Step by Step Guide to Building a WhatConverts API Integration in Ruby

Aug 16, 2024 • 6 minute read

Introduction

Hey there, fellow Ruby enthusiast! Ready to dive into the world of WhatConverts API integration? You're in for a treat. WhatConverts is a powerful lead tracking and reporting platform, and their API opens up a whole new realm of possibilities. We'll be using the whatconverts Ruby gem to make our lives easier, so buckle up!

Prerequisites

Before we jump in, make sure you've got:

Ruby 2.5 or higher (you're living on the edge, right?)
WhatConverts API credentials (if you don't have these, go grab 'em from your WhatConverts dashboard)

Installation

Let's kick things off by installing the gem. It's as easy as pie:

gem install whatconverts

Configuration

Now, let's set up our API credentials and initialize the client. It's like making a new friend, but cooler:

require 'whatconverts'

client = WhatConverts::Client.new(
  api_key: 'your_api_key',
  account_id: 'your_account_id'
)

Basic API Operations

Fetching Leads

Time to get those leads! It's like fishing, but for data:

leads = client.leads.list
puts leads

Creating a New Lead

Got a hot new lead? Let's add it to the mix:

new_lead = client.leads.create(
  name: 'John Doe',
  phone: '1234567890',
  email: '[email protected]'
)

Updating Lead Information

People change, and so do leads. Let's update that info:

updated_lead = client.leads.update(lead_id, { name: 'Jane Doe' })

Deleting a Lead

Sometimes, we need to let go. Here's how to delete a lead:

client.leads.delete(lead_id)

Advanced Usage

Filtering and Sorting Leads

Let's get picky with our leads:

filtered_leads = client.leads.list(
  filters: { status: 'new' },
  sort: { field: 'created_at', direction: 'desc' }
)

For when you've got more leads than you can handle in one go:

page_1 = client.leads.list(page: 1, per_page: 50)
page_2 = client.leads.list(page: 2, per_page: 50)

Error Handling

Because sometimes things don't go as planned:

begin
  client.leads.get(non_existent_id)
rescue WhatConverts::Error => e
  puts "Oops! #{e.message}"
end

Best Practices

Respect rate limits: WhatConverts isn't a fan of spam. Be cool.
Cache when you can: Your future self will thank you.

Example Project

Here's a little script to tie it all together:

require 'whatconverts'

client = WhatConverts::Client.new(api_key: 'your_api_key', account_id: 'your_account_id')

# Fetch and display recent leads
recent_leads = client.leads.list(
  filters: { created_at: { from: '2023-01-01' } },
  sort: { field: 'created_at', direction: 'desc' },
  per_page: 10
)

puts "Recent Leads:"
recent_leads.each do |lead|
  puts "#{lead.name} - #{lead.email}"
end

# Create a new lead
new_lead = client.leads.create(
  name: 'Ruby Rockstar',
  email: '[email protected]',
  phone: '1234567890'
)
puts "\nNew lead created: #{new_lead.name}"

# Update the lead
updated_lead = client.leads.update(new_lead.id, { status: 'qualified' })
puts "Lead updated: #{updated_lead.name} is now #{updated_lead.status}"

Troubleshooting

Hit a snag? Here are some common issues:

Authentication errors: Double-check your API credentials.
Rate limiting: Slow down, speed racer! Implement some delays between requests.
Unexpected data: Make sure you're sending the right data formats.

Conclusion

And there you have it! You're now equipped to wrangle the WhatConverts API like a pro. Remember, the API documentation is your friend, so don't be shy about diving deeper. Now go forth and convert those leads!

Happy coding, Rubyist! 🚀💎