Copy page

SDKs

R SDK

The tomba package is the official R client for the Tomba API. Every function takes a Tomba client object and sends one request. This page describes version 1.1.0, which is available from GitHub.

Requirements

• R 3.5.0 or later, as declared in DESCRIPTION.
• The httr and jsonlite packages, installed as dependencies.

Install

Code
install.packages("remotes")
remotes::install_github("tomba-io/r")

CRAN has version 1.0.1. It has only account, autocomplete, count, domain_search, email_finder, email_sources, email_verifier, logs, status, and usage, and those return the response body directly, without the data and rate_limit wrapper described below.

Authenticate

Create an API key and copy your secret on the API keys page, then export both, or set them in ~/.Renviron:

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

The package doesn't read environment variables itself. Pass the values as Tomba(key = ..., 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
library(tomba)

client <- Tomba(key = Sys.getenv("TOMBA_API_KEY"), secret = Sys.getenv("TOMBA_SECRET_KEY"))

result <- email_finder(client, domain = "stripe.com", fname = "Jane", lname = "Doe")
print(result$data$data$email)

Every function returns a list with two elements: data, the response body parsed with jsonlite::fromJSON, 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

When the API responds with status 400 or higher, the function signals an R error whose message is Tomba API error <status>: <response body>. Catch it with tryCatch:

Code
library(tomba)

client <- Tomba(key = Sys.getenv("TOMBA_API_KEY"), secret = Sys.getenv("TOMBA_SECRET_KEY"))

result <- tryCatch(
  email_finder(client, domain = "stripe.com", fname = "Jane", lname = "Doe"),
  error = function(e) {
    message(conditionMessage(e))
    NULL
  }
)
if (!is.null(result)) print(result$data$data$email)

The response body in the message is the JSON error, {"errors":{"type":…,"message":…,"code":…}}. Each errors.type is described in Errors. person_find, company_find, and combined_find don't signal an error when nothing is found: those endpoints answer with status 200 and an errors body, so check result$data$errors.

Rate limits and retries

The package doesn't retry. result$rate_limit is a named list of the response's rate limit headers that are present, with character 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.

A 429 signals an error without the response headers. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds; the timeout isn't configurable.

Method reference

Every function takes the client as obj, its first argument.

bulk_type is the {type} segment listed in Bulk types; the order of calls is described in Lifecycle. create_bulk 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/r (Apache-2.0).