Schemas

Natural-language description of the companies you want, 8 to 100 characters. Filters are generated from it on every request, so use it for the first request and send the returned meta.filters as filters for the next pages.

Structured filters for company search. Every filter is optional, and a company must match all the filters you send. Most values are matched against Tomba's company data, which isn't normalized to a fixed list; size, founded, and revenue accept only the values listed for them and ignore any other value.

Page number. Each page has up to 50 companies. On the Free plan outside a workspace, any page after the first returns page 1.

Company domains, such as stripe.com.

Two-letter country codes (ISO 3166-1 alpha-2), such as US.

City names, such as San Francisco.

State or region names, such as California.

Industries, such as financial services.

Employee count ranges: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, or 10001+.

Company types, such as private or public.

Keywords matched against each company's name, industry, keywords, and description.

Founding years, such as 2015, or ranges: before 1990, 1990-1999, 2000-2009, 2010-2019, or 2020+. exclude isn't supported.

Technology names, such as React.

Reference domains, such as stripe.com, to find similar companies. exclude isn't supported.

Annual revenue ranges: 0-1m, 1m-10m, 10m-50m, 50m-100m, or 100m+.

Four-digit SIC codes, such as 7372. See SIC codes.

Six-digit NAICS codes, 2017 or 2022 edition, such as 522320. See NAICS codes.

Values to include.

Values to exclude.

Values to include. A company matches when it matches any of them.

Values to exclude.

Always true.

One page of companies, up to 50.

Paging, and the filters the search used.

Number of companies that match.

The page returned. 0 if the search fails.

Companies per page. Always 50.

Number of pages.

The filters the search used: the ones you sent, or the ones generated from query. Only filters that were set appear. Send them as filters to get more pages of the same search.

The companies on this page, most popular domain first, or most relevant first when you filter by keywords. null if the search fails.

Company name.

Short description of the company.

Two-letter country code (ISO 3166-1 alpha-2) of the headquarters.

State or region.

City.

Street address.

Postal code.

Industry. Free text; not a fixed list.

Employee count range, such as 51-200. Free text; not a fixed list.

Company type. Currently always an empty string.

Year the company was founded.

Company domain, such as stripe.com.

Number of email addresses Tomba has for the domain.

Estimated annual revenue range. Free text; not a fixed list.

Whether Tomba has a phone number for the company. Currently always false.

LinkedIn company page URL, such as https://linkedin.com/company/stripe.

Facebook page URL, such as https://facebook.com/StripeHQ.

Twitter (X) profile URL, such as https://x.com/stripe.

Number of similar companies Tomba has for the domain.

Your account, plan, and credit usage in the current usage window.

The company and its email addresses.

Paging for the email addresses, and the request as the API read it.

The person and their email address.

URL of the page where the address was found.

Host name of that page, such as stripe.com.

When Tomba first found the address on the page, in RFC 3339 format.

When Tomba last saw the address on the page, in RFC 3339 format.

true if the address was on the page when Tomba last checked it.

When Tomba last checked the address, in RFC 3339 format.

Result of the last check: valid, accept_all, invalid, or unknown. See Status values.

true if the number is valid in its country's numbering plan.

National format, such as (415) 555-0132.

International format, such as +1 415-555-0132.

E.164 format, such as +14155550132.

RFC 3966 URI, such as tel:+1-415-555-0132.

Two-letter country code (ISO 3166-1 alpha-2) of the number.

Line type. FIXED_LINE_OR_MOBILE means the numbering plan doesn't distinguish landlines from mobiles; for US, Canadian, and Mexican numbers Tomba replaces it with MOBILE, FIXED_LINE, VOIP, or TOLL_FREE when the number's block is classified. Voicemail numbers are reported as UNKNOWN. See Line types.

Carrier the number was assigned to. Empty when unknown.

State or province of the number. null when the number doesn't identify one.

IANA time zones of the number, such as America/Los_Angeles.

Phone finder only. The email address the number was found for. Left out when empty.

