Copy page

Get started

Quickstart

This page takes you from a new account to a working API request.

Create an account

Sign up at app.tomba.io/auth/register. New accounts start on the free plan; its monthly allowance is listed in Credits and usage.

Get your API key and secret

Every request needs two credentials: an API key and your account secret.

1. Open API keys in the dashboard.
2. Create a key, or copy an existing one. Keys start with ta_.
3. Copy your secret from the same page. The secret starts with ts_.
4. Store both as environment variables so they stay out of your code:

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

Keys expire. See Authentication for expiry and rotation.

Make your first request

Find the email addresses Tomba knows for a company domain:

Code
curl "https://api.tomba.io/v1/domain-search?domain=stripe.com" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

A successful response returns the company in data.organization, the email addresses in data.emails, and paging information in meta. Trimmed, it looks like this:

Code
{
    "data": {
        "organization": {
            "website_url": "stripe.com",
            "organization": "Stripe",
            "location": {
                "country": "US",
                "city": "San Francisco",
                "state": "California"
            },
            "industries": "Financial Services",
            "pattern": "{first}",
            "accept_all": false
        },
        "emails": [
            {
                "email": "john@stripe.com",
                "first_name": "John",
                "last_name": "Doe",
                "position": "Software Engineer",
                "department": "engineering",
                "type": "personal",
                "score": 90,
                "verification": {
                    "date": "2025-01-15T00:00:00Z",
                    "status": "valid"
                }
            }
        ]
    },
    "meta": { "total": 1250, "pageSize": 10, "current": 1, "total_pages": 125 }
}

Company response and Person response describe every field.

If the request fails, the response contains an errors object instead. Errors lists every error type and what to do about it. Every endpoint, with its parameters and response schema, is in the API reference.

Dashboard

Before you send volume, read Rate limits, Credits and usage, and Going to production.