Copy page

SDKs

Python SDK

tomba-io is the official Python client for the Tomba API. Each API area is a service class, and each method sends one request.

Requirements

• Python 3.8 or later. The package declares no minimum version; its CI tests Python 3.8 to 3.12.
• requests, installed as a dependency.

Install

Code
pip install tomba-io

The import name is tomba.

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
import os

from tomba import Client, Finder

client = Client()
client.set_key(os.environ["TOMBA_API_KEY"]).set_secret(os.environ["TOMBA_SECRET_KEY"])

result = Finder(client).email_finder("stripe.com", "Jane", "Doe")
print(result["data"]["data"]["email"])

Every method returns a dict 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

The SDK raises TombaException when the API responds with status 400 or higher, when the request fails, and before sending a request when a required argument is None.

Code
import os

from tomba import Client, Finder, TombaException

client = Client()
client.set_key(os.environ["TOMBA_API_KEY"]).set_secret(os.environ["TOMBA_SECRET_KEY"])

try:
    result = Finder(client).email_finder("stripe.com", "Jane", "Doe")
except TombaException as error:
    print(error.code, error.message)
    if error.response:
        print(error.response["errors"]["type"])
else:
    print(result["data"]["data"]["email"])

Enrichment.person(), company(), and combined() don't raise when nothing is found: those endpoints answer with status 200 and an errors body, so check result["data"].get("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 as second_limit, minute_limit, daily_limit, minute_remaining, daily_remaining, minute_reset, daily_reset, retry_after, policy, and rate_limit. Numbers are integers, and a header that is absent or 0 becomes None.

A 429 raises TombaException with code 429, without the Retry-After header. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds. Change the timeout with client.set_timeout(seconds).

Method reference

Create each service with the client, for example Finder(client). Every class is importable from tomba. IDs are strings.

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. download_bulk returns the results file, a CSV, as bytes in result["data"].

Source

github.com/tomba-io/python (Apache-2.0). Release notes are in CHANGELOG.md.