Phone finder only. The domain the number was found for. Left out when empty.

Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty.

The verification result.

A person in Clearbit's field format. Fields Tomba doesn't fill are always null: timeZone, utcOffset, bio, site, avatar, fuzzy, emailProvider, activeAt, inactiveAt, geo.city, geo.state, geo.stateCode, geo.lat, geo.lng, employment.subRole, employment.seniority, facebook.handle, every github and gravatar field, and every twitter field except handle. See Clearbit-compatible enrichment.

The lookup.

A company in Clearbit's field format. Fields Tomba doesn't fill are always null: domainAliases, timeZone, utcOffset, logo, ticker, identifiers.usEIN, category.sector, category.industryGroup, category.industry, category.subIndustry, geo.subPremise, geo.lat, geo.lng, facebook.likes, every twitter field except handle, metrics.alexaUsRank, metrics.alexaGlobalRank, metrics.marketCap, metrics.raised, metrics.fiscalYearEnd, parent.domain, and ultimateParent.domain. See Clearbit-compatible enrichment.

The lookup.

The person and the company.

The lookup.

The counts.

Tomba's internal ID for the domain's company record. 0 when Tomba has no record of the domain.

One entry per country, in no particular order. An empty array when Tomba has no location data for the domain.

The sources, at most 20. An empty array, with status 201, when Tomba has none.

The address you asked about, trimmed and in lowercase.

Up to 20 formats, in no particular order. An empty array when Tomba has no formats for the domain.

Similar companies. null when Tomba has none for the domain.

Paging.

One entry per technology. null when Tomba has no technology data for the domain.

The domain you asked about. Left out when data is null.

One phone number, or an array of phone numbers. An empty array when nothing is found.

The email you sent, in lowercase. Only in a response without results.

The domain you sent, normalized. Only in a response without results.

The linkedin profile you sent, reduced to its permalink, such as jane-doe. Only in a response without results.

Lead ID.

User who saved the lead.

Email address, in lowercase. Empty when the lead was saved without one.

ID of the lead's list.

First name.

Last name.

Two-letter country code, for example US.

Company domain.

Job title.

Twitter profile URL.

LinkedIn profile URL.

Phone number.

Company name.

Notes.

Where the lead came from: domain (domain search), finder (email finder), verify (email verifier), or browser (browser extension).

Lead score, up to 100.

State of the last sync to a connected app: pending, error, or success.

Whether the lead was synced to Airtable.

Whether the lead was synced to HubSpot.

Whether the lead was synced to Mailchimp.

Whether the lead was synced to Pipedrive.

When the lead was saved.

When the lead was last changed.

The lead's list. Every field is null when the lead isn't in a list you can see.

Custom attribute values, keyed by the attribute's identifier. Values are strings. Empty when the lead has none. At most 25 are returned.

Attribute ID.

User who created the attribute.

Attribute name.

Key for the attribute's values in a lead's attributes: the name as a lowercase slug, so Deal size becomes deal-size.

Value type: string, date, or number.

When the attribute was created.

When the attribute was last changed.

List ID.

User who created the list.

Number of leads in the list. It's a counter updated as leads are added, moved, and deleted, so it can differ from the number of leads GET /leads?list= returns.

List name.

Whether the list is marked as a favorite.

When the list was created.

When the list was last changed.

List type. Lists created with this API have campaigns. Absent when empty.

Key ID.

User ID of the key's owner. A key authenticates as its owner, and its requests are charged to the owner.

The key value, ta_ followed by 37 characters. Send it as X-Tomba-Key.

Label for the key.

IP address the key was created or last rotated from.

When the key was created.

When the key was last changed.

true when the key is yours, false when it belongs to a workspace teammate.

Whether the key is past its expiry date.

When the key stops working. Requests with an expired key fail with 400 api_key_expired. Absent for the rare keys without an expiry date.

User ID of whoever created the key. Absent on older keys.

Last time the key authenticated a request, updated at most once an hour. Absent if the key hasn't been used.

