Copy page

SDKs

Ruby SDK

The tomba gem is the official Ruby client for the Tomba API. Each API area is a service class in the Tomba module, and each method sends one request.

Requirements

Ruby 2.5 or later, as declared in the gemspec. The gem uses only the standard library.

Install

Code
gem install tomba

Or add gem 'tomba' to your Gemfile.

Authenticate

Create an API key and copy your secret on the API keys page, then export both:

Code
export TOMBA_API_KEY="ta_xxxx"
export TOMBA_SECRET_KEY="ts_xxxx"

The SDK doesn't read environment variables. Pass the values to set_key and set_secret, and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
require 'tomba'

client = Tomba::Client.new
client.set_key(ENV.fetch('TOMBA_API_KEY')).set_secret(ENV.fetch('TOMBA_SECRET_KEY'))

finder = Tomba::Finder.new(client)
result = finder.email_finder(domain: 'stripe.com', first_name: 'Jane', last_name: 'Doe')
puts result['data']['data']['email']

Every method returns a hash with two keys: 'data', the parsed JSON body, and 'rate_limit'. The API wraps its payload in its own data object (Response format), so the address is at result['data']['data']['email'].

Errors

The SDK raises Tomba::Exception when the API responds with status 400 or higher, when the body isn't JSON, when the connection fails, and before sending a request when a required argument is nil.

Code
require 'tomba'

client = Tomba::Client.new
client.set_key(ENV.fetch('TOMBA_API_KEY')).set_secret(ENV.fetch('TOMBA_SECRET_KEY'))

begin
  finder = Tomba::Finder.new(client)
  result = finder.email_finder(domain: 'stripe.com', first_name: 'Jane', last_name: 'Doe')
  puts result['data']['data']['email']
rescue Tomba::Exception => e
  puts "#{e.code} #{e.message}"
  puts e.response['errors']['type'] if e.response
end

Each errors.type is described in Errors.

Rate limits and retries

The SDK doesn't retry. result['rate_limit'] holds the response's rate limit headers, keyed by header name: x-second-rate-limit, x-minute-rate-limit, x-daily-rate-limit, x-minute-request-left, x-daily-request-left, x-minute-reset-seconds, x-daily-reset-seconds, retry-after, ratelimit-policy, and ratelimit. Numbers are integers, and a header that is absent is nil.

A 429 raises Tomba::Exception with code 429, without the response headers. Wait before retrying as described in Handle 429 responses.

Connections and reads time out after 120 seconds; the timeouts aren't configurable.

Method reference

Create each service with the client, for example Tomba::Finder.new(client). Arguments shown as name: are keyword arguments.

type is the {type} segment listed in Bulk types. Bulk#create sends a JSON body, so it can't create jobs that need a CSV upload, such as email finder jobs.

Source

github.com/tomba-io/ruby (Apache-2.0). Release notes are in CHANGES.