Copy page

SDKs

Elixir SDK

The tomba Hex package is the official Elixir client for the Tomba API. Each API area is a module, each function sends one request, and every function returns {:ok, result} or {:error, %Tomba.Error{}}.

Requirements

• Elixir 1.12 or later, as declared in mix.exs.
• httpoison and jason, installed as dependencies.

Install

Add the package to your dependencies in mix.exs:

Code
def deps do
  [
    {:tomba, "~> 1.0"}
  ]
end

Then run mix deps.get.

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 Tomba.client/3, and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. The optional third argument takes :timeout in milliseconds (default 120_000) and :base_url. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
client = Tomba.client(System.fetch_env!("TOMBA_API_KEY"), System.fetch_env!("TOMBA_SECRET_KEY"))

{:ok, result} =
  Tomba.Finder.email_finder(client, %{
    "domain" => "stripe.com",
    "first_name" => "Jane",
    "last_name" => "Doe"
  })

IO.puts(result.data["data"]["email"])

Run a script like this one in your project with mix run first.exs. Functions take their parameters as a map with string keys, named as in the API reference. result is a map with two keys: :data, the decoded 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

Functions return {:error, %Tomba.Error{}}, rather than raising, when the API responds with a status outside 200 to 299 or the request fails.

Code
client = Tomba.client(System.fetch_env!("TOMBA_API_KEY"), System.fetch_env!("TOMBA_SECRET_KEY"))

params = %{"domain" => "stripe.com", "first_name" => "Jane", "last_name" => "Doe"}

case Tomba.Finder.email_finder(client, params) do
  {:ok, result} ->
    IO.puts(result.data["data"]["email"])

  {:error, %Tomba.Error{} = error} ->
    IO.puts("#{error.status_code} #{error.message}")
    IO.puts(get_in(error.response, [:data, "errors", "type"]))
end

A function called with a map that lacks a required key, such as "domain" for email_finder, raises FunctionClauseError without sending a request. Tomba.Enrichment.person/2, company/2, and combined/2 return {:ok, result} when nothing is found: those endpoints answer with status 200 and an errors body, so check result.data["errors"]. 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 that are present, keyed by lowercase header name, with string values: "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".

On a 429, read the wait time from error.response.rate_limit["retry-after"] and retry as described in Handle 429 responses.

Method reference

Every function takes the client as its first argument. Map arguments list the keys the function requires.

bulk_type is the {type} segment listed in Bulk types (Tomba.Bulk.valid_bulk_types/0 returns them); the order of calls is described in Lifecycle. Tomba.Bulk.create/3 sends a JSON body, so it can't create jobs that need a CSV upload, such as email finder jobs. Tomba.Bulk.download/3 returns the results file, a CSV, as a string in result.data.

Source

github.com/tomba-io/elixir (Apache-2.0).