Whole days until the key expires, negative once it has expired. Absent when expires_at is absent.

Name of whoever created the key, or their email address when they have no name. Absent when the creator is unknown.

Email address of whoever created the key. Absent when the creator is unknown.

Profile image URL of whoever created the key. Absent when there's none.

One row per user and day with charged credits, oldest first. Days without charged credits have no row. The source_* counters split the day's credits, of every type, by where the requests came from. null when the range has no rows.

Sums over the rows in data. There's no email_count total.

Log row ID.

User who made the request.

https://api.tomba.io plus the path for the lookup's type, without query parameters. It can differ from the path you called, which is in endpoint. Empty when the type isn't recognized.

The request's query parameters and top-level JSON body fields, as strings.

Name of the lookup type, for example Domain Search, Email Finder, or Email Verification. Some bulk download rows show the credit type instead: search or verifier.

Fingerprint of the request's parameters. Tomba uses it to recognize a repeat of a lookup already charged in the current usage window.

Credits charged. 0 for a repeat of a lookup already charged in the current usage window.

Where the request came from: API, Website, Browser extension, Google Sheets add-on, Bulk API, or MCP Agent.

Two-letter country code of the caller's IP address. Empty when unknown.

The request's User-Agent header.

The caller's IP address.

When the request was made.

Internal route name, for example domain-search, enrich-finder, or SearchCompanies. Absent on older rows.

HTTP method. Absent on older rows.

HTTP status of the response, always 200. Absent on older rows.

Request ID, on rows that recorded one. Rows logged by the current API don't record it, so the field is usually absent.

Path you called, for example /v1/domain-search. Absent on older rows.

ID of the API key that made the request. Absent for requests made with an OAuth access token or from the dashboard.

Time Tomba took to handle the request, in milliseconds. Absent on older rows.

Result of an update or delete.

Error details object used in reusable error responses.

Job name, 3 to 200 characters. Required, except for a domain export, which is named after its domain.

One value per line, or a JSON array of values. Tomba trims, lowercases, and de-duplicates the values, drops the invalid ones, and keeps the first ones up to the type's row limit. Not accepted by finder.

Rows of cells, for input with several columns. The first row is a header unless has_header is false. In a multipart form, send it as a JSON-encoded string.

Whether the first row of data or of the file is a header. A list has no header.

Column separator of the uploaded file: ,, ;, |, or tab. Any other value is read as ,.

The domain to export. Required for export, and used by no other type.

Zero-based column of the domain or website. Used by search, similar, company, finder, and phone-finder.

Zero-based column of the company name. Used by search, similar, company, and finder.

Zero-based column of the first name. Used by finder.

Zero-based column of the last name. Used by finder.

Zero-based column of the full name. Used by finder.

Zero-based column of the email address. Used by enrich, verifier, and phone-finder.

Zero-based column of the LinkedIn profile URL. Used by linkedin and phone-finder.

Zero-based column of the article URL. Used by author.

Zero-based column of the phone number. Used by phone-validator.

Zero-based column of the country code. Used by phone-validator.

Zero-based column of the technology slug. Used by technology.

Used by search, similar, and company: whether the input is domains or company names. Defaults to company when the input has a company name column and no domain column, and to domain otherwise.

Used by search and similar. Addresses returned per domain.

Used by search. With email_type_mode only, only addresses of this type are returned.

only returns only the addresses of email_type; priority returns every type.

Used by search. With departments_mode only, only addresses in these departments are returned.

only returns only the addresses in departments; priority returns every department.

Used by search: verifies the addresses found. It is turned off, without an error, when max_emails_per_domain is above 10 or the input has more than 2,000 rows. similar, company, finder, enrich, linkedin, and author accept it, but it only adds verification credits there; see Billing.

Adds phone numbers, at an extra cost. Used by search, company, finder, enrich, linkedin, verifier, and export.

Adds the web pages where each address was found. Used by search, finder, enrich, linkedin, author, verifier, and export.

Used by search. Adds 10 points, up to 90, to the score of an address that couldn't be verified but was found on at least 5 web pages.

Used by finder. Skips the rows that already have a value in a column named email.

Used by phone-finder. Returns every phone number found instead of one.

Used by export. The addresses to export, by type or by department.

Emails you when the job finishes with at least one result.

Launches the job right after creating it. If it can't start, it stays pending and data.message in the response says why. A domain export always starts.

An https:// URL that receives an event when the job completes, fails, or is cancelled. At most 2,048 characters, without a username or password, on a host with a public IP address. See Bulk job events.

Job ID.

ID of the user who created the job.

The job's type. Phone finder jobs are phone.

pending until launched, then running. completed, failed, and cancelled are final.

Percentage of the rows processed.

Rows processed.

Whether the results were downloaded, which charges the job, once.

Why the job failed.

How many times the job was retried.

Whether expired_at has passed. An expired job can no longer be downloaded, launched, or retried.

180 days after created_at. Download the results before this date.

The job's input and options, as set when it was created.

The job's results. They are updated while the job runs (partial is true) and final once it completes.

The first rows of the results, once billed is true; an empty array before. Their fields depend on the type.

Version of this document. Currently 1.

The options, with their defaults filled in. See POST /bulk/{type} for each one.

Whether an email is sent when the job finishes with results.

Where job events are sent. Absent without webhook_url.

technology only: your search balance when the job was created, which caps the websites returned per technology.

Version of this document. Currently 1.

true while the job is running.

Only the distributions that apply to the type are present.

Types that return email addresses only.

Types that return phone numbers only.

Credits of a job. Phone data is billed as search credits: phone is included in search, and total is search plus verify.

pending until the job is launched. completed, failed, and cancelled are final.

Percentage of the rows processed.

Rows processed so far.

Why the job failed.

Processing speed. null until enough rows are processed.

Estimated seconds until the job completes. null until enough rows are processed.

The job's results. They are updated while the job runs (partial is true) and final once it completes.

upper_bound before the job completes, exact after.

Whether the job was already charged. Later downloads are free.

Rows to process.

Credits of a job. Phone data is billed as search credits: phone is included in search, and total is search plus verify.

Your remaining search and verification credits.

Whether your remaining credits cover credits. Always true once billed.

The user who acted, or null for Tomba.

Why the job failed, for failed events.

Details of the event, such as the row counts of created, the file and whether it was billed for downloaded, or the attempt and HTTP status of a webhook delivery.

The bulk_type of its jobs.

The {type} in its URLs.

Its page in the web app, under https://app.tomba.io/bulk/.

Whether it accepts a file.

Whether it needs data or file, and refuses a list.

The field a list or a single column is read as.

The options it accepts.

Whether its jobs start when created.

The result files it can have.

The metrics.distribution keys it fills.

Search credits per phone number found.

Jobs created in the period, by status.

Credits of a job. Phone data is billed as search credits: phone is included in search, and total is search plus verify.

whsec_ followed by the base64-encoded key.

Always true.

What was done.

Always 200.

New name of the job, 3 to 200 characters.

Total number of items

Items per page

Current page number

Total number of pages

Machine-readable error type.

Human-readable error message.

HTTP status code associated with the error.

Suggested companies. An empty array when nothing matches, null if the lookup fails.

The query and the maximum number of suggestions.

Company name.

Company domain.

Number of email addresses Tomba has for the domain.

Your query, trimmed and in lowercase. Empty if the lookup fails.

Maximum number of suggestions. Always 5, or 0 if the lookup fails.

One result, or an array of results with full=true.

The email address. null when no address is found.

First name.

Last name.

First and last name.

Company domain, such as stripe.com.

Company name.

Format of the address, such as {first}.{last}. null with full=true. See Patterns.

Department, such as engineering. Empty when unknown, null with full=true. See Departments.

personal for an address that belongs to one person, generic for a role address. null with full=true.

Job title.

Two-letter country code (ISO 3166-1 alpha-2).

male or female.

Twitter (X) profile URL.

LinkedIn profile URL.

Confidence from 0 to 100 that the address is correct, based on its last verification result and the number of public sources that list it. 0 when no address is found.

true when the domain's mail server accepts mail for any address (catch-all).

true when Tomba has a phone number for the person. Set enrich_mobile=true to get it in phone_data.

Public pages where the address appears. null when no address is found.

Result of Tomba's last check of the address. Both fields are null when Tomba hasn't checked it.

Phone numbers for the person when you set enrich_mobile=true, otherwise an empty array. Left out when no address is found, with full=true, and for an address found by a live check.

URL of the page where the address was found.

Host name of that page, such as stripe.com.

When Tomba first found the address on the page, in RFC 3339 format.

When Tomba last saw the address on the page, in RFC 3339 format.

true if the address was on the page when Tomba last checked it.

When Tomba last checked the address, in RFC 3339 format.

Result of the last check.

The article's author and their email address.

The article URL.

Article title.

URL of the article's Open Graph image.

Article description.

Domain that hosts the article.

Name of the publication.

Publication date, as it appears on the page.

People named as the author on the page, best match first. null when none were found.

What you're reporting.

The item you're reporting, such as the email address, domain, phone number, or URL.

Why the data is wrong. Each flag_type accepts its own reasons, and any other combination fails with 422:

• email: hard_bounce, invalid_email, wrong_person, outdated, other
• organization: wrong_company, outdated, other
• phone: wrong_phone, outdated, other
• author_url: broken_url, wrong_person, outdated, other
• website: broken_url, wrong_company, outdated, other

Only an email report with hard_bounce can return a credit, once Tomba confirms it.

Details that help Tomba review the report, such as the bounce message your mail server received.

Report ID.

What was reported.

The reported item.

Why the data was reported.

Review status. A new report is pending until Tomba confirms or rejects it.

Credits returned for the report: 1 when Tomba confirmed an email report with the reason hard_bounce and returned a search credit, otherwise 0.

When you submitted the report.

Your comment. Absent when you didn't send one.

When Tomba reviewed the report. Absent until then.

Your reports, one page at a time.

One entry per route name. The response always has these 21 keys: domain-search, email-finder, email-verifier, email-count, email-sources, email-format, author-finder, enrich, linkedin, phone, phone-validator, similar, technology, domain-suggestions, me, searches, location, enrich-email, enrich-company, enrich-combined, and reveal.

Most keys match the endpoint path. The others:

• phone covers /phone-finder.
• enrich-email, enrich-company, and enrich-combined cover /people/find, /companies/find, and /combined/find.
• searches covers searches made in the Tomba dashboard.
• reveal is listed but not enforced, so its usage is always 0. /reveal/search has a fixed limit instead.

Requests per second.

Requests per minute.

Requests per day. The day runs from 00:00 UTC.

The number's details, or an empty array when the number isn't valid.

The phone you sent. Only in the response for a number that isn't valid.

The person's name.

The email address.

Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here.

male or female.

Always null.

Always null.

Location. Only country and countryCode are filled.

Always null.

Always null.

Always null.

Current employer and job.

Facebook profile. handle is always null.

Every field is always null.

Twitter (X) profile. Only handle is filled.

LinkedIn profile.

Every field is always null.

true when Tomba has a phone number for the person.

Always null.

Always null.

When Tomba last updated the record, in RFC 3339 format.

Always null.

Always null.

Result of Tomba's last check of the address. Both fields are null when Tomba hasn't checked it.

Company name.

Same value as name.

The domain.

Always null.

Contact details found on the website.

Industry codes. sector, industryGroup, industry, and subIndustry are always null.

Keywords that describe the company.

Short description of the company.

Year the company was founded, as a string.

Two-letter country code (ISO 3166-1 alpha-2) of the headquarters.

Always null.

Always null.

Headquarters address.

Always null. Use the Logo API.

Facebook page.

LinkedIn company page.