# Tomba - **OpenAPI Version:** `3.1.1` - **API Version:** `1.0.0` The Tomba API finds, verifies, and enriches professional email addresses, phone numbers, and company data over REST. ## Getting started Send every request with your API key and secret in the `X-Tomba-Key` and `X-Tomba-Secret` headers. Create both in the [dashboard](https://app.tomba.io/api); see [Authentication](https://docs.tomba.io/authentication). ```sh curl 'https://api.tomba.io/v1/email-finder?domain=stripe.com&first_name=Jane&last_name=Doe' \ -H "X-Tomba-Key: $TOMBA_API_KEY" \ -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" ``` ## Base URL and versioning All endpoints are served from `https://api.tomba.io/v1`. Backward-compatible changes ship without a new version path. ## Rate limits and credits Limits are enforced per plan and per endpoint. Rate-limited endpoints return rate-limit headers on every response, and a request over a limit returns `429 Too Many Requests` with a `Retry-After` header. See [Rate limits](https://docs.tomba.io/rate-limits) for the limits and headers, and [Credits and usage](https://docs.tomba.io/usage-and-quotas) for what each endpoint costs. ## Errors Missing, malformed, or expired credentials return `400` with an `errors.type` of `authentication_failed` or `api_key_expired`; credentials that don't match an account return `401`. Branch on `errors.type`, not on the status code alone. See [Errors](https://docs.tomba.io/error-handling). ## Timeouts Set a client timeout of at least 180 seconds. Searches and verifications run in real time against remote mail servers and websites, so response times vary. For large volumes, use [bulk jobs](https://docs.tomba.io/bulks). ## MCP server AI assistants can use the same data through the MCP server at `https://mcp.tomba.io/mcp`. See [Remote MCP server](https://docs.tomba.io/llm/remote-mcp/introduction). ## Servers - **URL:** `https://api.tomba.io/v1` - **Description:** Production server ## Operations ### Get Account - **Method:** `GET` - **Path:** `/me` - **Tags:** Account Returns your account, your plan, and your credit usage in the current usage window. - `requests.domains`, `requests.verifications`, and `requests.count` hold your search, verification, and email count allowances (`available`) and what you've used (`used`). The remaining balance is `available` minus `used`. - `issued` and `expired` bound the current usage window. `expired_subscription` is when the subscription period ends. - `pricing.available_searches` and `pricing.available_verifications` include your unused credit-pack credits, which `addon_credits` lists separately. - `secret_token` is your API secret. Don't log or share this response. This endpoint is rate-limited per plan under the route name `me`; see [Rate limits](https://docs.tomba.io/rate-limits). It also accepts an OAuth 2.0 access token with the `read` scope. See [Check usage](https://docs.tomba.io/usage-and-quotas#check-usage) for the other ways to track credits. #### Responses ##### Status: 200 Your account details. ###### Content-Type: application/json - **`data` (required)** `object` — Your account, plan, and credit usage in the current usage window. - **`activity` (required)** `boolean` — Notification setting for account activity emails. - **`blocked` (required)** `boolean` — Always \`false\` here. Requests from a blocked account fail with \`403\`. - **`confirmed` (required)** `boolean` — Whether your email address is confirmed. Until it is, the data endpoints return \`401\`. - **`country` (required)** `string | null` — Your country code, for example \`US\`. - **`created_at` (required)** `string`, format: `date-time` — When the account was created. - **`deleted` (required)** `boolean` — Always \`false\` here. Requests from a deleted account fail with \`403\`. - **`email` (required)** `string` — Your email address. - **`expired` (required)** `string`, format: `date-time` — End of the current usage window, when the counts in \`requests\` reset. - **`expired_subscription` (required)** `string`, format: `date-time` — When the current subscription period ends. - **`first_name` (required)** `string` — Your first name. - **`has_password` (required)** `boolean` — Whether the account has a password. An account without one, such as one created with Google sign-in, gets \`401\` from the data endpoints until a password is set. - **`image` (required)** `string` — Profile image URL. When you haven't uploaded an image, a Gravatar URL for your email address. - **`important_updates` (required)** `boolean` — Notification setting for important account emails. - **`intercom_user_jwt` (required)** `string` — Signed token for Tomba's in-app support chat. Not needed for API use. - **`ip` (required)** `string` — IP address the account was created from. - **`issued` (required)** `string`, format: `date-time` — Start of the current usage window. The \`used\` counts in \`requests\` start here. - **`last_name` (required)** `string` — Your last name. - **`newsletter` (required)** `boolean` — Notification setting for the newsletter. - **`onboarded` (required)** `boolean` — Whether you finished the dashboard's onboarding. - **`phone` (required)** `string | null` — Your phone number. - **`pricing` (required)** `object` — Your plan and its allowances. - **`auto_upgrade` (required)** `boolean | null` — Whether automatic upgrades to the next plan are turned on. - **`available_attr` (required)** `integer`, format: `int64` — Plan value for custom lead attributes. It isn't enforced: every account can create up to 29 attributes. - **`available_email_count` (required)** `integer`, format: `int64` — Email count credits per usage window, used by email count, email format, and location. - **`available_keys` (required)** `integer`, format: `int64` — Maximum number of unexpired API keys you can hold. While you have unused credit-pack credits, you can hold at least 25. - **`available_leads` (required)** `integer`, format: `int64` — Maximum number of leads you can store. - **`available_list` (required)** `integer`, format: `int64` — Maximum number of lead lists you can create. - **`available_searches` (required)** `integer`, format: `int64` — Search credits per usage window, including your unused credit-pack credits. For a workspace member, your individual search limit if the owner set one, otherwise the owner's allowance. - **`available_sources` (required)** `integer`, format: `int64` — Email sources lookups per usage window. - **`available_teams` (required)** `integer`, format: `int64` — Maximum number of workspace members. - **`available_technology` (required)** `integer`, format: `int64` — Plan value for technology lookups. It isn't enforced. - **`available_verifications` (required)** `integer`, format: `int64` — Verification credits per usage window, including your unused credit-pack credits. For a workspace member, your individual verification limit if the owner set one, otherwise the owner's allowance. - **`cancel_url` (required)** `string | null` — Legacy billing link for cancelling the subscription. - **`frequency` (required)** `string` — Billing frequency: \`monthly\`, \`yearly\`, or \`trial\`. - **`name` (required)** `string` — Plan name. A Free account with unused credit-pack credits shows \`Free + Credit Packs\`. - **`plan_full_access` (required)** `boolean | null` — Whether you can buy plans that need approval. - **`price_monthly` (required)** `string` — The plan's monthly list price. - **`price_yearly` (required)** `string` — The plan's yearly list price. - **`pricing_id` (required)** `integer` — Plan ID. - **`pw_customer` (required)** `string | null` — Legacy billing customer ID. - **`status` (required)** `string | null` — Subscription status, for example \`active\`. - **`stripe_customer_id` (required)** `string | null` — Stripe customer ID. - **`subscription_id` (required)** `string | null` — Billing subscription ID. - **`update_url` (required)** `string | null` — Legacy billing link for updating the payment method. - **`rate_limits`** `object` — Your plan's rate limits, merged with those of your credit packs, keyed by route name. A \`default\` key, when present, applies to routes without their own key. Absent when the plan has no rate-limit settings. For a workspace member, these are your own plan's limits, not the owner's limits that apply to your requests. \`GET /rate-limits\` returns the limits actually enforced. - **`product_updates` (required)** `boolean` — Notification setting for product update emails. - **`provider` (required)** `string` — How the account was created, for example \`local\` (email and password), \`google\`, \`github\`, \`linkedin\`, \`saml\`, or \`scim\`. - **`requests` (required)** `object` — Allowances and usage in the current usage window. \`available\` is the allowance, not what's left: the remaining balance is \`available\` minus \`used\`. For a workspace member, \`used\` counts only your own usage; the owner's pool is in \`workspace.owner.usage\`. - **`count` (required)** `object` — Email count credits, used by email count, email format, and location. \`available\` equals \`pricing.available\_email\_count\`. - **`available` (required)** `integer`, format: `int64` — Email count credit allowance. - **`used` (required)** `integer`, format: `int64` — Email count credits used in this window. - **`domains` (required)** `object` — Search credits. \`available\` equals \`pricing.available\_searches\`. - **`available` (required)** `integer`, format: `int64` — Search credit allowance. - **`used` (required)** `integer`, format: `int64` — Search credits used in this window. - **`verifications` (required)** `object` — Verification credits. \`available\` equals \`pricing.available\_verifications\`. - **`available` (required)** `integer`, format: `int64` — Verification credit allowance. - **`used` (required)** `integer`, format: `int64` — Verification credits used in this window. - **`role` (required)** `integer` — Internal account role. Accounts created by sign-up have \`2\`. - **`secret_token` (required)** `string` — Your API secret, the value you send as \`X-Tomba-Secret\`. All your API keys share this one secret. Treat it like a password. - **`timezone` (required)** `string | null` — Your time zone setting, for example \`America/New\_York\`. - **`title` (required)** `string | null` — Your job title. - **`user_id` (required)** `integer`, format: `int64` — Your user ID. - **`webmail` (required)** `boolean` — Always \`false\`. - **`weekly_digest` (required)** `boolean` — Notification setting for the weekly digest email. - **`addon_credits`** `object` — Your unused credit-pack credits. Absent when you have none. - **`search_credits` (required)** `integer`, format: `int64` — Unused search credits. - **`verification_credits` (required)** `integer`, format: `int64` — Unused verification credits. - **`onboarding_data`** `object` — Your answers to the dashboard's onboarding questions. Absent when there are none. - **`workspace`** `object` — Your workspace membership. Absent when you aren't in a workspace. - **`limit` (required)** `object` — Your individual credit limits in the workspace, set by the owner. \`null\` when there's no individual limit. - **`search` (required)** `integer | null`, format: `int64` — Your search credit limit. - **`verifier` (required)** `integer | null`, format: `int64` — Your verification credit limit. - **`name` (required)** `string` — Workspace name. - **`owner` (required)** `object` — The workspace owner's plan and usage. Filled in for members who aren't the owner; for the owner, every field is \`null\`. - **`available_searches` (required)** `integer | null`, format: `int64` — The owner's search credits per usage window. - **`available_teams` (required)** `integer | null`, format: `int64` — The owner's maximum number of workspace members. - **`available_verifications` (required)** `integer | null`, format: `int64` — The owner's verification credits per usage window. - **`frequency` (required)** `string | null` — The owner's billing frequency. - **`name` (required)** `string | null` — The owner's full name. - **`usage` (required)** `object` — Credits used in the owner's current usage window, the pool that members draw from. - **`search` (required)** `integer | null`, format: `int64` — Search credits used. - **`verifier` (required)** `integer | null`, format: `int64` — Verification credits used. - **`permissions` (required)** `object` — What your role allows. - **`bulk` (required)** `boolean` — Whether you can use bulk jobs. \`false\` for guests. - **`export` (required)** `boolean` — Whether you can export data. \`false\` for guests. - **`manage_members` (required)** `boolean` — Whether you can manage members. Owners and admins only. - **`manage_settings` (required)** `boolean` — Whether you can change workspace settings. Owners and admins only. - **`share_data` (required)** `boolean` — Whether you share data with the workspace. \`false\` for guests. - **`role` (required)** `string`, possible values: `"owner", "admin", "member", "guest"` — Your role in the workspace. - **`slug` (required)** `string` — Workspace slug. - **`sso_enabled` (required)** `boolean` — Whether single sign-on is set up for the workspace. - **`sso_enforced` (required)** `string`, possible values: `"none", "optional", "required"` — Whether members must sign in with single sign-on. - **`workspace_id` (required)** `integer`, format: `int64` — Workspace ID. - **`logo_url`** `string` — Workspace logo URL. Absent when there's no logo. **Example:** ``` { "data": { "user_id": 1, "email": "", "first_name": "", "last_name": "", "secret_token": "", "role": 1, "confirmed": true, "blocked": true, "phone": null, "image": "", "deleted": true, "provider": "", "timezone": null, "newsletter": true, "activity": true, "title": null, "country": null, "created_at": "", "ip": "", "has_password": true, "onboarded": true, "onboarding_data": { "propertyName*": "anything" }, "weekly_digest": true, "product_updates": true, "important_updates": true, "webmail": true, "issued": "", "expired": "", "expired_subscription": "", "pricing": { "name": "", "pricing_id": 1, "available_searches": 1, "available_verifications": 1, "available_leads": 1, "available_list": 1, "available_attr": 1, "available_keys": 1, "available_teams": 1, "available_technology": 1, "available_sources": 1, "available_email_count": 1, "frequency": "", "price_monthly": "", "price_yearly": "", "subscription_id": null, "status": null, "pw_customer": null, "stripe_customer_id": null, "update_url": null, "cancel_url": null, "auto_upgrade": null, "plan_full_access": null, "rate_limits": { "propertyName*": { "rps": 1, "rpm": 1, "daily": 1 } } }, "workspace": { "workspace_id": 1, "name": "", "slug": "", "logo_url": "", "role": "owner", "sso_enabled": true, "sso_enforced": "none", "permissions": { "share_data": true, "export": true, "bulk": true, "manage_members": true, "manage_settings": true }, "limit": { "search": null, "verifier": null }, "owner": { "name": null, "available_teams": null, "available_searches": null, "available_verifications": null, "frequency": null, "usage": { "search": null, "verifier": null } } }, "requests": { "domains": { "available": 1, "used": 1 }, "verifications": { "available": 1, "used": 1 }, "count": { "available": 1, "used": 1 } }, "addon_credits": { "search_credits": 1, "verification_credits": 1 }, "intercom_user_jwt": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Search Companies - **Method:** `POST` - **Path:** `/reveal/search` - **Tags:** Reveal Searches Tomba's company database with structured filters or a natural-language query, and returns 50 companies per page. When you send `query`, filters are generated from it with an AI model and any `filters` you send are ignored. The generated filters are returned in `meta.filters`; send them as `filters` to get the next pages without generating them again. Per-request webhooks aren't supported. This endpoint has a fixed rate limit instead of your plan's limits; see [Rate limits](https://docs.tomba.io/rate-limits#endpoints-with-fixed-limits). See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Request Body ##### Content-Type: application/json - **`filters`** `object` — 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`page`** `integer`, default: `1` — Page number. Each page has up to 50 companies. On the Free plan outside a workspace, any page after the first returns page 1. - **`query`** `string` — 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. **Example:** ``` { "query": "Real estate agencies in Europe", "filters": { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } }, "page": 1 } ``` #### Responses ##### Status: 200 One page of matching companies. ###### Content-Type: application/json - **`data` (required)** `object` — One page of companies, up to 50. - **`companies` (required)** `array | null` — The companies on this page, most popular domain first, or most relevant first when you filter by \`keywords\`. \`null\` if the search fails. - **`meta` (required)** `object` — Paging, and the filters the search used. - **`filters` (required)** `object` — 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`limit` (required)** `integer` — Companies per page. Always \`50\`. - **`page` (required)** `integer` — The page returned. \`0\` if the search fails. - **`pages` (required)** `integer` — Number of pages. - **`total` (required)** `integer` — Number of companies that match. - **`success` (required)** `boolean` — Always \`true\`. **Example:** ``` { "success": true, "data": { "companies": [ { "name": "", "description": "", "country": "", "state": "", "city": "", "street_address": "", "postal_code": "", "industry": "", "company_size": "", "type": "", "founded": "", "website_url": "", "total_emails": 1, "revenue": "", "phone_number": true, "linkedin_url": "", "facebook_url": "", "twitter_url": "", "total_similar": 1 } ] }, "meta": { "total": 1, "page": 1, "limit": 1, "pages": 1, "filters": { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A field failed validation, or filters couldn't be generated from \`query\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Domain Search - **Method:** `GET` - **Path:** `/domain-search` - **Tags:** Finder Returns the company behind a domain and one page of the email addresses Tomba has for it, with each person's name, job title, department, and verification status. A domain with no known addresses, and a disposable or webmail domain such as `gmail.com`, returns `200` with an empty `data.emails` array. The credit cost depends on `limit`, not on the number of addresses returned; see [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 The company and one page of its email addresses. ###### Content-Type: application/json - **`data` (required)** `object` — The company and its email addresses. - **`emails` (required)** `array` — One page of the domain's email addresses. Empty when there are none. **Items:** - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string` — The email address. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. Empty when either is unknown. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`phone_data` (required)** `array` — Phone numbers for the person when you set \`enrich\_mobile=true\`, otherwise an empty array. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`seniority` (required)** `string | null` — \`junior\`, \`senior\`, or \`executive\`. - **`sources` (required)** `array` — Public pages where the address appears. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string`, possible values: `"personal", "generic"` — \`personal\` for an address that belongs to one person, \`generic\` for a role address. - **`verification` (required)** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`organization` (required)** `object` — The company that owns the domain. For a domain Tomba has no record of, and for a disposable or webmail domain, only \`website\_url\`, \`disposable\`, and \`webmail\` are set; the other fields are \`null\` or \`false\`. - **`accept_all` (required)** `boolean` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company_size` (required)** `string | null` — Employee count range, such as \`1-10\`. Free text; not a fixed list. - **`company_type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`description` (required)** `string | null` — Short description of the company. - **`disposable` (required)** `boolean` — \`true\` when the domain belongs to a disposable email provider. \`emails\` is then empty. - **`founded` (required)** `string | null` — Year the company was founded. - **`industries` (required)** `string | null` — Industry. Free text from several data sources, such as \`financial services\`; not a fixed list. - **`keywords` (required)** `array | null` — Keywords that describe the company. - **`last_updated` (required)** `string | null`, format: `date-time` — When Tomba last updated the company record, in RFC 3339 format. - **`location` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`postal_code` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`street_address` (required)** `string | null` — Street address. - **`organization` (required)** `string | null` — Company name. When Tomba has no name for the company, it's derived from the domain. - **`pattern` (required)** `string | null` — Email format used at the domain, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the company. Get it from the phone finder with \`domain\`. - **`ranking` (required)** `integer | null` — Popularity rank of the domain on the web. Lower is more popular. - **`revenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. Free text; not a fixed list. - **`social_links` (required)** `object` — URLs of the company's social profiles. - **`facebook_url` (required)** `string | null` — Facebook page URL. - **`github_url` (required)** `string | null` — GitHub organization URL. - **`instagram_url` (required)** `string | null` — Instagram profile URL. - **`linkedin_url` (required)** `string | null` — LinkedIn company page URL. - **`pinterest_url` (required)** `string | null` — Pinterest profile URL. - **`tiktok_url` (required)** `string | null` — TikTok profile URL. - **`twitter_url` (required)** `string | null` — Twitter (X) profile URL. - **`youtube_url` (required)** `string | null` — YouTube channel URL. - **`total_similar` (required)** `integer | null` — Number of similar companies Tomba has for the domain. List them with \`GET /similar\`. - **`webmail` (required)** `boolean` — \`true\` when the domain belongs to a webmail provider, such as Gmail. \`emails\` is then empty. - **`website_url` (required)** `string | null` — The domain. - **`whois` (required)** `object` — Domain registration from the WHOIS record. Each field is \`null\` when Tomba has no WHOIS data. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`meta` (required)** `object` — Paging for the email addresses, and the request as the API read it. - **`current` (required)** `integer` — The page returned. - **`pageSize` (required)** `integer` — Addresses per page, the \`limit\` you requested. \`10\` in a response without results. - **`params` (required)** `object` — The request parameters after normalization and defaults. - **`company` (required)** `string` — The \`company\` you sent, as a lowercase slug. Empty when not sent. - **`country` (required)** `string | null` — The \`country\` you sent, in uppercase. - **`department` (required)** `string | null` — The \`department\` you sent. - **`domain` (required)** `string` — The domain searched, in lowercase and without \`www.\`. When \`company\` matched a company, its domain. - **`enrich_mobile` (required)** `boolean` — The \`enrich\_mobile\` you sent. - **`limit` (required)** `integer` — The \`limit\` applied. - **`live` (required)** `boolean` — Not used; always \`false\` unless you send it. - **`page` (required)** `integer` — The page returned. - **`type` (required)** `string`, possible values: `"all", "personal", "generic"` — The \`type\` applied. - **`webhook_url` (required)** `string | null` — The \`webhook\_url\` you sent. - **`total` (required)** `integer` — Number of addresses Tomba has for the domain that match \`type\`. With a single \`department\`, or with \`country\`, the number for that department or country. - **`total_pages` (required)** `integer` — Number of pages at your \`limit\`, computed from the domain's total for \`type\` without the \`department\` or \`country\` filter. \`1\` in a response without results. **Example:** ``` { "data": { "organization": { "website_url": null, "organization": null, "location": { "country": null, "city": null, "state": null, "street_address": null, "postal_code": null }, "social_links": { "twitter_url": null, "facebook_url": null, "linkedin_url": null, "instagram_url": null, "github_url": null, "youtube_url": null, "pinterest_url": null, "tiktok_url": null }, "disposable": true, "webmail": true, "phone_number": true, "industries": null, "founded": null, "company_size": null, "company_type": null, "revenue": null, "accept_all": true, "description": null, "pattern": null, "total_similar": null, "keywords": [ "" ], "ranking": null, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "last_updated": null }, "emails": [ { "email": "", "first_name": null, "last_name": null, "full_name": null, "gender": null, "phone_number": true, "type": "personal", "country": null, "position": null, "department": null, "seniority": null, "twitter": null, "linkedin": null, "score": 0, "verification": { "date": null, "status": "valid" }, "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "...": "[Additional Properties Truncated]" } ], "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ] } ] }, "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1, "params": { "domain": "", "company": "", "page": 1, "limit": 1, "department": null, "country": null, "type": "all", "live": true, "enrich_mobile": true, "webhook_url": null } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Finder - **Method:** `GET` - **Path:** `/email-finder` - **Tags:** Finder Finds a person's professional email address from their name and their company's domain or name. Tomba returns a stored address when it has one; otherwise it generates candidate addresses and checks them against the company's mail servers. When no address is found, the response is still `200` and `data.email` is `null`. A disposable or webmail domain, such as `gmail.com`, fails with `400` and type `unknown_record`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The person's address, or \`data.email\` \`null\` when none is found. ###### Content-Type: application/json - **`data` (required)** `object` — The person and their email address. - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string | null`, format: `email` — The email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Format of the address, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. Set \`enrich\_mobile=true\` to get it in \`phone\_data\`. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null`, possible values: `"personal", "generic", null` — \`personal\` for an address that belongs to one person, \`generic\` for a role address such as \`support@\`. - **`website_url` (required)** `string | null` — Company domain, such as \`stripe.com\`. - **`disposable`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a disposable email provider. - **`phone_data`** `array` — Phone numbers for the person when you set \`enrich\_mobile=true\`, otherwise an empty array. Left out when no address is found and for an address found by a live check. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`webmail`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a webmail provider, such as Gmail. **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "disposable": true, "webmail": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Verifier - **Method:** `GET` - **Path:** `/email-verifier` - **Tags:** Verifier Checks whether an email address can receive mail. `data.email.status` and `data.email.result` give the outcome; the other fields report the individual checks. You can also send the address in the path, as `GET /email-verifier/{email}`. #### Responses ##### Status: 200 The verification result. ###### Content-Type: application/json - **`data` (required)** `object` — The verification result. - **`email` (required)** `object` — The checks. - **`accept_all` (required)** `boolean` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`block` (required)** `boolean` — \`true\` when the mail server blocked or refused the check. Usually comes with status \`unknown\`. - **`disposable` (required)** `boolean` — \`true\` when the domain belongs to a disposable email provider. - **`email` (required)** `string` — The verified address. Empty when the domain is disposable. - **`gibberish` (required)** `boolean` — \`true\` when the part before \`@\` looks randomly generated. - **`greylisted` (required)** `boolean` — \`true\` when the mail server temporarily deferred the check. - **`mx` (required)** `object` — MX records of the domain. - **`records` (required)** `array | null` — MX host names. \`null\` when Tomba has no MX data for the domain. - **`mx_check` (required)** `boolean` — \`true\` when the domain has MX records. - **`regex` (required)** `boolean` — \`true\` when the address is syntactically valid. - **`result` (required)** `string`, possible values: `"deliverable", "undeliverable", "risky", ""` — Deliverability verdict: \`deliverable\`, \`undeliverable\`, or \`risky\`. Empty when the domain is disposable. See \[Result values]\(https\://docs.tomba.io/attributes/verifier#result-values). - **`score` (required)** `integer` — Confidence score: \`99\` for \`valid\`, \`77\` or more for \`accept\_all\`, \`55\` or more for an \`unknown\` check that the server blocked, \`11\` or more for \`invalid\` and other \`unknown\` results, and \`2\` for \`disposable\`. For an address Tomba has on record, each public source adds one point. - **`smtp_check` (required)** `boolean` — \`true\` when the domain has MX records, the same as \`mx\_check\`. It doesn't show whether the mailbox exists; use \`status\`. - **`smtp_provider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. - **`smtp_server` (required)** `boolean` — Same value as \`smtp\_check\`. - **`status` (required)** `string`, possible values: `"valid", "Valid", "accept_all", "invalid", "unknown", "disposable"` — Detailed outcome: \`valid\`, \`accept\_all\`, \`invalid\`, \`unknown\`, or \`disposable\`. A valid result from a live check of an address outside webmail domains is returned as \`Valid\`, with a capital V, so compare case-insensitively. There's no \`webmail\` status; check the \`webmail\` field. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`webmail` (required)** `boolean` — \`true\` when the domain belongs to a webmail provider, such as Gmail. - **`whois` (required)** `object` — Domain registration from the WHOIS record. Each field is \`null\` when Tomba has no WHOIS data for the domain. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`phone_data` (required)** `array | null` — Phone numbers for the address when you set \`enrich\_mobile=true\` and Tomba has the address on record; otherwise an empty array. \`null\` when Tomba has no record of the address, and for disposable and webmail addresses. - **`sources` (required)** `array` — Public pages where the address appears. When a valid address has no public source, the list can contain one entry that points to the address's page on Tomba. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. **Example:** ``` { "data": { "email": { "email": "", "result": "deliverable", "status": "valid", "score": 0, "smtp_provider": null, "mx": { "records": [ "" ] }, "mx_check": true, "smtp_server": true, "smtp_check": true, "accept_all": true, "greylisted": true, "block": true, "gibberish": true, "disposable": true, "webmail": true, "regex": true, "whois": { "registrar_name": null, "referral_url": null, "created_date": null } }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 408 Request timeout. The email verifier couldn't complete the mailbox check because the remote mail server returned an unexpected response. The request isn't charged; retry later. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Phone Finder - **Method:** `GET` - **Path:** `/phone-finder` - **Tags:** Phone Finds phone numbers for a person or a company from an email address, a domain, or a LinkedIn profile URL. Send at least one of `email`, `domain`, and `linkedin`; you can combine them, and the numbers found for each are merged without duplicates. The same endpoint is also available as `GET /phone` and `GET /phone/{email}`. `data` is one number, preferring a valid one, or an array of every number found with `full=true`. When nothing is found, the response is still `200`: `data` is an empty array and the response repeats the identifiers you sent. The cost depends on whether you send `domain`; see [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 One phone number, an array with \`full=true\`, or an empty \`data\` array when nothing is found. ###### Content-Type: application/json - **`data` (required)** `object` — One phone number, or an array of phone numbers. An empty array when nothing is found. - **`domain`** `string` — The \`domain\` you sent, normalized. Only in a response without results. - **`email`** `string` — The \`email\` you sent, in lowercase. Only in a response without results. - **`linkedin`** `string` — The \`linkedin\` profile you sent, reduced to its permalink, such as \`jane-doe\`. Only in a response without results. **Example:** ``` { "email": "", "domain": "", "linkedin": "", "data": { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A parameter failed validation, or none of \`email\`, \`domain\`, and \`linkedin\` was sent. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Phone validator - **Method:** `GET` - **Path:** `/phone-validator` - **Tags:** Phone Checks whether a phone number is valid in its country's numbering plan and returns its formats, line type, carrier, region, and time zones. For a number that isn't valid, the response is still `200`, with an empty `data` array and your input in `phone`. A number whose country can't be determined fails with `422`; send it in international format or add `country_code`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The number's details, or an empty \`data\` array when the number isn't valid. ###### Content-Type: application/json - **`data` (required)** `object` — The number's details, or an empty array when the number isn't valid. - **`phone`** `string` — The \`phone\` you sent. Only in the response for a number that isn't valid. **Example:** ``` { "phone": "", "data": { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A parameter failed validation, or the number's country can't be determined. Send the number in international format or add \`country\_code\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Sources - **Method:** `GET` - **Path:** `/email-sources` - **Tags:** Email Returns the public web pages where Tomba found an email address, with when it was first and last seen on each. When Tomba has no sources for the address, the response has status `201` and an empty `data` array. This endpoint uses the sources balance. Only a `200` response is charged; when the balance is used up it returns `429`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 The address's sources. ###### Content-Type: application/json - **`data` (required)** `array` — The sources, at most 20. An empty array, with status \`201\`, when Tomba has none. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. - **`email` (required)** `string` — The address you asked about, trimmed and in lowercase. **Example:** ``` { "data": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "email": "" } ``` ##### Status: 201 Tomba has no sources for the address. Not charged. ###### Content-Type: application/json - **`data` (required)** `array` — The sources, at most 20. An empty array, with status \`201\`, when Tomba has none. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. - **`email` (required)** `string` — The address you asked about, trimmed and in lowercase. **Example:** ``` { "data": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "email": "" } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Domain status - **Method:** `GET` - **Path:** `/domain-status` - **Tags:** Domain Tells you whether a domain, or the domain of an email address, belongs to a webmail provider such as Gmail or to a disposable email provider. The endpoint needs no API key, isn't charged, and isn't rate-limited. Send `domain` or `email`. The response is a flat object, not wrapped in `data`, and repeats the `domain` or `email` you sent. A value that fails validation returns `200` with `{"webmail": false, "disposable": true}`. #### Responses ##### Status: 200 The domain's status. ###### Content-Type: application/json - **`disposable` (required)** `boolean` — \`true\` when the domain belongs to a disposable email provider. Also \`true\` when the input fails validation or when you send neither parameter. - **`webmail` (required)** `boolean` — \`true\` when the domain belongs to a webmail provider. - **`domain`** `string` — The \`domain\` you sent, in lowercase and without \`www.\`. Returned when you send \`domain\`, and as an empty string when you send neither parameter. - **`email`** `string` — The \`email\` you sent, in lowercase. Returned when you send \`email\` without \`domain\`. **Example:** ``` { "domain": "", "email": "", "webmail": true, "disposable": true } ``` ##### Status: 400 The IP address the request came from is blocked by the firewall. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The domain is a public suffix, such as \`co.uk\`, rather than a domain someone can register. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Count - **Method:** `GET` - **Path:** `/email-count` - **Tags:** Finder Returns how many email addresses Tomba has for a domain, by email type, department, and seniority. Use it to size a domain before a domain search. An unknown, webmail, or disposable domain returns `0` in every count. This endpoint uses the email count balance, and every successful call is charged; when the balance is used up it returns `429`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 The counts for the domain. ###### Content-Type: application/json - **`data` (required)** `object` — The counts. - **`department` (required)** `object` — Number of addresses of the requested \`type\` in each department. Every department is present, with \`0\` when there are none. - **`accounting` (required)** `integer` - **`administrative` (required)** `integer` - **`communication` (required)** `integer` - **`diversity` (required)** `integer` - **`education` (required)** `integer` - **`engineering` (required)** `integer` - **`executive` (required)** `integer` - **`facilities` (required)** `integer` - **`finance` (required)** `integer` - **`healthcare` (required)** `integer` - **`hr` (required)** `integer` - **`it` (required)** `integer` - **`legal` (required)** `integer` - **`management` (required)** `integer` - **`marketing` (required)** `integer` - **`operations` (required)** `integer` - **`pr` (required)** `integer` - **`sales` (required)** `integer` - **`security` (required)** `integer` - **`software` (required)** `integer` - **`support` (required)** `integer` - **`warehouse` (required)** `integer` - **`generic_emails` (required)** `integer` — Number of generic (role) addresses, such as \`support\@stripe.com\`. - **`personal_emails` (required)** `integer` — Number of personal addresses, such as \`jane.doe\@stripe.com\`. - **`seniority` (required)** `object` — Number of addresses of the requested \`type\` at each seniority level. - **`executive` (required)** `integer` - **`junior` (required)** `integer` - **`senior` (required)** `integer` - **`total` (required)** `integer` — Number of addresses of the requested \`type\`. - **`website_id` (required)** `integer` — Tomba's internal ID for the domain's company record. \`0\` when Tomba has no record of the domain. **Example:** ``` { "data": { "total": 1, "personal_emails": 1, "generic_emails": 1, "department": { "engineering": 1, "finance": 1, "hr": 1, "it": 1, "marketing": 1, "operations": 1, "management": 1, "sales": 1, "legal": 1, "support": 1, "communication": 1, "executive": 1, "accounting": 1, "administrative": 1, "diversity": 1, "facilities": 1, "pr": 1, "security": 1, "software": 1, "warehouse": 1, "healthcare": 1, "education": 1 }, "seniority": { "junior": 1, "senior": 1, "executive": 1 } }, "website_id": 1 } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get domain suggestions - **Method:** `GET` - **Path:** `/domain-suggestions` - **Tags:** Domain Suggestions Returns up to five companies whose name or domain matches your query, with their domain and the number of email addresses Tomba has for it. Use it to turn a company name into a domain before a domain search. The number of suggestions is fixed at five. This endpoint isn't charged. When nothing matches, `data` is an empty array; if the lookup fails, `data` is `null`. #### Responses ##### Status: 200 Up to five matching companies. ###### Content-Type: application/json - **`data` (required)** `array | null` — Suggested companies. An empty array when nothing matches, \`null\` if the lookup fails. - **`meta` (required)** `object` — The query and the maximum number of suggestions. - **`limit` (required)** `integer` — Maximum number of suggestions. Always \`5\`, or \`0\` if the lookup fails. - **`query` (required)** `string` — Your query, trimmed and in lowercase. Empty if the lookup fails. **Example:** ``` { "data": [ { "name": "Stripe", "domain": "stripe.com", "email_count": 1250 } ], "meta": { "query": "stripe", "limit": 5 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Format - **Method:** `GET` - **Path:** `/email-format` - **Tags:** Finder Returns the formats that a domain's email addresses follow, such as `{first}.{last}`, with the share of known addresses that use each one. `data` is an empty array when Tomba has no formats for the domain. This endpoint uses the email count balance, and every successful call is charged, including one with an empty result; when the balance is used up it returns `429`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 The domain's email formats. ###### Content-Type: application/json - **`data` (required)** `array` — Up to 20 formats, in no particular order. An empty array when Tomba has no formats for the domain. **Items:** - **`format` (required)** `string` — The pattern, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`percentage` (required)** `integer` — Share of the domain's known addresses that use this pattern, from 0 to 100. **Example:** ``` { "data": [ { "format": "", "percentage": 0 } ] } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Location - **Method:** `GET` - **Path:** `/location` - **Tags:** Finder Returns, for each country, how many of a domain's email addresses belong to people in that country. To list the addresses for one country, pass its code to domain search in `country`. `data` is an empty array when Tomba has no location data for the domain. This endpoint uses the email count balance, and every successful call is charged, including one with an empty result; when the balance is used up it returns `429`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 Address counts by country. ###### Content-Type: application/json - **`data` (required)** `array` — One entry per country, in no particular order. An empty array when Tomba has no location data for the domain. **Items:** - **`name` (required)** `string` — Two-letter country code (ISO 3166-1 alpha-2). Pass it to domain search in \`country\` to list those addresses. - **`total` (required)** `integer` — Number of the domain's email addresses in that country. **Example:** ``` { "data": [ { "name": "", "total": 1 } ] } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Similar - **Method:** `GET` - **Path:** `/similar` - **Tags:** Domain Returns companies similar to a domain, such as competitors, 25 per page. When Tomba has the domain on record but no similar companies stored, it looks them up live before it responds, except on the Free plan. `data` is `null` when there are no similar companies. The response always has up to 25 companies per page, whatever `limit` you send; `limit` only changes the credit cost. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 One page of similar companies, or \`data\` \`null\` when there are none. ###### Content-Type: application/json - **`data` (required)** `array | null` — Similar companies. \`null\` when Tomba has none for the domain. - **`meta` (required)** `object` — Paging. - **`current` (required)** `integer` — The page returned. - **`pageSize` (required)** `integer` — Results per page. Always \`25\`. - **`params` (required)** `object` — Not used by this endpoint. Always present, with empty values. - **`company`** `string` - **`country`** `string | null` - **`department`** `string | null` - **`domain`** `string` - **`enrich_mobile`** `boolean` - **`limit`** `integer` - **`live`** `boolean` - **`page`** `integer` - **`type`** `string` - **`webhook_url`** `string | null` - **`total` (required)** `integer` — Number of similar companies Tomba has for the domain. - **`total_pages` (required)** `integer` — Number of pages. \`0\` when there are no results. **Example:** ``` { "data": [ { "website_url": "", "name": null, "industries": null } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1, "params": { "domain": "", "company": "", "page": 1, "limit": 1, "department": null, "country": null, "type": "", "live": true, "enrich_mobile": true, "webhook_url": null } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Technology - **Method:** `GET` - **Path:** `/technology` - **Tags:** Domain Returns the technologies detected on a domain's website, such as its analytics, live chat, and payment tools, with their categories. When Tomba hasn't analyzed the domain before, it detects them live before it responds, except on the Free plan. `data` is `null` when Tomba has no technology data for the domain. A live detection that fails returns `500` with type `internal_error`. The request needs a positive search balance; see [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs). #### Responses ##### Status: 200 The domain's technologies, or \`data\` \`null\` when Tomba has none. ###### Content-Type: application/json - **`data` (required)** `array | null` — One entry per technology. \`null\` when Tomba has no technology data for the domain. - **`domain`** `string` — The domain you asked about. Left out when \`data\` is \`null\`. **Example:** ``` { "domain": "", "data": [ { "slug": "", "name": "", "icon": "", "website": "", "description": "", "categories": [ { "id": 1, "slug": "", "name": "" } ] } ] } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Author Finder - **Method:** `GET` - **Path:** `/author-finder` - **Tags:** Finder Finds the email address of the author of an article or blog post from its URL. Tomba reads the page, identifies the author, and returns their address with the article and every author candidate in `data.info`. When no address is found, the response is still `200`: `data.email` is `null`, and `data.info` is returned if the page could be read. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The author's address, or \`data.email\` \`null\` when none is found. ###### Content-Type: application/json - **`data` (required)** `object` — The article's author and their email address. - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Always \`null\` for the author finder. - **`email` (required)** `string | null`, format: `email` — The author's email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Always \`null\` for the author finder. - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the author. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null` — Always \`null\` for the author finder. - **`website_url` (required)** `string | null` — Domain of the author's company, such as \`stripe.com\`. - **`info`** `object` — The article the author finder read, with every author candidate found on the page. Left out when the page couldn't be read. Text fields are empty strings when the page doesn't provide them. - **`article_domain` (required)** `string` — Domain that hosts the article. - **`candidates` (required)** `array | null` — People named as the author on the page, best match first. \`null\` when none were found. - **`description` (required)** `string` — Article description. - **`og_image` (required)** `string` — URL of the article's Open Graph image. - **`publish_date` (required)** `string` — Publication date, as it appears on the page. - **`publisher_name` (required)** `string` — Name of the publication. - **`title` (required)** `string` — Article title. - **`url` (required)** `string` — The article URL. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": null, "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "info": { "url": "", "title": "", "og_image": "", "description": "", "article_domain": "", "publisher_name": "", "publish_date": "", "candidates": [ { "full_name": "", "first_name": "", "last_name": "", "email": "", "image": "", "gravatar": true, "linkedin": "", "twitter": "", "facebook": "", "github": "", "...": "[Additional Properties Truncated]" } ] } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Linkedin Finder - **Method:** `GET` - **Path:** `/linkedin` - **Tags:** Finder Finds the professional email address of the person behind a LinkedIn profile URL. Tomba returns a stored address when it has one; otherwise it may read the profile and search for the address live. When no address is found, the response is still `200` and `data.email` is `null`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The person's address, an array of addresses with \`full=true\`, or \`data.email\` \`null\` when none is found. ###### Content-Type: application/json - **`data` (required)** `object` — One result, or an array of results with \`full=true\`. **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "...": "[Additional Properties Truncated]" } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Email Enrichment - **Method:** `GET` - **Path:** `/enrich` - **Tags:** Finder Returns the person behind an email address, with their name, company, job title, social profiles, and the address's verification status, in Tomba's own format. For Clearbit's format, use the [Person API](https://docs.tomba.io/api/enrichment#person-api). When Tomba has no data for the address, the response is still `200`: `data.email` is `null`, and `data.disposable` and `data.webmail` describe the address's domain. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The person, or \`data.email\` \`null\` when Tomba has no data for the address. ###### Content-Type: application/json - **`data` (required)** `object` — The person and their email address. - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string | null`, format: `email` — The email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Format of the address, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. Set \`enrich\_mobile=true\` to get it in \`phone\_data\`. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null`, possible values: `"personal", "generic", null` — \`personal\` for an address that belongs to one person, \`generic\` for a role address such as \`support@\`. - **`website_url` (required)** `string | null` — Company domain, such as \`stripe.com\`. - **`disposable`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a disposable email provider. - **`phone_data`** `array` — Phone numbers for the person when you set \`enrich\_mobile=true\`, otherwise an empty array. Left out when no address is found and for an address found by a live check. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`webmail`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a webmail provider, such as Gmail. **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "disposable": true, "webmail": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Company API - **Method:** `GET` - **Path:** `/companies/find` - **Tags:** Enrichment Returns the company behind a domain in Clearbit's Company API format: name, description, location, industry codes, social handles, size, revenue, and technologies. Fields that Tomba doesn't fill are always `null`; see [Clearbit-compatible enrichment](https://docs.tomba.io/attributes/enrichment). When there's no match, the response has status `200` with an `errors` object instead of `data`: type `not_found` (code `404`) when Tomba has no record of the domain, and `params_invalid` (code `422`) for a disposable or webmail domain. Check for `errors` before you read `data`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The company, or an \`errors\` object with status \`200\` when there's no match. ###### Content-Type: application/json **One of:** - **`data` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#company-fields). - **`category` (required)** `object` — Industry codes. \`sector\`, \`industryGroup\`, \`industry\`, and \`subIndustry\` are always \`null\`. - **`industry` (required)** `string | null` - **`industryGroup` (required)** `string | null` - **`naics6Codes` (required)** `array | null` — Six-digit NAICS codes. - **`naics6Codes2022` (required)** `array | null` — Six-digit NAICS 2022 codes. - **`naicsCode` (required)** `string | null` — NAICS code. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`sector` (required)** `string | null` - **`sic4Codes` (required)** `array | null` — Four-digit SIC codes. - **`sicCode` (required)** `string | null` — SIC code. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`subIndustry` (required)** `string | null` - **`description` (required)** `string | null` — Short description of the company. - **`domain` (required)** `string | null` — The domain. - **`domainAliases` (required)** `array | null` — Always \`null\`. - **`emailProvider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. Clearbit returns a boolean here. - **`facebook` (required)** `object` — Facebook page. - **`handle` (required)** `string | null` — Handle of the company's Facebook page. - **`likes` (required)** `string | null` — Always \`null\`. - **`foundedYear` (required)** `string | null` — Year the company was founded, as a string. - **`geo` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`postalCode` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`stateCode` (required)** `string | null` — Same value as \`state\`. - **`streetAddress` (required)** `string | null` — Street address. - **`streetName` (required)** `string | null` — Same value as \`streetAddress\`. - **`streetNumber` (required)** `string | null` — Same value as \`streetAddress\`. - **`subPremise` (required)** `string | null` — Always \`null\`. - **`identifiers` (required)** `object` — Business identifiers. \`usEIN\` is always \`null\`. - **`usEIN` (required)** `string | null` - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`legalName` (required)** `string | null` — Same value as \`name\`. - **`linkedin` (required)** `object` — LinkedIn company page. - **`handle` (required)** `string | null` — Handle of the company's LinkedIn page. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`logo` (required)** `string | null` — Always \`null\`. Use the \[Logo API]\(https\://docs.tomba.io/logo-api). - **`metrics` (required)** `object` — Size and traffic. Only \`trafficRank\`, \`employees\`, \`annualRevenue\`, and \`estimatedAnnualRevenue\` are filled. - **`alexaGlobalRank` (required)** `string | null` — Always \`null\`. - **`alexaUsRank` (required)** `string | null` — Always \`null\`. - **`annualRevenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. - **`employees` (required)** `string | null` — Employee count range, such as \`51-200\`. Clearbit returns a number here. - **`estimatedAnnualRevenue` (required)** `string | null` — Same value as \`annualRevenue\`. - **`fiscalYearEnd` (required)** `string | null` — Always \`null\`. - **`marketCap` (required)** `string | null` — Always \`null\`. - **`raised` (required)** `string | null` — Always \`null\`. - **`trafficRank` (required)** `string | null` — Popularity rank of the domain on the web, as a number in a string. Lower is more popular. Clearbit returns a label such as \`very\_high\` here. - **`name` (required)** `string | null` — Company name. - **`parent` (required)** `object` — Parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`site` (required)** `object` — Contact details found on the website. - **`emailAddresses` (required)** `array | null` — Up to 6 generic (role) addresses at the domain. - **`phoneNumbers` (required)** `array | null` — The company's phone number, if Tomba has one. - **`tags` (required)** `array | null` — Keywords that describe the company. - **`tech` (required)** `array | null` — Names of the technologies detected on the website. - **`techCategories` (required)** `array | null` — Categories of those technologies. - **`ticker` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Handle of the company's Twitter (X) profile. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`ultimateParent` (required)** `object` — Ultimate parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`whois` (required)** `object` — Domain registration from the WHOIS record, with snake\_case keys. Not a Clearbit field. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`meta` (required)** `object` — The lookup. - **`domain` (required)** `string | null` — The domain you looked up. * **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "data": { "name": null, "legalName": null, "domain": null, "domainAliases": [ "" ], "site": { "phoneNumbers": [ "" ], "emailAddresses": [ "" ] }, "category": { "sector": null, "industryGroup": null, "industry": null, "subIndustry": null, "sicCode": null, "sic4Codes": [ "" ], "naicsCode": null, "naics6Codes": [ "" ], "naics6Codes2022": [ "" ] }, "tags": [ "" ], "description": null, "foundedYear": null, "location": null, "timeZone": null, "utcOffset": null, "geo": { "streetNumber": null, "streetName": null, "subPremise": null, "streetAddress": null, "city": null, "postalCode": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "logo": null, "facebook": { "handle": null, "likes": null }, "linkedin": { "handle": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "location": null, "site": null, "avatar": null }, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "emailProvider": null, "type": null, "ticker": null, "identifiers": { "usEIN": null }, "metrics": { "alexaUsRank": null, "alexaGlobalRank": null, "trafficRank": null, "employees": null, "marketCap": null, "raised": null, "annualRevenue": null, "estimatedAnnualRevenue": null, "fiscalYearEnd": null }, "indexedAt": null, "tech": [ "" ], "techCategories": [ "" ], "parent": { "domain": null }, "ultimateParent": { "domain": null } }, "meta": { "domain": null } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Person API - **Method:** `GET` - **Path:** `/people/find` - **Tags:** Enrichment Returns the person behind an email address in Clearbit's Person API format: name, location, employment, and social profiles. Fields that Tomba doesn't fill are always `null`; see [Clearbit-compatible enrichment](https://docs.tomba.io/attributes/enrichment). For Tomba's own format, use [Email Enrichment](https://docs.tomba.io/api/finder#email-enrichment). When there's no match, the response has status `200` with an `errors` object instead of `data`: type `not_found` (code `404`) when Tomba has no data for the address, and `params_invalid` (code `422`) for a disposable or webmail address. Check for `errors` before you read `data`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The person, or an \`errors\` object with status \`200\` when there's no match. ###### Content-Type: application/json **One of:** - **`data` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#person-fields). - **`activeAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`avatar` (required)** `string | null` — Always \`null\`. - **`bio` (required)** `string | null` — Always \`null\`. - **`email` (required)** `string | null` — The email address. - **`emailProvider` (required)** `string | null` — Always \`null\`. - **`employment` (required)** `object` — Current employer and job. - **`domain` (required)** `string` — Employer's domain. - **`name` (required)** `string | null` — Employer's name. - **`role` (required)** `string | null` — Department, such as \`engineering\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`seniority` (required)** `string | null` — Always \`null\`. - **`subRole` (required)** `string | null` — Always \`null\`. - **`title` (required)** `string | null` — Job title. - **`facebook` (required)** `object` — Facebook profile. \`handle\` is always \`null\`. - **`handle` (required)** `string | null` - **`fuzzy` (required)** `boolean | null` — Always \`null\`. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`geo` (required)** `object` — Location. Only \`country\` and \`countryCode\` are filled. - **`city` (required)** `string | null` — Always \`null\`. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`state` (required)** `string | null` — Always \`null\`. - **`stateCode` (required)** `string | null` — Always \`null\`. - **`github` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`blog` (required)** `string | null` - **`company` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` - **`id` (required)** `string | null` - **`gravatar` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`avatars` (required)** `array | null` - **`handle` (required)** `string | null` - **`urls` (required)** `array | null` - **`inactiveAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`linkedin` (required)** `object` — LinkedIn profile. - **`handle` (required)** `string | null` — LinkedIn profile URL. Clearbit returns a handle here. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here. - **`name` (required)** `object` — The person's name. - **`familyName` (required)** `string` — Last name. - **`fullName` (required)** `string` — First and last name. - **`givenName` (required)** `string` — First name. - **`phone` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`site` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`favorites` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Twitter (X) profile URL. Clearbit returns a handle here. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`statuses` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`meta` (required)** `object` — The lookup. - **`email` (required)** `string` — The address you looked up. * **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "data": { "name": { "fullName": "", "givenName": "", "familyName": "" }, "email": null, "location": null, "gender": null, "timeZone": null, "utcOffset": null, "geo": { "city": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "bio": null, "site": null, "avatar": null, "employment": { "domain": "", "name": null, "title": null, "role": null, "subRole": null, "seniority": null }, "facebook": { "handle": null }, "github": { "handle": null, "id": null, "avatar": null, "company": null, "blog": null, "followers": null, "following": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "statuses": null, "favorites": null, "location": null, "site": null, "avatar": null }, "linkedin": { "handle": null }, "gravatar": { "handle": null, "urls": [ "" ], "avatar": null, "avatars": [ "" ] }, "verification": { "date": null, "status": "valid" }, "phone": true, "fuzzy": null, "emailProvider": null, "indexedAt": null, "activeAt": null, "inactiveAt": null }, "meta": { "email": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Combined API - **Method:** `GET` - **Path:** `/combined/find` - **Tags:** Enrichment Returns the person behind an email address and the company behind its domain in one call, in Clearbit's format: `data.person` has the [Person API](https://docs.tomba.io/api/enrichment#person-api) fields and `data.company` the [Company API](https://docs.tomba.io/api/enrichment#company-api) fields. When Tomba has no record of the domain, every `company` field is `null` and `meta.email` is empty. When there's no match for the person, the response has status `200` with an `errors` object instead of `data`: type `not_found` (code `404`) when Tomba has no data for the address, and `params_invalid` (code `422`) for a disposable or webmail address. Check for `errors` before you read `data`. See [Credits and usage](https://docs.tomba.io/usage-and-quotas#credit-costs) for when a request is charged. #### Responses ##### Status: 200 The person and the company, or an \`errors\` object with status \`200\` when there's no match. ###### Content-Type: application/json **One of:** - **`data` (required)** `object` — The person and the company. - **`company` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#company-fields). - **`category` (required)** `object` — Industry codes. \`sector\`, \`industryGroup\`, \`industry\`, and \`subIndustry\` are always \`null\`. - **`industry` (required)** `string | null` - **`industryGroup` (required)** `string | null` - **`naics6Codes` (required)** `array | null` — Six-digit NAICS codes. - **`naics6Codes2022` (required)** `array | null` — Six-digit NAICS 2022 codes. - **`naicsCode` (required)** `string | null` — NAICS code. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`sector` (required)** `string | null` - **`sic4Codes` (required)** `array | null` — Four-digit SIC codes. - **`sicCode` (required)** `string | null` — SIC code. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`subIndustry` (required)** `string | null` - **`description` (required)** `string | null` — Short description of the company. - **`domain` (required)** `string | null` — The domain. - **`domainAliases` (required)** `array | null` — Always \`null\`. - **`emailProvider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. Clearbit returns a boolean here. - **`facebook` (required)** `object` — Facebook page. - **`handle` (required)** `string | null` — Handle of the company's Facebook page. - **`likes` (required)** `string | null` — Always \`null\`. - **`foundedYear` (required)** `string | null` — Year the company was founded, as a string. - **`geo` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`postalCode` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`stateCode` (required)** `string | null` — Same value as \`state\`. - **`streetAddress` (required)** `string | null` — Street address. - **`streetName` (required)** `string | null` — Same value as \`streetAddress\`. - **`streetNumber` (required)** `string | null` — Same value as \`streetAddress\`. - **`subPremise` (required)** `string | null` — Always \`null\`. - **`identifiers` (required)** `object` — Business identifiers. \`usEIN\` is always \`null\`. - **`usEIN` (required)** `string | null` - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`legalName` (required)** `string | null` — Same value as \`name\`. - **`linkedin` (required)** `object` — LinkedIn company page. - **`handle` (required)** `string | null` — Handle of the company's LinkedIn page. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`logo` (required)** `string | null` — Always \`null\`. Use the \[Logo API]\(https\://docs.tomba.io/logo-api). - **`metrics` (required)** `object` — Size and traffic. Only \`trafficRank\`, \`employees\`, \`annualRevenue\`, and \`estimatedAnnualRevenue\` are filled. - **`alexaGlobalRank` (required)** `string | null` — Always \`null\`. - **`alexaUsRank` (required)** `string | null` — Always \`null\`. - **`annualRevenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. - **`employees` (required)** `string | null` — Employee count range, such as \`51-200\`. Clearbit returns a number here. - **`estimatedAnnualRevenue` (required)** `string | null` — Same value as \`annualRevenue\`. - **`fiscalYearEnd` (required)** `string | null` — Always \`null\`. - **`marketCap` (required)** `string | null` — Always \`null\`. - **`raised` (required)** `string | null` — Always \`null\`. - **`trafficRank` (required)** `string | null` — Popularity rank of the domain on the web, as a number in a string. Lower is more popular. Clearbit returns a label such as \`very\_high\` here. - **`name` (required)** `string | null` — Company name. - **`parent` (required)** `object` — Parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`site` (required)** `object` — Contact details found on the website. - **`emailAddresses` (required)** `array | null` — Up to 6 generic (role) addresses at the domain. - **`phoneNumbers` (required)** `array | null` — The company's phone number, if Tomba has one. - **`tags` (required)** `array | null` — Keywords that describe the company. - **`tech` (required)** `array | null` — Names of the technologies detected on the website. - **`techCategories` (required)** `array | null` — Categories of those technologies. - **`ticker` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Handle of the company's Twitter (X) profile. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`ultimateParent` (required)** `object` — Ultimate parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`whois` (required)** `object` — Domain registration from the WHOIS record, with snake\_case keys. Not a Clearbit field. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`person` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#person-fields). - **`activeAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`avatar` (required)** `string | null` — Always \`null\`. - **`bio` (required)** `string | null` — Always \`null\`. - **`email` (required)** `string | null` — The email address. - **`emailProvider` (required)** `string | null` — Always \`null\`. - **`employment` (required)** `object` — Current employer and job. - **`domain` (required)** `string` — Employer's domain. - **`name` (required)** `string | null` — Employer's name. - **`role` (required)** `string | null` — Department, such as \`engineering\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`seniority` (required)** `string | null` — Always \`null\`. - **`subRole` (required)** `string | null` — Always \`null\`. - **`title` (required)** `string | null` — Job title. - **`facebook` (required)** `object` — Facebook profile. \`handle\` is always \`null\`. - **`handle` (required)** `string | null` - **`fuzzy` (required)** `boolean | null` — Always \`null\`. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`geo` (required)** `object` — Location. Only \`country\` and \`countryCode\` are filled. - **`city` (required)** `string | null` — Always \`null\`. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`state` (required)** `string | null` — Always \`null\`. - **`stateCode` (required)** `string | null` — Always \`null\`. - **`github` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`blog` (required)** `string | null` - **`company` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` - **`id` (required)** `string | null` - **`gravatar` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`avatars` (required)** `array | null` - **`handle` (required)** `string | null` - **`urls` (required)** `array | null` - **`inactiveAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`linkedin` (required)** `object` — LinkedIn profile. - **`handle` (required)** `string | null` — LinkedIn profile URL. Clearbit returns a handle here. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here. - **`name` (required)** `object` — The person's name. - **`familyName` (required)** `string` — Last name. - **`fullName` (required)** `string` — First and last name. - **`givenName` (required)** `string` — First name. - **`phone` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`site` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`favorites` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Twitter (X) profile URL. Clearbit returns a handle here. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`statuses` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`meta` (required)** `object` — The lookup. - **`email` (required)** `string` — The address you looked up. Empty when Tomba has no record of its domain. * **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "data": { "person": { "name": { "fullName": "", "givenName": "", "familyName": "" }, "email": null, "location": null, "gender": null, "timeZone": null, "utcOffset": null, "geo": { "city": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "bio": null, "site": null, "avatar": null, "employment": { "domain": "", "name": null, "title": null, "role": null, "subRole": null, "seniority": null }, "facebook": { "handle": null }, "github": { "handle": null, "id": null, "avatar": null, "company": null, "blog": null, "followers": null, "following": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "statuses": null, "favorites": null, "location": null, "site": null, "avatar": null }, "linkedin": { "handle": null }, "gravatar": { "handle": null, "urls": [ "" ], "avatar": null, "avatars": [ "" ] }, "verification": { "date": null, "status": "valid" }, "phone": true, "fuzzy": null, "emailProvider": null, "indexedAt": null, "activeAt": null, "inactiveAt": null }, "company": { "name": null, "legalName": null, "domain": null, "domainAliases": [ "" ], "site": { "phoneNumbers": [ "" ], "emailAddresses": [ "" ] }, "category": { "sector": null, "industryGroup": null, "industry": null, "subIndustry": null, "sicCode": null, "sic4Codes": [ "" ], "naicsCode": null, "naics6Codes": [ "" ], "naics6Codes2022": [ "" ] }, "tags": [ "" ], "description": null, "foundedYear": null, "location": null, "timeZone": null, "utcOffset": null, "geo": { "streetNumber": null, "streetName": null, "subPremise": null, "streetAddress": null, "city": null, "postalCode": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "...": "[Additional Properties Truncated]" }, "logo": null, "facebook": { "handle": null, "likes": null }, "linkedin": { "handle": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "location": null, "site": null, "avatar": null }, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "emailProvider": null, "type": null, "ticker": null, "identifiers": { "usEIN": null }, "metrics": { "alexaUsRank": null, "alexaGlobalRank": null, "trafficRank": null, "employees": null, "marketCap": null, "raised": null, "annualRevenue": null, "estimatedAnnualRevenue": null, "fiscalYearEnd": null }, "indexedAt": null, "tech": [ "" ], "techCategories": [ "" ], "parent": { "domain": null }, "ultimateParent": { "domain": null } } }, "meta": { "email": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 402 Payment required. The search or verification balance, or a workspace member's individual limit, is lower than the estimated cost of this request. Nothing is charged. Check balances with \`GET /me\`. See \[Credits and usage]\(https\://docs.tomba.io/usage-and-quotas). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. A per-second, per-minute, or daily limit was hit; the message names which one and \`Retry-After\` says when to retry. On email count, email format, location, and email sources, a \`429\` without \`Retry-After\` means that balance is used up. See \[Rate limits]\(https\://docs.tomba.io/rate-limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 451 Unavailable for legal reasons. The person who owns this email address, LinkedIn profile, or phone number asked Tomba, directly or indirectly, to stop processing their personal data. The data is withheld permanently and the request isn't charged. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### List bulk jobs - **Method:** `GET` - **Path:** `/bulk/{type}` - **Tags:** Bulks List the jobs of a type, `limit` per page, sorted by job ID. Jobs are shared by all members of a workspace. Archived jobs are listed only with `archived=true`, and deleted jobs never. #### Responses ##### Status: 200 A page of jobs, newest first unless \`direction\` is \`asc\`. ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`archived` (required)** `boolean` - **`billed` (required)** `boolean` — Whether the results were downloaded, which charges the job, once. - **`bulk_id` (required)** `integer`, format: `int64` — Job ID. - **`bulk_type` (required)** `string` — The job's type. Phone finder jobs are \`phone\`. - **`cancelled_at` (required)** `string | null`, format: `date-time` - **`completed_at` (required)** `string | null`, format: `date-time` - **`config` (required)** `object` — The job's input and options, as set when it was created. - **`input`** `object` - **`delimiter`** `string` — Column separator of the input. - **`fields`** `object` — Zero-based column of each field, as set or detected from the header. - **`file_size`** `integer` — Size of the uploaded file, in bytes. - **`has_header`** `boolean` — Whether the first row was a header. - **`original_file_name`** `string` — Name of the uploaded file. - **`rows`** `integer` — Rows accepted for processing. - **`source`** `string`, possible values: `"list", "data", "file"` — How the input was sent. - **`notify`** `boolean` — Whether an email is sent when the job finishes with results. - **`options`** `object` — The options, with their defaults filled in. See \`POST /bulk/{type}\` for each one. - **`boost_score_from_sources`** `boolean` - **`departments`** `array` **Items:** `string` - **`departments_mode`** `string` - **`email_type`** `string` - **`email_type_mode`** `string` - **`filter`** `string` - **`find_all_phones`** `boolean` - **`find_phones`** `boolean` - **`include_sources`** `boolean` - **`input_type`** `string` - **`max_emails_per_domain`** `integer` - **`skip_rows_with_email`** `boolean` - **`verify_emails`** `boolean` - **`quota_snapshot`** `object` — \`technology\` only: your search balance when the job was created, which caps the websites returned per technology. - **`searches`** `integer` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`webhook`** `object` — Where job events are sent. Absent without \`webhook\_url\`. - **`url`** `string` - **`created_at` (required)** `string`, format: `date-time` - **`error_message` (required)** `string | null` — Why the job failed. - **`expired` (required)** `boolean` — Whether \`expired\_at\` has passed. An expired job can no longer be downloaded, launched, or retried. - **`expired_at` (required)** `string`, format: `date-time` — 180 days after \`created\_at\`. Download the results before this date. - **`metrics` (required)** `object` — The job's results. They are updated while the job runs (\`partial\` is \`true\`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`name` (required)** `string` - **`processed` (required)** `integer` — Rows processed. - **`progress` (required)** `integer` — Percentage of the rows processed. - **`retry_count` (required)** `integer` — How many times the job was retried. - **`started_at` (required)** `string | null`, format: `date-time` - **`status` (required)** `string`, possible values: `"pending", "running", "completed", "failed", "cancelled"` — \`pending\` until launched, then \`running\`. \`completed\`, \`failed\`, and \`cancelled\` are final. - **`user_id` (required)** `integer`, format: `int64` — ID of the user who created the job. - **`preview`** `array` — The first rows of the results, once \`billed\` is \`true\`; an empty array before. Their fields depend on the type. **Items:** - **`meta` (required)** `object` - **`current`** `integer` — The \`page\` returned. - **`pageSize`** `integer` — The \`limit\` applied. - **`total`** `integer` — Number of jobs that match the filters. - **`total_pages`** `number` — \`total\` divided by \`pageSize\`, rounded down, so a last partial page isn't counted. Request pages until \`data\` has fewer items than \`limit\`. **Example:** ``` { "data": [ { "bulk_id": 1, "user_id": 1, "bulk_type": "", "name": "", "status": "pending", "archived": true, "progress": 0, "processed": 1, "billed": true, "error_message": null, "retry_count": 1, "created_at": "", "started_at": null, "completed_at": null, "cancelled_at": null, "expired": true, "expired_at": "", "config": { "v": 1, "input": { "source": "list", "has_header": true, "delimiter": "", "original_file_name": "", "file_size": 1, "rows": 1, "fields": { "propertyName*": 1 } }, "options": { "input_type": "", "max_emails_per_domain": 1, "email_type": "", "email_type_mode": "", "departments": [ "" ], "departments_mode": "", "verify_emails": true, "find_phones": true, "include_sources": true, "boost_score_from_sources": true, "...": "[Additional Properties Truncated]" }, "notify": true, "webhook": { "url": "" }, "quota_snapshot": { "searches": 1 } }, "metrics": { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } }, "preview": [ { "propertyName*": "anything" } ] } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Create a bulk job - **Method:** `POST` - **Path:** `/bulk/{type}` - **Tags:** Bulks Create a job from a `list` of values, `data` rows, or a CSV `file` (multipart). With `data` or `file`, each column is found from the header row unless you set its zero-based `*_field_index`. The options a type uses are listed in [Bulk types](https://docs.tomba.io/bulks#bulk-types); unknown parameters are ignored. The job is `pending` until you launch it. With `launch` set to `true`, it starts right away; if it can't, it stays `pending` and `data.message` says why. A domain export (`export`) takes one `domain`, always starts, and needs a paid plan. Nothing is charged until the first download; see [Billing](https://docs.tomba.io/bulks#billing). You can create 15 jobs of a type a day (30 domain exports), and none while 2 jobs of the type are running; see [Limits](https://docs.tomba.io/bulks#limits). #### Request Body ##### Content-Type: application/json - **`boost_score_from_sources`** `boolean`, default: `false` — 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. - **`company_name_field_index`** `integer` — Zero-based column of the company name. Used by \`search\`, \`similar\`, \`company\`, and \`finder\`. - **`country_field_index`** `integer` — Zero-based column of the country code. Used by \`phone-validator\`. - **`data`** `array` — 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. **Items:** **Array of:** `string` - **`delimiter`** `string`, default: `","` — Column separator of the uploaded file: \`,\`, \`;\`, \`|\`, or \`tab\`. Any other value is read as \`,\`. - **`departments`** `array` — Used by \`search\`. With \`departments\_mode\` \`only\`, only addresses in these departments are returned. **Items:** `string`, possible values: `"all", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"` - **`departments_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses in \`departments\`; \`priority\` returns every department. - **`domain`** `string` — The domain to export. Required for \`export\`, and used by no other type. - **`domain_field_index`** `integer` — Zero-based column of the domain or website. Used by \`search\`, \`similar\`, \`company\`, \`finder\`, and \`phone-finder\`. - **`email_field_index`** `integer` — Zero-based column of the email address. Used by \`enrich\`, \`verifier\`, and \`phone-finder\`. - **`email_type`** `string`, possible values: `"all", "personal", "generic"`, default: `"all"` — Used by \`search\`. With \`email\_type\_mode\` \`only\`, only addresses of this type are returned. - **`email_type_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses of \`email\_type\`; \`priority\` returns every type. - **`filter`** `string`, possible values: `"all", "personal", "generic", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"`, default: `"all"` — Used by \`export\`. The addresses to export, by type or by department. - **`find_all_phones`** `boolean`, default: `false` — Used by \`phone-finder\`. Returns every phone number found instead of one. - **`find_phones`** `boolean`, default: `false` — Adds phone numbers, at an extra cost. Used by \`search\`, \`company\`, \`finder\`, \`enrich\`, \`linkedin\`, \`verifier\`, and \`export\`. - **`first_name_field_index`** `integer` — Zero-based column of the first name. Used by \`finder\`. - **`full_name_field_index`** `integer` — Zero-based column of the full name. Used by \`finder\`. - **`has_header`** `boolean`, default: `true` — Whether the first row of \`data\` or of the file is a header. A \`list\` has no header. - **`include_sources`** `boolean`, default: `false` — Adds the web pages where each address was found. Used by \`search\`, \`finder\`, \`enrich\`, \`linkedin\`, \`author\`, \`verifier\`, and \`export\`. - **`input_type`** `string`, possible values: `"domain", "company"` — 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. - **`last_name_field_index`** `integer` — Zero-based column of the last name. Used by \`finder\`. - **`launch`** `boolean`, default: `false` — 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. - **`linkedin_url_field_index`** `integer` — Zero-based column of the LinkedIn profile URL. Used by \`linkedin\` and \`phone-finder\`. - **`list`** `string` — 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\`. - **`max_emails_per_domain`** `integer`, possible values: `1, 10, 20, 50, 100`, default: `10` — Used by \`search\` and \`similar\`. Addresses returned per domain. - **`name`** `string` — Job name, 3 to 200 characters. Required, except for a domain export, which is named after its domain. - **`notify`** `boolean`, default: `false` — Emails you when the job finishes with at least one result. - **`phone_field_index`** `integer` — Zero-based column of the phone number. Used by \`phone-validator\`. - **`skip_rows_with_email`** `boolean`, default: `false` — Used by \`finder\`. Skips the rows that already have a value in a column named \`email\`. - **`technology_field_index`** `integer` — Zero-based column of the technology slug. Used by \`technology\`. - **`url_field_index`** `integer` — Zero-based column of the article URL. Used by \`author\`. - **`verify_emails`** `boolean`, default: `false` — 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]\(https\://docs.tomba.io/bulks#billing). - **`webhook_url`** `string`, format: `uri` — 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]\(https\://docs.tomba.io/webhook#bulk-job-events). **Example:** ``` { "name": "", "list": "", "data": [ [ "" ] ], "has_header": true, "delimiter": ",", "domain": "", "domain_field_index": 0, "company_name_field_index": 0, "first_name_field_index": 0, "last_name_field_index": 0, "full_name_field_index": 0, "email_field_index": 0, "linkedin_url_field_index": 0, "url_field_index": 0, "phone_field_index": 0, "country_field_index": 0, "technology_field_index": 0, "input_type": "domain", "max_emails_per_domain": 10, "email_type": "all", "email_type_mode": "only", "departments": [ "all" ], "departments_mode": "only", "verify_emails": false, "find_phones": false, "include_sources": false, "boost_score_from_sources": false, "skip_rows_with_email": false, "find_all_phones": false, "filter": "all", "notify": false, "launch": false, "webhook_url": "" } ``` ##### Content-Type: multipart/form-data **All of:** - **`boost_score_from_sources`** `boolean`, default: `false` — 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. - **`company_name_field_index`** `integer` — Zero-based column of the company name. Used by \`search\`, \`similar\`, \`company\`, and \`finder\`. - **`country_field_index`** `integer` — Zero-based column of the country code. Used by \`phone-validator\`. - **`data`** `array` — 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. **Items:** **Array of:** `string` - **`delimiter`** `string`, default: `","` — Column separator of the uploaded file: \`,\`, \`;\`, \`|\`, or \`tab\`. Any other value is read as \`,\`. - **`departments`** `array` — Used by \`search\`. With \`departments\_mode\` \`only\`, only addresses in these departments are returned. **Items:** `string`, possible values: `"all", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"` - **`departments_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses in \`departments\`; \`priority\` returns every department. - **`domain`** `string` — The domain to export. Required for \`export\`, and used by no other type. - **`domain_field_index`** `integer` — Zero-based column of the domain or website. Used by \`search\`, \`similar\`, \`company\`, \`finder\`, and \`phone-finder\`. - **`email_field_index`** `integer` — Zero-based column of the email address. Used by \`enrich\`, \`verifier\`, and \`phone-finder\`. - **`email_type`** `string`, possible values: `"all", "personal", "generic"`, default: `"all"` — Used by \`search\`. With \`email\_type\_mode\` \`only\`, only addresses of this type are returned. - **`email_type_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses of \`email\_type\`; \`priority\` returns every type. - **`filter`** `string`, possible values: `"all", "personal", "generic", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"`, default: `"all"` — Used by \`export\`. The addresses to export, by type or by department. - **`find_all_phones`** `boolean`, default: `false` — Used by \`phone-finder\`. Returns every phone number found instead of one. - **`find_phones`** `boolean`, default: `false` — Adds phone numbers, at an extra cost. Used by \`search\`, \`company\`, \`finder\`, \`enrich\`, \`linkedin\`, \`verifier\`, and \`export\`. - **`first_name_field_index`** `integer` — Zero-based column of the first name. Used by \`finder\`. - **`full_name_field_index`** `integer` — Zero-based column of the full name. Used by \`finder\`. - **`has_header`** `boolean`, default: `true` — Whether the first row of \`data\` or of the file is a header. A \`list\` has no header. - **`include_sources`** `boolean`, default: `false` — Adds the web pages where each address was found. Used by \`search\`, \`finder\`, \`enrich\`, \`linkedin\`, \`author\`, \`verifier\`, and \`export\`. - **`input_type`** `string`, possible values: `"domain", "company"` — 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. - **`last_name_field_index`** `integer` — Zero-based column of the last name. Used by \`finder\`. - **`launch`** `boolean`, default: `false` — 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. - **`linkedin_url_field_index`** `integer` — Zero-based column of the LinkedIn profile URL. Used by \`linkedin\` and \`phone-finder\`. - **`list`** `string` — 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\`. - **`max_emails_per_domain`** `integer`, possible values: `1, 10, 20, 50, 100`, default: `10` — Used by \`search\` and \`similar\`. Addresses returned per domain. - **`name`** `string` — Job name, 3 to 200 characters. Required, except for a domain export, which is named after its domain. - **`notify`** `boolean`, default: `false` — Emails you when the job finishes with at least one result. - **`phone_field_index`** `integer` — Zero-based column of the phone number. Used by \`phone-validator\`. - **`skip_rows_with_email`** `boolean`, default: `false` — Used by \`finder\`. Skips the rows that already have a value in a column named \`email\`. - **`technology_field_index`** `integer` — Zero-based column of the technology slug. Used by \`technology\`. - **`url_field_index`** `integer` — Zero-based column of the article URL. Used by \`author\`. - **`verify_emails`** `boolean`, default: `false` — 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]\(https\://docs.tomba.io/bulks#billing). - **`webhook_url`** `string`, format: `uri` — 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]\(https\://docs.tomba.io/webhook#bulk-job-events). * **`file`** `string` — CSV file of up to 4 MB. Save spreadsheets as CSV first: \`.xlsx\`, \`.xls\`, \`.numbers\`, and \`.ods\` files are refused. **Example:** ``` { "name": "", "list": "", "data": [ [ "" ] ], "has_header": true, "delimiter": ",", "domain": "", "domain_field_index": 0, "company_name_field_index": 0, "first_name_field_index": 0, "last_name_field_index": 0, "full_name_field_index": 0, "email_field_index": 0, "linkedin_url_field_index": 0, "url_field_index": 0, "phone_field_index": 0, "country_field_index": 0, "technology_field_index": 0, "input_type": "domain", "max_emails_per_domain": 10, "email_type": "all", "email_type_mode": "only", "departments": [ "all" ], "departments_mode": "only", "verify_emails": false, "find_phones": false, "include_sources": false, "boost_score_from_sources": false, "skip_rows_with_email": false, "find_all_phones": false, "filter": "all", "notify": false, "launch": false, "webhook_url": "", "file": "" } ``` #### Responses ##### Status: 201 The job was created. With \`launch\`, \`data.message\` is present when the job couldn't start: it stays \`pending\`, and you can launch it later. The \`X-RateLimit-\*\` headers count the jobs of this type created today. ###### Content-Type: application/json - **`data` (required)** `object` - **`id` (required)** `integer`, format: `int64` — Job ID. - **`message`** `string` — Why the requested launch was refused. **Example:** ``` { "data": { "id": 1, "message": "" } } ``` ##### Status: 400 Bad request. The credentials are missing or malformed (see \`authentication\_failed\`), the JSON body or the CSV file can't be read (\`api\_error\`), no value of the \`list\` is valid for the type (\`unknown\_record\`), or a domain export was requested on the Free plan (\`api\_error\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 413 Request entity too large. The request, including any uploaded file, is over 4 MB. This response has an \`error\` string instead of the \`errors\` object. ###### Content-Type: application/json - **`error`** `string` **Example:** ``` { "error": "" } ``` ##### Status: 422 Unprocessable entity. A parameter is missing or invalid, or the type doesn't use it; the message names it. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. You created the daily maximum of jobs of this type (\`Retry-After\` is sent), 2 jobs of this type are running, or a kind of credit the job needs is used up. See \[Limits]\(https\://docs.tomba.io/bulks#limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get a bulk job - **Method:** `GET` - **Path:** `/bulk/{type}/{id}` - **Tags:** Bulks Get a job by ID, with its options in `config`, its results in `metrics`, and, once it is billed, the first result rows in `preview`. #### Responses ##### Status: 200 The job, with the first rows of its results in \`preview\` once it is billed. ###### Content-Type: application/json - **`data` (required)** `object` — A bulk job. \`preview\` is returned only by \`GET /bulk/{type}/{id}\`. - **`archived` (required)** `boolean` - **`billed` (required)** `boolean` — Whether the results were downloaded, which charges the job, once. - **`bulk_id` (required)** `integer`, format: `int64` — Job ID. - **`bulk_type` (required)** `string` — The job's type. Phone finder jobs are \`phone\`. - **`cancelled_at` (required)** `string | null`, format: `date-time` - **`completed_at` (required)** `string | null`, format: `date-time` - **`config` (required)** `object` — The job's input and options, as set when it was created. - **`input`** `object` - **`delimiter`** `string` — Column separator of the input. - **`fields`** `object` — Zero-based column of each field, as set or detected from the header. - **`file_size`** `integer` — Size of the uploaded file, in bytes. - **`has_header`** `boolean` — Whether the first row was a header. - **`original_file_name`** `string` — Name of the uploaded file. - **`rows`** `integer` — Rows accepted for processing. - **`source`** `string`, possible values: `"list", "data", "file"` — How the input was sent. - **`notify`** `boolean` — Whether an email is sent when the job finishes with results. - **`options`** `object` — The options, with their defaults filled in. See \`POST /bulk/{type}\` for each one. - **`boost_score_from_sources`** `boolean` - **`departments`** `array` **Items:** `string` - **`departments_mode`** `string` - **`email_type`** `string` - **`email_type_mode`** `string` - **`filter`** `string` - **`find_all_phones`** `boolean` - **`find_phones`** `boolean` - **`include_sources`** `boolean` - **`input_type`** `string` - **`max_emails_per_domain`** `integer` - **`skip_rows_with_email`** `boolean` - **`verify_emails`** `boolean` - **`quota_snapshot`** `object` — \`technology\` only: your search balance when the job was created, which caps the websites returned per technology. - **`searches`** `integer` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`webhook`** `object` — Where job events are sent. Absent without \`webhook\_url\`. - **`url`** `string` - **`created_at` (required)** `string`, format: `date-time` - **`error_message` (required)** `string | null` — Why the job failed. - **`expired` (required)** `boolean` — Whether \`expired\_at\` has passed. An expired job can no longer be downloaded, launched, or retried. - **`expired_at` (required)** `string`, format: `date-time` — 180 days after \`created\_at\`. Download the results before this date. - **`metrics` (required)** `object` — The job's results. They are updated while the job runs (\`partial\` is \`true\`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`name` (required)** `string` - **`processed` (required)** `integer` — Rows processed. - **`progress` (required)** `integer` — Percentage of the rows processed. - **`retry_count` (required)** `integer` — How many times the job was retried. - **`started_at` (required)** `string | null`, format: `date-time` - **`status` (required)** `string`, possible values: `"pending", "running", "completed", "failed", "cancelled"` — \`pending\` until launched, then \`running\`. \`completed\`, \`failed\`, and \`cancelled\` are final. - **`user_id` (required)** `integer`, format: `int64` — ID of the user who created the job. - **`preview`** `array` — The first rows of the results, once \`billed\` is \`true\`; an empty array before. Their fields depend on the type. **Items:** **Example:** ``` { "data": { "bulk_id": 1, "user_id": 1, "bulk_type": "", "name": "", "status": "pending", "archived": true, "progress": 0, "processed": 1, "billed": true, "error_message": null, "retry_count": 1, "created_at": "", "started_at": null, "completed_at": null, "cancelled_at": null, "expired": true, "expired_at": "", "config": { "v": 1, "input": { "source": "list", "has_header": true, "delimiter": "", "original_file_name": "", "file_size": 1, "rows": 1, "fields": { "propertyName*": 1 } }, "options": { "input_type": "", "max_emails_per_domain": 1, "email_type": "", "email_type_mode": "", "departments": [ "" ], "departments_mode": "", "verify_emails": true, "find_phones": true, "include_sources": true, "boost_score_from_sources": true, "find_all_phones": true, "skip_rows_with_email": true, "filter": "" }, "notify": true, "webhook": { "url": "" }, "quota_snapshot": { "searches": 1 } }, "metrics": { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } }, "preview": [ { "propertyName*": "anything" } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Launch a bulk job - **Method:** `PUT` - **Path:** `/bulk/{type}/{id}` - **Tags:** Bulks Start a `pending` job; any other status, or an expired job, returns `409`. The launch is refused with `429` while 2 jobs of the type are running, or when a kind of credit the job needs is used up. Nothing is charged at launch; see [Billing](https://docs.tomba.io/bulks#billing). Follow the job with `GET /bulk/{type}/{id}/progress` or a [webhook](https://docs.tomba.io/webhook#bulk-job-events). #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job's status doesn't allow this action, or the job has expired; the message says which. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. You created the daily maximum of jobs of this type (\`Retry-After\` is sent), 2 jobs of this type are running, or a kind of credit the job needs is used up. See \[Limits]\(https\://docs.tomba.io/bulks#limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get bulk job progress - **Method:** `GET` - **Path:** `/bulk/{type}/{id}/progress` - **Tags:** Bulks Get a job's status, progress, estimated time left, and results so far. The fields are at the top level of the response, not in `data`. Poll until `status` is `completed`, `failed`, or `cancelled`, or use a [webhook](https://docs.tomba.io/webhook#bulk-job-events) instead. #### Responses ##### Status: 200 The job's progress, at the top level of the response rather than in \`data\`. ###### Content-Type: application/json - **`error_message` (required)** `string | null` — Why the job failed. - **`eta_seconds` (required)** `integer | null` — Estimated seconds until the job completes. \`null\` until enough rows are processed. - **`metrics` (required)** `object` — The job's results. They are updated while the job runs (\`partial\` is \`true\`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`processed` (required)** `integer` — Rows processed so far. - **`progress` (required)** `integer` — Percentage of the rows processed. - **`rows_per_minute` (required)** `number | null` — Processing speed. \`null\` until enough rows are processed. - **`status` (required)** `string`, possible values: `"pending", "running", "completed", "failed", "cancelled"` — \`pending\` until the job is launched. \`completed\`, \`failed\`, and \`cancelled\` are final. **Example:** ``` { "status": "pending", "progress": 0, "processed": 1, "error_message": null, "rows_per_minute": null, "eta_seconds": null, "metrics": { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Download bulk job results - **Method:** `GET` - **Path:** `/bulk/{type}/{id}/download` - **Tags:** Bulks Download a result file of a `completed` job as CSV. `file` selects it: `full` (the default), `valid`, or `not_found`. A job without a file of that kind returns `404`, and a job past its `expired_at` returns `409`. The first successful download charges the job's credits, shown in `metrics.credits`; later downloads of any file are free. If your balance is lower than the cost at the first download, the response is `429` and nothing is charged. See [Billing](https://docs.tomba.io/bulks#billing). Each job can be downloaded 25 times a day, and a domain export 30 times. #### Responses ##### Status: 200 The CSV file, as an attachment named after the job: \`\.csv\` for \`full\`, \`\\_valid.csv\` for \`valid\`, and \`\\_invalid.csv\` for \`not\_found\`. ###### Content-Type: text/csv `string` **Example:** ``` true ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. The job doesn't exist (\`unknown\_record\`), or it has no file of the requested kind (\`api\_error\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job isn't \`completed\` yet, or it has expired. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. The job was downloaded 25 times today, or, at the first download, your search or verification balance, or your individual limit in a workspace, is lower than the job's cost. Nothing is charged. \`Retry-After\` is sent only for the daily limit. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Estimate bulk job credits - **Method:** `GET` - **Path:** `/bulk/{type}/{id}/estimate` - **Tags:** Bulks Get the credits a job costs, and whether your balance covers them. Before the job completes, `basis` is `upper_bound`: the cost if every row returned the maximum. Once it completes, `basis` is `exact`: what the first download charges. #### Responses ##### Status: 200 The estimate. ###### Content-Type: application/json - **`data` (required)** `object` — The credits of a job. Before it completes, an upper bound, as if every row returned the maximum. Once it completes, exactly what the first download charges. - **`basis`** `string`, possible values: `"upper_bound", "exact"` — \`upper\_bound\` before the job completes, \`exact\` after. - **`billed`** `boolean` — Whether the job was already charged. Later downloads are free. - **`bulk_id`** `integer`, format: `int64` - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`note`** `string` - **`remaining`** `object` — Your remaining search and verification credits. - **`search`** `integer` - **`verify`** `integer` - **`rows`** `integer` — Rows to process. - **`status`** `string` - **`sufficient`** `boolean` — Whether your remaining credits cover \`credits\`. Always \`true\` once billed. **Example:** ``` { "data": { "bulk_id": 1, "status": "", "basis": "upper_bound", "billed": true, "rows": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "remaining": { "search": 1, "verify": 1 }, "sufficient": true, "note": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get bulk job history - **Method:** `GET` - **Path:** `/bulk/{type}/{id}/history` - **Tags:** Bulks List a job's events, oldest first: creation, launch, start, end, retries, downloads, renames, archiving, and webhook deliveries. #### Responses ##### Status: 200 A page of events. ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`actor`** `string`, possible values: `"user", "worker", "admin", "system"` - **`created_at`** `string`, format: `date-time` - **`event`** `string`, possible values: `"created", "launched", "started", "completed", "failed", "cancelled", "retried", "downloaded", "renamed", "archived", "restored", "deleted", "webhook_delivered", "webhook_failed"` - **`id`** `integer`, format: `int64` - **`message`** `string | null` — Why the job failed, for \`failed\` events. - **`meta`** `object | null` — 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. - **`user_id`** `integer | null`, format: `int64` — The user who acted, or \`null\` for Tomba. - **`meta` (required)** `object` - **`current` (required)** `integer` — Current page number - **`pageSize` (required)** `integer` — Items per page - **`total` (required)** `integer` — Total number of items - **`total_pages` (required)** `number` — Total number of pages **Example:** ``` { "data": [ { "id": 1, "user_id": null, "event": "created", "actor": "user", "message": null, "meta": null, "created_at": "" } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Cancel a bulk job - **Method:** `POST` - **Path:** `/bulk/{type}/{id}/cancel` - **Tags:** Bulks Cancel a `pending` job: its status becomes `cancelled`, and you can retry it later. Only a `pending` job can be cancelled; any other status returns `409`. #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job's status doesn't allow this action, or the job has expired; the message says which. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retry a bulk job - **Method:** `POST` - **Path:** `/bulk/{type}/{id}/retry` - **Tags:** Bulks Run a `failed` or `cancelled` job again from its input, with the same options. Its results and metrics are reset, `retry_count` goes up by one, and the job is launched. It returns `409` when the job has another status, has expired, or its input is no longer stored, and `429` like `PUT /bulk/{type}/{id}`. #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job's status doesn't allow this action, or the job has expired; the message says which. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. You created the daily maximum of jobs of this type (\`Retry-After\` is sent), 2 jobs of this type are running, or a kind of credit the job needs is used up. See \[Limits]\(https\://docs.tomba.io/bulks#limits). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Rename a bulk job - **Method:** `PUT` - **Path:** `/bulk/{type}/{id}/rename` - **Tags:** Bulks Rename a job. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — New name of the job, 3 to 200 characters. **Example:** ``` { "name": "" } ``` #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Archive a bulk job - **Method:** `DELETE` - **Path:** `/bulk/{type}/{id}/archive` - **Tags:** Bulks Archive a `completed`, `failed`, or `cancelled` job: it leaves the default list and appears with `archived=true`. Restore it with `PUT /bulk/{type}/{id}/restore`. Other statuses, and an archived job, return `409`. #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job's status doesn't allow this action, or the job has expired; the message says which. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Restore an archived bulk job - **Method:** `PUT` - **Path:** `/bulk/{type}/{id}/restore` - **Tags:** Bulks Move an archived job back to the default list. A job that isn't archived returns `409`. #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. The job's status doesn't allow this action, or the job has expired; the message says which. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Delete a bulk job - **Method:** `DELETE` - **Path:** `/bulk/{type}/{id}/delete` - **Tags:** Bulks Delete a job. It no longer appears in lists and its routes return `404`. #### Responses ##### Status: 200 The action succeeded. \`data.message\` says what was done. ###### Content-Type: application/json - **`data` (required)** `object` - **`code` (required)** `integer` — Always \`200\`. - **`message` (required)** `string` — What was done. - **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 Not found. No job of this type has this ID in your account or workspace, or it was deleted. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### List bulk types - **Method:** `GET` - **Path:** `/bulk/types` - **Tags:** Bulks List every bulk type with its input fields and the header names detected for them, its options, row limit, daily limits, result files, and metrics distributions. #### Responses ##### Status: 200 Every bulk type. ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`allows_upload`** `boolean` — Whether it accepts a file. - **`app_path`** `string` — Its page in the web app, under \`https\://app.tomba.io/bulk/\`. - **`auto_launch`** `boolean` — Whether its jobs start when created. - **`creates_per_day`** `integer` - **`description`** `string` - **`distributions`** `array` — The \`metrics.distribution\` keys it fills. **Items:** `string` - **`downloads`** `array` — The result files it can have. **Items:** `string` - **`downloads_per_job_per_day`** `integer` - **`fields`** `array` **Items:** - **`field`** `string` - **`header_synonyms`** `array` — Header names that are matched to this field, ignoring case, spaces, and punctuation. **Items:** `string` - **`label`** `string` - **`param`** `string` — Its \`\*\_field\_index\` parameter. - **`file_required`** `boolean` — Whether it needs \`data\` or \`file\`, and refuses a \`list\`. - **`label`** `string` - **`max_rows`** `integer` - **`options`** `array` — The options it accepts. **Items:** `string` - **`path`** `string` — The \`{type}\` in its URLs. - **`phone_credits_per_phone`** `integer` — Search credits per phone number found. - **`primary_field`** `string` — The field a \`list\` or a single column is read as. - **`storage`** `string` - **`type`** `string` — The \`bulk\_type\` of its jobs. - **`verify`** `object` - **`always`** `boolean` — Whether it always verifies (\`verifier\`). - **`max_emails_per_domain`** `integer` — Above this \`max\_emails\_per\_domain\`, \`verify\_emails\` is turned off. - **`max_rows`** `integer` — Above this many rows, \`verify\_emails\` is turned off. **Example:** ``` { "data": [ { "type": "", "path": "", "label": "", "description": "", "app_path": "", "storage": "", "allows_upload": true, "file_required": true, "primary_field": "", "fields": [ { "field": "", "param": "", "label": "", "header_synonyms": [ "" ] } ], "options": [ "" ], "max_rows": 1, "verify": { "always": true, "max_rows": 1, "max_emails_per_domain": 1 }, "creates_per_day": 1, "downloads_per_job_per_day": 1, "auto_launch": true, "downloads": [ "" ], "distributions": [ "" ], "phone_credits_per_phone": 1 } ] } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get bulk statistics - **Method:** `GET` - **Path:** `/bulk/stats` - **Tags:** Bulks Get the bulk activity of your account, or of your workspace: jobs created by status, rows processed, results, and credits billed, in total, per type, and per day. The period is the last 30 days unless you set `from` and `to`, and is at most one year. #### Responses ##### Status: 200 The statistics. ###### Content-Type: application/json - **`data` (required)** `object` — Bulk activity of your account, or of your workspace, over a period. Credits count billed jobs only. - **`by_type`** `array` **Items:** - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`found`** `integer` - **`hit_rate`** `number` - **`jobs`** `integer` - **`label`** `string` - **`rows_processed`** `integer` - **`type`** `string` - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`daily`** `array` **Items:** - **`credits`** `integer` - **`date`** `string`, format: `date` - **`jobs`** `integer` - **`rows_processed`** `integer` - **`emails_found`** `integer` - **`found`** `integer` - **`from`** `string`, format: `date-time` - **`hit_rate`** `number` - **`jobs`** `object` — Jobs created in the period, by status. - **`cancelled`** `integer` - **`completed`** `integer` - **`failed`** `integer` - **`pending`** `integer` - **`running`** `integer` - **`total`** `integer` - **`rows_processed`** `integer` - **`to`** `string`, format: `date-time` **Example:** ``` { "data": { "from": "", "to": "", "jobs": { "total": 1, "pending": 1, "running": 1, "completed": 1, "failed": 1, "cancelled": 1 }, "rows_processed": 1, "found": 1, "emails_found": 1, "hit_rate": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "by_type": [ { "type": "", "label": "", "jobs": 1, "rows_processed": 1, "found": 1, "hit_rate": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 } } ], "daily": [ { "date": "", "jobs": 1, "rows_processed": 1, "credits": 1 } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 Unprocessable entity. A parameter failed validation, or the account reached its cap on API keys, leads, lead lists, or lead attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Get the bulk webhook secret - **Method:** `GET` - **Path:** `/bulk/webhook-secret` - **Tags:** Bulks Get the key your bulk job events are signed with. It is created on first use, or when you first create a job with `webhook_url`. See [Bulk job events](https://docs.tomba.io/webhook#bulk-job-events). #### Responses ##### Status: 200 The secret. ###### Content-Type: application/json - **`data` (required)** `object` — The key bulk job events are signed with. See \[Bulk job events]\(https\://docs.tomba.io/webhook#bulk-job-events). - **`created_at`** `string`, format: `date-time` - **`rotated_at`** `string | null`, format: `date-time` - **`secret`** `string` — \`whsec\_\` followed by the base64-encoded key. **Example:** ``` { "data": { "secret": "", "created_at": "", "rotated_at": null } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Rotate the bulk webhook secret - **Method:** `POST` - **Path:** `/bulk/webhook-secret/rotate` - **Tags:** Bulks Replace the key your bulk job events are signed with. The old key stops working at once, including for events of jobs that are already running. #### Responses ##### Status: 200 The secret. ###### Content-Type: application/json - **`data` (required)** `object` — The key bulk job events are signed with. See \[Bulk job events]\(https\://docs.tomba.io/webhook#bulk-job-events). - **`created_at`** `string`, format: `date-time` - **`rotated_at`** `string | null`, format: `date-time` - **`secret`** `string` — \`whsec\_\` followed by the base64-encoded key. **Example:** ``` { "data": { "secret": "", "created_at": "", "rotated_at": null } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve Leads - **Method:** `GET` - **Path:** `/leads` - **Tags:** Leads Returns the leads of your workspace, or your own leads when you aren't in a workspace, with each lead's list and custom attribute values. - `list` returns only the leads in one list. - `meta.total_pages` is rounded down, so it doesn't count a last, partial page. Use `meta.total` to know when you've read every lead. - With no matching leads, `data.leads` is an empty array and `meta` is absent. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 A page of leads. ###### Content-Type: application/json - **`data` (required)** `object` - **`leads` (required)** `array` — The leads on this page. **Items:** - **`attributes` (required)** `object` — Custom attribute values, keyed by the attribute's \`identifier\`. Values are strings. Empty when the lead has none. At most 25 are returned. - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code, for example \`US\`. - **`created_at` (required)** `string`, format: `date-time` — When the lead was saved. - **`email` (required)** `string` — Email address, in lowercase. Empty when the lead was saved without one. - **`first_name` (required)** `string | null` — First name. - **`id` (required)** `integer`, format: `int64` — Lead ID. - **`last_name` (required)** `string | null` — Last name. - **`lead_source` (required)** `string | null` — Where the lead came from: \`domain\` (domain search), \`finder\` (email finder), \`verify\` (email verifier), or \`browser\` (browser extension). - **`leads_list` (required)** `object` — The lead's list. Every field is \`null\` when the lead isn't in a list you can see. - **`list_id` (required)** `integer | null`, format: `int64` — List ID. - **`name` (required)** `string | null` — List name. - **`size` (required)** `integer | null`, format: `int64` — Number of leads in the list. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`list_id` (required)** `integer | null`, format: `int64` — ID of the lead's list. - **`notes` (required)** `string | null` — Notes. - **`phone_number` (required)** `string | null` — Phone number. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer | null` — Lead score, up to 100. - **`sync_airtable` (required)** `boolean | null` — Whether the lead was synced to Airtable. - **`sync_hubspot` (required)** `boolean | null` — Whether the lead was synced to HubSpot. - **`sync_mailchimp` (required)** `boolean | null` — Whether the lead was synced to Mailchimp. - **`sync_pipedrive` (required)** `boolean | null` — Whether the lead was synced to Pipedrive. - **`sync_status` (required)** `string | null` — State of the last sync to a connected app: \`pending\`, \`error\`, or \`success\`. - **`twitter` (required)** `string | null` — Twitter profile URL. - **`updated_at` (required)** `string`, format: `date-time` — When the lead was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who saved the lead. - **`website_url` (required)** `string | null` — Company domain. - **`meta`** `object` - **`current` (required)** `integer` — Current page number - **`pageSize` (required)** `integer` — Items per page - **`total` (required)** `integer` — Total number of items - **`total_pages` (required)** `number` — Total number of pages **Example:** ``` { "data": { "leads": [ { "id": 1, "user_id": 1, "email": "", "list_id": null, "first_name": null, "last_name": null, "country": null, "website_url": null, "position": null, "twitter": null, "linkedin": null, "phone_number": null, "company": null, "notes": null, "lead_source": null, "score": null, "sync_status": null, "sync_airtable": null, "sync_hubspot": null, "sync_mailchimp": null, "sync_pipedrive": null, "created_at": "", "updated_at": "", "leads_list": { "list_id": null, "size": null, "name": null }, "attributes": { "propertyName*": "" } } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A query parameter failed validation. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Create a Lead - **Method:** `POST` - **Path:** `/leads` - **Tags:** Leads Saves a lead to your account. Every field is optional, `email` included. Tomba doesn't check for duplicates: saving the same email address twice creates two leads. - `list_id` must be a JSON number. Sent as a string, the lead is still created, but without the list and without every field that follows `list_id` in the request body. A `list_id` that isn't one of your own lists is dropped. - `attributes` sets custom attribute values, keyed by the attribute's `identifier` from `GET /attributes`. Send the values as strings. Keys that don't match one of your attributes are ignored. - You can store as many leads as `pricing.available_leads` in `GET /me`. Past that, the request fails with `422` `rate_limit`. When your plan isn't Free and you've set up a lead webhook, Tomba sends the new lead to it. See [Lead events](https://docs.tomba.io/webhook#lead-events). Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`attributes`** `object` — Custom attribute values keyed by attribute \`identifier\`. Values must be strings. - **`company`** `string` — Company name, up to 55 characters. - **`country`** `string` — Two-letter country code in uppercase, for example \`US\`. - **`email`** `string`, format: `email` — Email address. Stored in lowercase. - **`first_name`** `string` — First name, 1 to 25 characters. - **`last_name`** `string` — Last name, 1 to 25 characters. - **`lead_source`** `string` — Where the lead came from, as a code in a string: \`1\` domain search, \`2\` email finder, \`3\` email verifier, \`4\` browser extension. Leads return it as \`domain\`, \`finder\`, \`verify\`, or \`browser\`. - **`linkedin`** `string` — LinkedIn profile URL. - **`list_id`** `integer`, format: `int64` — ID of one of your lead lists. Must be a JSON number. - **`notes`** `string` — Notes, up to 55 characters. - **`phone_number`** `string` — Phone number. - **`position`** `string` — Job title, up to 255 characters. - **`score`** `integer` — Lead score, up to 100. - **`twitter`** `string` — Twitter profile URL. A bare handle fails validation. - **`website_url`** `string` — Company domain, for example \`stripe.com\`. **Example:** ``` { "email": "", "list_id": 1, "first_name": "", "last_name": "", "country": "", "website_url": "", "position": "", "twitter": "", "linkedin": "", "phone_number": "", "company": "", "notes": "", "score": 1, "lead_source": "", "attributes": { "propertyName*": "" } } ``` #### Responses ##### Status: 201 Lead created. ###### Content-Type: application/json - **`data` (required)** `object` - **`id` (required)** `integer`, format: `int64` — ID of the new lead. **Example:** ``` { "data": { "id": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A field failed validation (\`params\_invalid\`), or you already store as many leads as your plan allows (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve a Single Lead - **Method:** `GET` - **Path:** `/leads/{leadId}` - **Tags:** Leads Returns one lead of your workspace, as the only item of `data.leads`. A lead that doesn't exist, or that you can't see, returns `200` with an empty `data.leads` array, not `404`. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 The lead, or an empty array when there's no such lead. ###### Content-Type: application/json - **`data` (required)** `object` - **`leads` (required)** `array` — The lead. Empty when there's no such lead. **Items:** - **`attributes` (required)** `object` — Custom attribute values, keyed by the attribute's \`identifier\`. Values are strings. Empty when the lead has none. At most 25 are returned. - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code, for example \`US\`. - **`created_at` (required)** `string`, format: `date-time` — When the lead was saved. - **`email` (required)** `string` — Email address, in lowercase. Empty when the lead was saved without one. - **`first_name` (required)** `string | null` — First name. - **`id` (required)** `integer`, format: `int64` — Lead ID. - **`last_name` (required)** `string | null` — Last name. - **`lead_source` (required)** `string | null` — Where the lead came from: \`domain\` (domain search), \`finder\` (email finder), \`verify\` (email verifier), or \`browser\` (browser extension). - **`leads_list` (required)** `object` — The lead's list. Every field is \`null\` when the lead isn't in a list you can see. - **`list_id` (required)** `integer | null`, format: `int64` — List ID. - **`name` (required)** `string | null` — List name. - **`size` (required)** `integer | null`, format: `int64` — Number of leads in the list. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`list_id` (required)** `integer | null`, format: `int64` — ID of the lead's list. - **`notes` (required)** `string | null` — Notes. - **`phone_number` (required)** `string | null` — Phone number. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer | null` — Lead score, up to 100. - **`sync_airtable` (required)** `boolean | null` — Whether the lead was synced to Airtable. - **`sync_hubspot` (required)** `boolean | null` — Whether the lead was synced to HubSpot. - **`sync_mailchimp` (required)** `boolean | null` — Whether the lead was synced to Mailchimp. - **`sync_pipedrive` (required)** `boolean | null` — Whether the lead was synced to Pipedrive. - **`sync_status` (required)** `string | null` — State of the last sync to a connected app: \`pending\`, \`error\`, or \`success\`. - **`twitter` (required)** `string | null` — Twitter profile URL. - **`updated_at` (required)** `string`, format: `date-time` — When the lead was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who saved the lead. - **`website_url` (required)** `string | null` — Company domain. **Example:** ``` { "data": { "leads": [ { "id": 1, "user_id": 1, "email": "", "list_id": null, "first_name": null, "last_name": null, "country": null, "website_url": null, "position": null, "twitter": null, "linkedin": null, "phone_number": null, "company": null, "notes": null, "lead_source": null, "score": null, "sync_status": null, "sync_airtable": null, "sync_hubspot": null, "sync_mailchimp": null, "sync_pipedrive": null, "created_at": "", "updated_at": "", "leads_list": { "list_id": null, "size": null, "name": null }, "attributes": { "propertyName*": "" } } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The lead ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Update a lead - **Method:** `PUT` - **Path:** `/leads/{leadId}` - **Tags:** Leads Updates a lead of your workspace. Send only the fields to change; the others keep their values. - `list_id` moves the lead to that list. A list outside your workspace is ignored. - `attributes` adds or replaces custom attribute values, keyed by the attribute's `identifier`. Keys that don't match an attribute of your workspace are ignored. - Some limits differ from `POST /leads`: `first_name` and `last_name` need at least 2 characters, `position` takes up to 25, and `twitter` and `linkedin` up to 99. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`attributes`** `object` — Custom attribute values keyed by attribute \`identifier\`. Values must be strings. - **`company`** `string` — Company name, up to 55 characters. - **`country`** `string` — Two-letter country code in uppercase, for example \`US\`. - **`email`** `string`, format: `email` — Email address. Stored in lowercase. - **`first_name`** `string` — First name, 2 to 25 characters. - **`last_name`** `string` — Last name, 2 to 25 characters. - **`lead_source`** `string` — Where the lead came from, as a code in a string (see \`POST /leads\`). - **`linkedin`** `string` — LinkedIn profile URL, up to 99 characters. - **`list_id`** `integer`, format: `int64` — ID of a lead list in your workspace. Must be a JSON number. - **`notes`** `string` — Notes, up to 55 characters. - **`phone_number`** `string` — Phone number. - **`position`** `string` — Job title, up to 25 characters. - **`score`** `integer` — Lead score, up to 100. - **`twitter`** `string` — Twitter profile URL, up to 99 characters. - **`website_url`** `string` — Company domain, for example \`stripe.com\`. **Example:** ``` { "email": "", "first_name": "", "last_name": "", "country": "", "website_url": "", "position": "", "twitter": "", "linkedin": "", "phone_number": "", "company": "", "notes": "", "score": 1, "list_id": 1, "lead_source": "", "attributes": { "propertyName*": "" } } ``` #### Responses ##### Status: 200 Lead updated. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No lead with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The lead ID isn't a number, or a field failed validation. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Delete a lead - **Method:** `DELETE` - **Path:** `/leads/{leadId}` - **Tags:** Leads Deletes a lead of your workspace, with its custom attribute values. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 Lead deleted. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No lead with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The lead ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve Lead Attributes - **Method:** `GET` - **Path:** `/attributes` - **Tags:** Lead Attributes Returns up to 25 custom lead attributes of your workspace, or your own attributes when you aren't in a workspace. There's no pagination. Use an attribute's `identifier` as the key when you set its value in a lead's `attributes`. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 Your lead attributes. ###### Content-Type: application/json - **`data` (required)** `object` - **`attributes` (required)** `array` — The attributes. Empty when there are none. **Items:** - **`created_at` (required)** `string`, format: `date-time` — When the attribute was created. - **`id` (required)** `integer`, format: `int64` — Attribute ID. - **`identifier` (required)** `string` — Key for the attribute's values in a lead's \`attributes\`: the name as a lowercase slug, so \`Deal size\` becomes \`deal-size\`. - **`name` (required)** `string` — Attribute name. - **`type` (required)** `string` — Value type: \`string\`, \`date\`, or \`number\`. - **`updated_at` (required)** `string`, format: `date-time` — When the attribute was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who created the attribute. **Example:** ``` { "data": { "attributes": [ { "id": 1, "user_id": 1, "name": "", "identifier": "", "type": "", "created_at": "", "updated_at": "" } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Create a Lead Attribute - **Method:** `POST` - **Path:** `/attributes` - **Tags:** Lead Attributes Creates a custom lead attribute. Its `identifier`, the key for its values in a lead's `attributes`, is the name as a lowercase slug: `Deal size` becomes `deal-size`. The request fails with `422` when you already have an attribute with the same identifier, or already have 29 attributes, the limit on every plan. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Attribute name, 2 to 25 characters. - **`type` (required)** `string`, possible values: `"string", "date", "number"` — Value type. **Example:** ``` { "name": "", "type": "string" } ``` #### Responses ##### Status: 201 Attribute created. ###### Content-Type: application/json - **`data` (required)** `object` - **`id` (required)** `integer`, format: `int64` — ID of the new attribute. **Example:** ``` { "data": { "id": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A field failed validation or the identifier is already used (\`params\_invalid\`), or you already have 29 attributes (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve a Single Lead Attribute - **Method:** `GET` - **Path:** `/attributes/{attributeId}` - **Tags:** Lead Attributes Confirms that an attribute exists in your workspace. Only `id` is filled in: the other fields come back as empty strings, `0`, and zero timestamps. To read an attribute's name, identifier, and type, use `GET /attributes`. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 The attribute, with only \`id\` filled in. ###### Content-Type: application/json - **`data` (required)** `object` - **`attributes` (required)** `object` - **`created_at` (required)** `string`, format: `date-time` — When the attribute was created. - **`id` (required)** `integer`, format: `int64` — Attribute ID. - **`identifier` (required)** `string` — Key for the attribute's values in a lead's \`attributes\`: the name as a lowercase slug, so \`Deal size\` becomes \`deal-size\`. - **`name` (required)** `string` — Attribute name. - **`type` (required)** `string` — Value type: \`string\`, \`date\`, or \`number\`. - **`updated_at` (required)** `string`, format: `date-time` — When the attribute was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who created the attribute. **Example:** ``` { "data": { "attributes": { "id": 1, "user_id": 1, "name": "", "identifier": "", "type": "", "created_at": "", "updated_at": "" } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No attribute with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The attribute ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Update a Lead Attribute - **Method:** `PUT` - **Path:** `/attributes/{attributeId}` - **Tags:** Lead Attributes Renames an attribute and sets its type. Send both fields. - The identifier is rebuilt from the new name. Values already set on leads stay attached and appear under the new identifier. - A `name` whose identifier matches the attribute's current one fails with `422`, so you can't change only the type. - Only attributes you created are changed. For a teammate's attribute, the request returns `200` without changing anything. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — New attribute name, 2 to 25 characters. - **`type` (required)** `string`, possible values: `"string", "date", "number"` — Value type. **Example:** ``` { "name": "", "type": "string" } ``` #### Responses ##### Status: 200 Attribute updated. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No attribute with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The attribute ID isn't a number, a field failed validation, or the new name gives the attribute's current identifier. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Delete a Lead Attribute - **Method:** `DELETE` - **Path:** `/attributes/{attributeId}` - **Tags:** Lead Attributes Deletes an attribute of your workspace. Its values no longer appear on leads. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 Attribute deleted. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No attribute with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The attribute ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve Leads Lists - **Method:** `GET` - **Path:** `/leads_lists` - **Tags:** Lead Lists Returns up to 25 lead lists of your workspace, or your own lists when you aren't in a workspace. There's no pagination. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 Your lead lists. ###### Content-Type: application/json - **`data` (required)** `object` - **`list_leads` (required)** `array` — The lists. Empty when there are none. **Items:** - **`created_at` (required)** `string`, format: `date-time` — When the list was created. - **`favorite` (required)** `boolean` — Whether the list is marked as a favorite. - **`id` (required)** `integer`, format: `int64` — List ID. - **`name` (required)** `string` — List name. - **`size` (required)** `integer`, format: `int64` — 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. - **`updated_at` (required)** `string`, format: `date-time` — When the list was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who created the list. - **`type`** `string` — List type. Lists created with this API have \`campaigns\`. Absent when empty. **Example:** ``` { "data": { "list_leads": [ { "id": 1, "user_id": 1, "size": 1, "name": "", "type": "", "favorite": true, "created_at": "", "updated_at": "" } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Create Leads List - **Method:** `POST` - **Path:** `/leads_lists` - **Tags:** Lead Lists Creates a lead list. The name must be unique among your lists. You can create as many lists as `pricing.available_list` in `GET /me`. Past that, the request fails with `422` `rate_limit`; the error message mentions custom fields, but the limit is on lists. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — List name, 2 to 40 characters after trimming spaces. - **`favorite`** `boolean`, default: `false` — Whether to mark the list as a favorite. **Example:** ``` { "name": "", "favorite": false } ``` #### Responses ##### Status: 201 List created. ###### Content-Type: application/json - **`data` (required)** `object` - **`id` (required)** `integer`, format: `int64` — ID of the new list. **Example:** ``` { "data": { "id": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 \`name\` failed validation or is already used by one of your lists (\`params\_invalid\`), or you already have as many lists as your plan allows (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve a Single Leads List - **Method:** `GET` - **Path:** `/leads_lists/{listId}` - **Tags:** Lead Lists Returns one lead list of your workspace. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 The list. ###### Content-Type: application/json - **`data` (required)** `object` - **`created_at` (required)** `string`, format: `date-time` — When the list was created. - **`favorite` (required)** `boolean` — Whether the list is marked as a favorite. - **`id` (required)** `integer`, format: `int64` — List ID. - **`name` (required)** `string` — List name. - **`size` (required)** `integer`, format: `int64` — 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. - **`updated_at` (required)** `string`, format: `date-time` — When the list was last changed. - **`user_id` (required)** `integer`, format: `int64` — User who created the list. - **`type`** `string` — List type. Lists created with this API have \`campaigns\`. Absent when empty. **Example:** ``` { "data": { "id": 1, "user_id": 1, "size": 1, "name": "", "type": "", "favorite": true, "created_at": "", "updated_at": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No list with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The list ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Update Leads List - **Method:** `PUT` - **Path:** `/leads_lists/{listId}` - **Tags:** Lead Lists Renames a list of your workspace, or marks or unmarks it as a favorite. - `favorite` is always written: leaving it out sets it to `false`. - A `name` already used by a list in your workspace fails with `422`, and that includes this list's own current name. Leave `name` out to change only `favorite`. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Request Body ##### Content-Type: application/json - **`favorite`** `boolean`, default: `false` — Whether the list is a favorite. Defaults to \`false\` when left out. - **`name`** `string` — New list name, 2 to 40 characters after trimming spaces. **Example:** ``` { "name": "", "favorite": false } ``` #### Responses ##### Status: 200 List updated. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No list with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The list ID isn't a number, \`name\` failed validation, or \`name\` is already used in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Delete Leads List - **Method:** `DELETE` - **Path:** `/leads_lists/{listId}` - **Tags:** Lead Lists Deletes a list of your workspace. The leads in it aren't deleted. Also accepts an OAuth 2.0 access token with the `leads` scope. #### Responses ##### Status: 200 List deleted. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No list with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The list ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve API Keys - **Method:** `GET` - **Path:** `/keys` - **Tags:** Keys Returns the API keys of your workspace: yours and every other member's, including their full key values. Without a workspace, returns your own keys. The response holds at most 50 keys, oldest first. Limited to 100 requests per minute. Also accepts an OAuth 2.0 access token with the `account` scope. #### Responses ##### Status: 200 The keys of your workspace. Each key still authenticates as its own owner, and its requests are charged to that owner. ###### Content-Type: application/json - **`data` (required)** `object` - **`keys` (required)** `array` **Items:** - **`created_at` (required)** `string`, format: `date-time` — When the key was created. - **`expired` (required)** `boolean` — Whether the key is past its expiry date. - **`id` (required)** `integer`, format: `int64` — Key ID. - **`ip` (required)** `string` — IP address the key was created or last rotated from. - **`is_owner` (required)** `boolean` — \`true\` when the key is yours, \`false\` when it belongs to a workspace teammate. - **`key` (required)** `string` — The key value, \`ta\_\` followed by 37 characters. Send it as \`X-Tomba-Key\`. - **`name` (required)** `string` — Label for the key. - **`updated_at` (required)** `string`, format: `date-time` — When the key was last changed. - **`user_id` (required)** `integer`, format: `int64` — User ID of the key's owner. A key authenticates as its owner, and its requests are charged to the owner. - **`created_by`** `integer`, format: `int64` — User ID of whoever created the key. Absent on older keys. - **`creator_email`** `string` — Email address of whoever created the key. Absent when the creator is unknown. - **`creator_image`** `string` — Profile image URL of whoever created the key. Absent when there's none. - **`creator_name`** `string` — Name of whoever created the key, or their email address when they have no name. Absent when the creator is unknown. - **`expires_at`** `string`, format: `date-time` — 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. - **`expires_in_days`** `integer` — Whole days until the key expires, negative once it has expired. Absent when \`expires\_at\` is absent. - **`last_used_at`** `string`, format: `date-time` — Last time the key authenticated a request, updated at most once an hour. Absent if the key hasn't been used. **Example:** ``` { "data": { "keys": [ { "id": 1, "user_id": 1, "key": "", "name": "CI runner", "ip": "", "expires_at": "", "created_by": 1, "last_used_at": "", "created_at": "", "updated_at": "", "is_owner": true, "expired": true, "expires_in_days": 87, "creator_name": "", "creator_email": "", "creator_image": "" } ] } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Create an API Key - **Method:** `POST` - **Path:** `/keys` - **Tags:** Keys Creates an API key for your account and returns its value in `data.message`. The request body is optional: - Without `name`, the key is named `Default key`, or `Default key 2`, `Default key 3`, and so on when that name is taken. - Without `expires_in_days`, the key expires in 365 days, the maximum. You can hold as many unexpired keys as `pricing.available_keys` in `GET /me`, and at least 25 while you have unused credit-pack credits. Expired keys don't count. Past the limit, the request fails with `422` `rate_limit`. Tomba emails you when a key is created. Limited to 100 requests per hour. Also accepts an OAuth 2.0 access token with the `account` scope. See [Rotate keys](https://docs.tomba.io/authentication#rotate-keys). #### Request Body ##### Content-Type: application/json - **`expires_in_days`** `integer`, default: `365` — Key lifetime in days, from 1 to 365. - **`name`** `string` — Label for the key, 2 to 100 characters after trimming spaces. Name the key after where it will be used. **Example:** ``` { "name": "", "expires_in_days": 365 } ``` #### Responses ##### Status: 201 Key created. ###### Content-Type: application/json - **`data` (required)** `object` - **`id` (required)** `integer`, format: `int64` — ID of the new key. - **`message` (required)** `string` — The new key's value. **Example:** ``` { "data": { "id": 1, "message": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A field failed validation (\`params\_invalid\`), or you already hold as many unexpired keys as your plan allows (\`rate\_limit\`). ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve a Single API Key - **Method:** `GET` - **Path:** `/keys/{keyId}` - **Tags:** Keys Returns one API key of your workspace, including its value. After rotating a key with `PUT`, read its new value here. Limited to 100 requests per minute for each key ID. Also accepts an OAuth 2.0 access token with the `account` scope. #### Responses ##### Status: 200 The key. ###### Content-Type: application/json - **`data` (required)** `object` - **`keys` (required)** `object` - **`created_at` (required)** `string`, format: `date-time` — When the key was created. - **`expired` (required)** `boolean` — Whether the key is past its expiry date. - **`id` (required)** `integer`, format: `int64` — Key ID. - **`ip` (required)** `string` — IP address the key was created or last rotated from. - **`is_owner` (required)** `boolean` — \`true\` when the key is yours, \`false\` when it belongs to a workspace teammate. - **`key` (required)** `string` — The key value, \`ta\_\` followed by 37 characters. Send it as \`X-Tomba-Key\`. - **`name` (required)** `string` — Label for the key. - **`updated_at` (required)** `string`, format: `date-time` — When the key was last changed. - **`user_id` (required)** `integer`, format: `int64` — User ID of the key's owner. A key authenticates as its owner, and its requests are charged to the owner. - **`created_by`** `integer`, format: `int64` — User ID of whoever created the key. Absent on older keys. - **`creator_email`** `string` — Email address of whoever created the key. Absent when the creator is unknown. - **`creator_image`** `string` — Profile image URL of whoever created the key. Absent when there's none. - **`creator_name`** `string` — Name of whoever created the key, or their email address when they have no name. Absent when the creator is unknown. - **`expires_at`** `string`, format: `date-time` — 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. - **`expires_in_days`** `integer` — Whole days until the key expires, negative once it has expired. Absent when \`expires\_at\` is absent. - **`last_used_at`** `string`, format: `date-time` — Last time the key authenticated a request, updated at most once an hour. Absent if the key hasn't been used. **Example:** ``` { "data": { "keys": { "id": 1, "user_id": 1, "key": "", "name": "CI runner", "ip": "", "expires_at": "", "created_by": 1, "last_used_at": "", "created_at": "", "updated_at": "", "is_owner": true, "expired": true, "expires_in_days": 87, "creator_name": "", "creator_email": "", "creator_image": "" } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No key with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The key ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Rename an API Key - **Method:** `PATCH` - **Path:** `/keys/{keyId}` - **Tags:** Keys Changes a key's name. The name is the only field you can edit. Expiry can't be changed: to extend a key, rotate it with `PUT`, which issues a new value with a new 365-day term. Any member of the key owner's workspace can rename the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the `account` scope. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — New name for the key, 2 to 100 characters after trimming spaces. **Example:** ``` { "name": "" } ``` #### Responses ##### Status: 200 Key renamed. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No key with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The key ID isn't a number, or \`name\` is missing or isn't 2 to 100 characters. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Reset an API Key - **Method:** `PUT` - **Path:** `/keys/{keyId}` - **Tags:** Keys Rotates a key: issues a new value and a new 365-day expiry, and the old value stops working immediately. The key keeps its ID, name, and creator. Rotating also revives an expired key. The response doesn't include the new value; read it with `GET /keys/{keyId}`. Any member of the key owner's workspace can rotate the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the `account` scope. #### Responses ##### Status: 200 Key rotated. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No key with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The key ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Delete an API Key - **Method:** `DELETE` - **Path:** `/keys/{keyId}` - **Tags:** Keys Deletes a key. Requests made with it fail from then on. Any member of the key owner's workspace can delete the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the `account` scope. #### Responses ##### Status: 200 Key deleted. ###### Content-Type: application/json - **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No key with this ID in your workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 The key ID isn't a number. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve API Usage - **Method:** `GET` - **Path:** `/usage` - **Tags:** Account Returns your daily credit usage over a range of days, one row per user and day, with totals for the range. - `duration` sets the range: from that many days ago through today. Rows exist only for days with charged credits. - `scope=team` returns the rows of every member of your workspace, and `scope=member` the rows of one member. Both need the workspace owner or admin role. - A workspace owner's rows also include the credits that members used on most endpoints, because those count against the owner's pool. With `scope=team`, those credits appear in both the member's rows and the owner's. The endpoint also reads `start`, `end`, and `period`, but they have no effect on the result: `start` and `end` in `YYYY-MM-DD` form are ignored, an RFC 3339 value fails with `500`, and `period` is validated (`daily`, `weekly`, or `monthly`) but not used. Use `duration`. Call this endpoint with an API key and secret. OAuth access tokens aren't accepted and get `401`. See [Check usage](https://docs.tomba.io/usage-and-quotas#check-usage). #### Responses ##### Status: 200 Daily usage rows and their totals. ###### Content-Type: application/json - **`data` (required)** `array | null` — 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. - **`total` (required)** `object` — Sums over the rows in \`data\`. There's no \`email\_count\` total. - **`export` (required)** `integer` — Legacy export counter. - **`search` (required)** `integer` — Search credits. - **`source_api` (required)** `integer` — Credits charged through direct API calls. - **`source_bulk` (required)** `integer` — Credits charged for bulk job downloads. - **`source_extension` (required)** `integer` — Credits charged through the browser extension. - **`source_sheets` (required)** `integer` — Credits charged through the Google Sheets add-on. - **`source_website` (required)** `integer` — Credits charged through the Tomba website. - **`sources` (required)** `integer` — Email sources credits. - **`verifier` (required)** `integer` — Verification credits. **Example:** ``` { "data": [ { "id": 1, "user_id": 1, "search": 1, "verifier": 1, "export": 1, "sources": 1, "email_count": 1, "source_website": 1, "source_bulk": 1, "source_extension": 1, "source_api": 1, "source_sheets": 1, "created_at": "" } ], "total": { "search": 1, "verifier": 1, "export": 1, "sources": 1, "source_website": 1, "source_extension": 1, "source_bulk": 1, "source_api": 1, "source_sheets": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. \`scope=team\` and \`scope=member\` need the workspace owner or admin role. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A query parameter has a value outside its allowed set. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve API Logs - **Method:** `GET` - **Path:** `/logs` - **Tags:** Account Returns your billable lookups, newest first, with what each one cost. Only requests to endpoints that cost credits, and that returned `200` with a result, are logged. Repeats of a lookup already charged in the current usage window appear with `cost` `0`. Failed requests, lookups without a result, and free endpoints aren't logged. In a workspace, the response includes the rows of every member; `member_id` narrows it to one member. `data` is `null` when no row matches. Call this endpoint with an API key and secret. OAuth access tokens aren't accepted and get `401`. #### Responses ##### Status: 200 A page of log rows. ###### Content-Type: application/json - **`data` (required)** `array | null` — Log rows. \`null\` when no row matches. - **`meta` (required)** `object` — Pagination details. - **`limit` (required)** `integer` — Rows per page. - **`page` (required)** `integer` — Current page. - **`total` (required)** `integer` — Number of matching rows. - **`total_pages` (required)** `integer` — Number of pages. **Example:** ``` { "data": [ { "id": 1, "user_id": 1, "uri": "", "params": null, "type": "", "hash": "", "cost": 1, "route_name": "", "source": "", "country": "", "user_agent": "", "ip_address": "", "http_method": "", "status_code": 1, "request_id": "", "endpoint": "", "api_key_id": 1, "duration_ms": 1, "created_at": "" } ], "meta": { "total": 1, "page": 1, "limit": 1, "total_pages": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A query parameter failed validation. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve a Single API Log - **Method:** `GET` - **Path:** `/logs/{logId}` - **Tags:** Account Returns one row of `GET /logs` by its `id`. In a workspace, you can read the rows of every member. The API also matches `logId` against the row's `request_id`, but rows logged by the current API don't record one, so use `id`. Call this endpoint with an API key and secret. OAuth access tokens aren't accepted and get `401`. #### Responses ##### Status: 200 The log row. ###### Content-Type: application/json - **`data` (required)** `object` — One billable lookup. Only requests to endpoints that cost credits, and that returned \`200\` with a result, are logged, including repeats charged \`0\`. - **`cost` (required)** `integer` — Credits charged. \`0\` for a repeat of a lookup already charged in the current usage window. - **`country` (required)** `string` — Two-letter country code of the caller's IP address. Empty when unknown. - **`created_at` (required)** `string`, format: `date-time` — When the request was made. - **`hash` (required)** `string` — Fingerprint of the request's parameters. Tomba uses it to recognize a repeat of a lookup already charged in the current usage window. - **`id` (required)** `integer`, format: `int64` — Log row ID. - **`ip_address` (required)** `string` — The caller's IP address. - **`params` (required)** `object | null` — The request's query parameters and top-level JSON body fields, as strings. - **`source` (required)** `string` — Where the request came from: \`API\`, \`Website\`, \`Browser extension\`, \`Google Sheets add-on\`, \`Bulk API\`, or \`MCP Agent\`. - **`type` (required)** `string` — 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\`. - **`uri` (required)** `string` — \`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. - **`user_agent` (required)** `string` — The request's \`User-Agent\` header. - **`user_id` (required)** `integer`, format: `int64` — User who made the request. - **`api_key_id`** `integer`, format: `int64` — ID of the API key that made the request. Absent for requests made with an OAuth access token or from the dashboard. - **`duration_ms`** `integer` — Time Tomba took to handle the request, in milliseconds. Absent on older rows. - **`endpoint`** `string` — Path you called, for example \`/v1/domain-search\`. Absent on older rows. - **`http_method`** `string` — HTTP method. Absent on older rows. - **`request_id`** `string` — Request ID, on rows that recorded one. Rows logged by the current API don't record it, so the field is usually absent. - **`route_name`** `string` — Internal route name, for example \`domain-search\`, \`enrich-finder\`, or \`SearchCompanies\`. Absent on older rows. - **`status_code`** `integer` — HTTP status of the response, always \`200\`. Absent on older rows. **Example:** ``` { "data": { "id": 1, "user_id": 1, "uri": "", "params": null, "type": "", "hash": "", "cost": 1, "route_name": "", "source": "", "country": "", "user_agent": "", "ip_address": "", "http_method": "", "status_code": 1, "request_id": "", "endpoint": "", "api_key_id": 1, "duration_ms": 1, "created_at": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 404 No row with this ID in your account or workspace. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Retrieve rate limits - **Method:** `GET` - **Path:** `/rate-limits` - **Tags:** Account Returns, for every rate-limited route, the limits that apply to your account and the requests counted against them in the current minute and day. - The limits come from your plan, raised by any credit pack that still has credits. `0` means unlimited. - In a workspace, members get the owner's limits, and the usage counts cover the whole workspace. Every API key, OAuth app, and member of an account or workspace shares these counters. - Daily counts reset at 00:00 UTC. `pricing.rate_limits` in `GET /me` shows your own plan's limits; this endpoint shows the limits actually enforced on your requests. It isn't rate-limited itself. It also accepts an OAuth 2.0 access token with the `read` scope. See [Rate limits](https://docs.tomba.io/rate-limits#check-your-limits). #### Responses ##### Status: 200 Limits and usage for each route. ###### Content-Type: application/json - **`data` (required)** `object` — 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. **Example:** ``` { "data": { "propertyName*": { "limits": { "rps": 1, "rpm": 1, "daily": 1 }, "usage": { "rpm_used": 1, "daily_used": 1 } } } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 403 Forbidden. The account is blocked or deleted, the OAuth access token lacks the required scope, or the plan doesn't include the endpoint. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Flag Incorrect Data - **Method:** `POST` - **Path:** `/flag` - **Tags:** Flag Reports incorrect data: an email address that bounced or is wrong, or a wrong organization, phone number, author URL, or website. `reason` must be one of the reasons listed for the `flag_type`. Tomba reviews each report by hand. A new report has the `status` `pending`; follow it with `GET /flag`. When Tomba confirms an `email` report with the reason `hard_bounce`, it returns one search credit to the usage window that's current at that moment, and the report's `credits_refunded` becomes `1`. Verification credits aren't returned, and other types and reasons don't return credits. See [Refunds for incorrect data](https://docs.tomba.io/usage-and-quotas#refunds-for-incorrect-data). Reporting an item again with the same `flag_type` while your earlier report is still pending fails with `409`. `POST /flag` is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope. #### Request Body ##### Content-Type: application/json - **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What you're reporting. - **`reason` (required)** `string`, possible values: `"hard_bounce", "invalid_email", "wrong_person", "outdated", "wrong_company", "wrong_phone", "broken_url", "other"` — 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. - **`value` (required)** `string` — The item you're reporting, such as the email address, domain, phone number, or URL. - **`comment`** `string` — Details that help Tomba review the report, such as the bounce message your mail server received. **Example:** ``` { "flag_type": "email", "value": "", "reason": "hard_bounce", "comment": "" } ``` #### Responses ##### Status: 201 Report created, pending review. ###### Content-Type: application/json - **`data` (required)** `object` - **`created_at` (required)** `string`, format: `date-time` — When you submitted the report. - **`credits_refunded` (required)** `integer` — Credits returned for the report: \`1\` when Tomba confirmed an \`email\` report with the reason \`hard\_bounce\` and returned a search credit, otherwise \`0\`. - **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What was reported. - **`id` (required)** `integer`, format: `int64` — Report ID. - **`reason` (required)** `string` — Why the data was reported. - **`status` (required)** `string`, possible values: `"pending", "confirmed", "rejected"` — Review status. A new report is \`pending\` until Tomba confirms or rejects it. - **`value` (required)** `string` — The reported item. - **`comment`** `string` — Your comment. Absent when you didn't send one. - **`resolved_at`** `string`, format: `date-time` — When Tomba reviewed the report. Absent until then. **Example:** ``` { "data": { "id": 1, "flag_type": "email", "value": "", "reason": "", "comment": "", "status": "pending", "credits_refunded": 1, "resolved_at": "", "created_at": "" } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 409 Conflict. A report for the same item is already pending review. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 422 A field failed validation, or \`reason\` isn't one of the reasons for the \`flag\_type\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### List My Flags - **Method:** `GET` - **Path:** `/flag` - **Tags:** Flag Returns the reports you submitted, with their review status and any credits returned. Only your own reports are listed, not your workspace's. `GET /flag` is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope. #### Responses ##### Status: 200 A page of your reports. ###### Content-Type: application/json - **`data` (required)** `array` — Your reports, one page at a time. **Items:** - **`created_at` (required)** `string`, format: `date-time` — When you submitted the report. - **`credits_refunded` (required)** `integer` — Credits returned for the report: \`1\` when Tomba confirmed an \`email\` report with the reason \`hard\_bounce\` and returned a search credit, otherwise \`0\`. - **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What was reported. - **`id` (required)** `integer`, format: `int64` — Report ID. - **`reason` (required)** `string` — Why the data was reported. - **`status` (required)** `string`, possible values: `"pending", "confirmed", "rejected"` — Review status. A new report is \`pending\` until Tomba confirms or rejects it. - **`value` (required)** `string` — The reported item. - **`comment`** `string` — Your comment. Absent when you didn't send one. - **`resolved_at`** `string`, format: `date-time` — When Tomba reviewed the report. Absent until then. - **`meta` (required)** `object` - **`current` (required)** `integer` — Current page number - **`pageSize` (required)** `integer` — Items per page - **`total` (required)** `integer` — Total number of items - **`total_pages` (required)** `number` — Total number of pages **Example:** ``` { "data": [ { "id": 1, "flag_type": "email", "value": "", "reason": "", "comment": "", "status": "pending", "credits_refunded": 1, "resolved_at": "", "created_at": "" } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } } ``` ##### Status: 400 Bad request. The credentials are missing, malformed, or expired, or a parameter or plan rule rejected the request. The \`type\` field identifies the exact cause. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 401 Unauthorized. The API key and secret are well-formed but don't match an account; the account is unconfirmed, has no password set, or its subscription has expired; or an OAuth 2.0 access token is invalid, expired, or revoked. Missing, malformed, and expired credentials return \`400\` instead, and blocked or deleted accounts return \`403\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 429 Too many requests. This endpoint has a fixed limit, the same on every plan. The \`429\` carries only \`Retry-After\`; successful responses carry \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\`. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ##### Status: 500 Internal server error. Retry with backoff. If the error persists, contact support with the \`X-Request-ID\` response header. ###### Content-Type: application/json - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### Tomba MCP Server - **Method:** `POST` - **Path:** `/mcp` - **Tags:** MCP Server Model Context Protocol (MCP) endpoint for AI assistants, served over Streamable HTTP. Send JSON-RPC 2.0 messages such as `initialize`, `tools/list`, and `tools/call`; the server keeps no session state. It exposes 28 tools, 12 prompts, and 3 resources. Authenticate with an OAuth 2.0 access token (MCP clients discover the flow from the `WWW-Authenticate` header of a `401`), with a bearer token of `base64(api_key:secret)`, or with the `X-Tomba-Key` and `X-Tomba-Secret` headers. See [Remote MCP server](https://docs.tomba.io/llm/remote-mcp/introduction) and the [tools reference](https://docs.tomba.io/llm/remote-mcp/tools). #### Request Body ##### Content-Type: application/json - **`jsonrpc` (required)** `string`, possible values: `"2.0"` - **`method` (required)** `string` - **`id`** `integer` - **`params`** `object` **Example:** ``` { "jsonrpc": "2.0", "id": 1, "method": "", "params": {} } ``` #### Responses ##### Status: 200 The JSON-RPC response, sent as a server-sent event stream with one \`message\` event. A tool call that fails is still a \`200\`: its result has \`isError: true\` and the reason in \`content\`. ###### Content-Type: text/event-stream `string` **Example:** ``` true ``` ##### Status: 401 No credentials were sent. The \`WWW-Authenticate\` header points MCP clients to the OAuth protected-resource metadata. ###### Content-Type: application/json **Example:** ``` {} ``` ##### Status: 500 Server error, returned as a JSON-RPC error with code \`-32603\`. ###### Content-Type: application/json **Example:** ``` {} ``` ### SERVERS /mcp - **Method:** `SERVERS` - **Path:** `/mcp` ## Schemas ### RevealSearchRequest - **Type:**`object` Send `query` or `filters`. When you send `query`, Tomba generates filters from it and ignores any `filters` you send; the generated filters are returned in `meta.filters`. - **`filters`** `object` — 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`page`** `integer`, default: `1` — Page number. Each page has up to 50 companies. On the Free plan outside a workspace, any page after the first returns page 1. - **`query`** `string` — 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. **Example:** ``` { "query": "Real estate agencies in Europe", "filters": { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } }, "page": 1 } ``` ### RevealFilters - **Type:**`object` 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. **Example:** ``` { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } } ``` ### SearchFilter - **Type:**`object` Values to include and exclude. A company matches when it matches any `include` value and no `exclude` value. Values are matched against Tomba's company data, which isn't normalized to a fixed list. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. **Example:** ``` { "include": [ "" ], "exclude": [ "" ] } ``` ### PremiumSearchFilter - **Type:**`object` Values to include and exclude. On the Free plan outside a workspace, a request for a page after the first is served as page 1 without these filters. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. **Example:** ``` { "include": [ "" ], "exclude": [ "" ] } ``` ### RevealSearchResponse - **Type:**`object` Company search response. - **`data` (required)** `object` — One page of companies, up to 50. - **`companies` (required)** `array | null` — The companies on this page, most popular domain first, or most relevant first when you filter by \`keywords\`. \`null\` if the search fails. - **`meta` (required)** `object` — Paging, and the filters the search used. - **`filters` (required)** `object` — 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`limit` (required)** `integer` — Companies per page. Always \`50\`. - **`page` (required)** `integer` — The page returned. \`0\` if the search fails. - **`pages` (required)** `integer` — Number of pages. - **`total` (required)** `integer` — Number of companies that match. - **`success` (required)** `boolean` — Always \`true\`. **Example:** ``` { "success": true, "data": { "companies": [ { "name": "", "description": "", "country": "", "state": "", "city": "", "street_address": "", "postal_code": "", "industry": "", "company_size": "", "type": "", "founded": "", "website_url": "", "total_emails": 1, "revenue": "", "phone_number": true, "linkedin_url": "", "facebook_url": "", "twitter_url": "", "total_similar": 1 } ] }, "meta": { "total": 1, "page": 1, "limit": 1, "pages": 1, "filters": { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } } } } ``` ### RevealMeta - **Type:**`object` Paging, and the filters the search used. - **`filters` (required)** `object` — 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. - **`company`** `object` — Company domains, such as \`stripe.com\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`founded`** `object` — Founding years, such as \`2015\`, or ranges: \`before 1990\`, \`1990-1999\`, \`2000-2009\`, \`2010-2019\`, or \`2020+\`. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`industry`** `object` — Industries, such as \`financial services\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`keywords`** `object` — Keywords matched against each company's name, industry, keywords, and description. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`location_city`** `object` — City names, such as \`San Francisco\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_country`** `object` — Two-letter country codes (ISO 3166-1 alpha-2), such as \`US\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`location_state`** `object` — State or region names, such as \`California\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`naics`** `object` — Six-digit NAICS codes, 2017 or 2022 edition, such as \`522320\`. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`revenue`** `object` — Annual revenue ranges: \`0-1m\`, \`1m-10m\`, \`10m-50m\`, \`50m-100m\`, or \`100m+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`sic`** `object` — Four-digit SIC codes, such as \`7372\`. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`similar`** `object` — Reference domains, such as \`stripe.com\`, to find similar companies. \`exclude\` isn't supported. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`size`** `object` — Employee count ranges: \`1-10\`, \`11-50\`, \`51-200\`, \`201-500\`, \`501-1000\`, \`1001-5000\`, \`5001-10000\`, or \`10001+\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. - **`technologies`** `object` — Technology names, such as \`React\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`type`** `object` — Company types, such as \`private\` or \`public\`. - **`exclude`** `array | null` — Values to exclude. - **`include`** `array | null` — Values to include. A company matches when it matches any of them. - **`limit` (required)** `integer` — Companies per page. Always \`50\`. - **`page` (required)** `integer` — The page returned. \`0\` if the search fails. - **`pages` (required)** `integer` — Number of pages. - **`total` (required)** `integer` — Number of companies that match. **Example:** ``` { "total": 1, "page": 1, "limit": 1, "pages": 1, "filters": { "company": { "include": [ "" ], "exclude": [ "" ] }, "location_country": { "include": [ "" ], "exclude": [ "" ] }, "location_city": { "include": [ "" ], "exclude": [ "" ] }, "location_state": { "include": [ "" ], "exclude": [ "" ] }, "industry": { "include": [ "" ], "exclude": [ "" ] }, "size": { "include": [ "" ], "exclude": [ "" ] }, "type": { "include": [ "" ], "exclude": [ "" ] }, "keywords": { "include": [ "" ], "exclude": [ "" ] }, "founded": { "include": [ "" ], "exclude": [ "" ] }, "technologies": { "include": [ "" ], "exclude": [ "" ] }, "similar": { "include": [ "" ], "exclude": [ "" ] }, "revenue": { "include": [ "" ], "exclude": [ "" ] }, "sic": { "include": [ "" ], "exclude": [ "" ] }, "naics": { "include": [ "" ], "exclude": [ "" ] } } } ``` ### RevealData - **Type:**`object` One page of companies, up to 50. - **`companies` (required)** `array | null` — The companies on this page, most popular domain first, or most relevant first when you filter by \`keywords\`. \`null\` if the search fails. **Example:** ``` { "companies": [ { "name": "", "description": "", "country": "", "state": "", "city": "", "street_address": "", "postal_code": "", "industry": "", "company_size": "", "type": "", "founded": "", "website_url": "", "total_emails": 1, "revenue": "", "phone_number": true, "linkedin_url": "", "facebook_url": "", "twitter_url": "", "total_similar": 1 } ] } ``` ### Company - **Type:**`object` A company returned by company search. Every field is always present; text fields are empty strings when Tomba has no value. - **`city` (required)** `string` — City. - **`company_size` (required)** `string` — Employee count range, such as \`51-200\`. Free text; not a fixed list. - **`country` (required)** `string` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`description` (required)** `string` — Short description of the company. - **`facebook_url` (required)** `string` — Facebook page URL, such as \`https\://facebook.com/StripeHQ\`. - **`founded` (required)** `string` — Year the company was founded. - **`industry` (required)** `string` — Industry. Free text; not a fixed list. - **`linkedin_url` (required)** `string` — LinkedIn company page URL, such as \`https\://linkedin.com/company/stripe\`. - **`name` (required)** `string` — Company name. - **`phone_number` (required)** `boolean` — Whether Tomba has a phone number for the company. Currently always \`false\`. - **`postal_code` (required)** `string` — Postal code. - **`revenue` (required)** `string` — Estimated annual revenue range. Free text; not a fixed list. - **`state` (required)** `string` — State or region. - **`street_address` (required)** `string` — Street address. - **`total_emails` (required)** `integer` — Number of email addresses Tomba has for the domain. - **`total_similar` (required)** `integer` — Number of similar companies Tomba has for the domain. - **`twitter_url` (required)** `string` — Twitter (X) profile URL, such as \`https\://x.com/stripe\`. - **`type` (required)** `string` — Company type. Currently always an empty string. - **`website_url` (required)** `string` — Company domain, such as \`stripe.com\`. **Example:** ``` { "name": "", "description": "", "country": "", "state": "", "city": "", "street_address": "", "postal_code": "", "industry": "", "company_size": "", "type": "", "founded": "", "website_url": "", "total_emails": 1, "revenue": "", "phone_number": true, "linkedin_url": "", "facebook_url": "", "twitter_url": "", "total_similar": 1 } ``` ### Account - **Type:**`object` * **`data` (required)** `object` — Your account, plan, and credit usage in the current usage window. - **`activity` (required)** `boolean` — Notification setting for account activity emails. - **`blocked` (required)** `boolean` — Always \`false\` here. Requests from a blocked account fail with \`403\`. - **`confirmed` (required)** `boolean` — Whether your email address is confirmed. Until it is, the data endpoints return \`401\`. - **`country` (required)** `string | null` — Your country code, for example \`US\`. - **`created_at` (required)** `string`, format: `date-time` — When the account was created. - **`deleted` (required)** `boolean` — Always \`false\` here. Requests from a deleted account fail with \`403\`. - **`email` (required)** `string` — Your email address. - **`expired` (required)** `string`, format: `date-time` — End of the current usage window, when the counts in \`requests\` reset. - **`expired_subscription` (required)** `string`, format: `date-time` — When the current subscription period ends. - **`first_name` (required)** `string` — Your first name. - **`has_password` (required)** `boolean` — Whether the account has a password. An account without one, such as one created with Google sign-in, gets \`401\` from the data endpoints until a password is set. - **`image` (required)** `string` — Profile image URL. When you haven't uploaded an image, a Gravatar URL for your email address. - **`important_updates` (required)** `boolean` — Notification setting for important account emails. - **`intercom_user_jwt` (required)** `string` — Signed token for Tomba's in-app support chat. Not needed for API use. - **`ip` (required)** `string` — IP address the account was created from. - **`issued` (required)** `string`, format: `date-time` — Start of the current usage window. The \`used\` counts in \`requests\` start here. - **`last_name` (required)** `string` — Your last name. - **`newsletter` (required)** `boolean` — Notification setting for the newsletter. - **`onboarded` (required)** `boolean` — Whether you finished the dashboard's onboarding. - **`phone` (required)** `string | null` — Your phone number. - **`pricing` (required)** `object` — Your plan and its allowances. - **`auto_upgrade` (required)** `boolean | null` — Whether automatic upgrades to the next plan are turned on. - **`available_attr` (required)** `integer`, format: `int64` — Plan value for custom lead attributes. It isn't enforced: every account can create up to 29 attributes. - **`available_email_count` (required)** `integer`, format: `int64` — Email count credits per usage window, used by email count, email format, and location. - **`available_keys` (required)** `integer`, format: `int64` — Maximum number of unexpired API keys you can hold. While you have unused credit-pack credits, you can hold at least 25. - **`available_leads` (required)** `integer`, format: `int64` — Maximum number of leads you can store. - **`available_list` (required)** `integer`, format: `int64` — Maximum number of lead lists you can create. - **`available_searches` (required)** `integer`, format: `int64` — Search credits per usage window, including your unused credit-pack credits. For a workspace member, your individual search limit if the owner set one, otherwise the owner's allowance. - **`available_sources` (required)** `integer`, format: `int64` — Email sources lookups per usage window. - **`available_teams` (required)** `integer`, format: `int64` — Maximum number of workspace members. - **`available_technology` (required)** `integer`, format: `int64` — Plan value for technology lookups. It isn't enforced. - **`available_verifications` (required)** `integer`, format: `int64` — Verification credits per usage window, including your unused credit-pack credits. For a workspace member, your individual verification limit if the owner set one, otherwise the owner's allowance. - **`cancel_url` (required)** `string | null` — Legacy billing link for cancelling the subscription. - **`frequency` (required)** `string` — Billing frequency: \`monthly\`, \`yearly\`, or \`trial\`. - **`name` (required)** `string` — Plan name. A Free account with unused credit-pack credits shows \`Free + Credit Packs\`. - **`plan_full_access` (required)** `boolean | null` — Whether you can buy plans that need approval. - **`price_monthly` (required)** `string` — The plan's monthly list price. - **`price_yearly` (required)** `string` — The plan's yearly list price. - **`pricing_id` (required)** `integer` — Plan ID. - **`pw_customer` (required)** `string | null` — Legacy billing customer ID. - **`status` (required)** `string | null` — Subscription status, for example \`active\`. - **`stripe_customer_id` (required)** `string | null` — Stripe customer ID. - **`subscription_id` (required)** `string | null` — Billing subscription ID. - **`update_url` (required)** `string | null` — Legacy billing link for updating the payment method. - **`rate_limits`** `object` — Your plan's rate limits, merged with those of your credit packs, keyed by route name. A \`default\` key, when present, applies to routes without their own key. Absent when the plan has no rate-limit settings. For a workspace member, these are your own plan's limits, not the owner's limits that apply to your requests. \`GET /rate-limits\` returns the limits actually enforced. - **`product_updates` (required)** `boolean` — Notification setting for product update emails. - **`provider` (required)** `string` — How the account was created, for example \`local\` (email and password), \`google\`, \`github\`, \`linkedin\`, \`saml\`, or \`scim\`. - **`requests` (required)** `object` — Allowances and usage in the current usage window. \`available\` is the allowance, not what's left: the remaining balance is \`available\` minus \`used\`. For a workspace member, \`used\` counts only your own usage; the owner's pool is in \`workspace.owner.usage\`. - **`count` (required)** `object` — Email count credits, used by email count, email format, and location. \`available\` equals \`pricing.available\_email\_count\`. - **`available` (required)** `integer`, format: `int64` — Email count credit allowance. - **`used` (required)** `integer`, format: `int64` — Email count credits used in this window. - **`domains` (required)** `object` — Search credits. \`available\` equals \`pricing.available\_searches\`. - **`available` (required)** `integer`, format: `int64` — Search credit allowance. - **`used` (required)** `integer`, format: `int64` — Search credits used in this window. - **`verifications` (required)** `object` — Verification credits. \`available\` equals \`pricing.available\_verifications\`. - **`available` (required)** `integer`, format: `int64` — Verification credit allowance. - **`used` (required)** `integer`, format: `int64` — Verification credits used in this window. - **`role` (required)** `integer` — Internal account role. Accounts created by sign-up have \`2\`. - **`secret_token` (required)** `string` — Your API secret, the value you send as \`X-Tomba-Secret\`. All your API keys share this one secret. Treat it like a password. - **`timezone` (required)** `string | null` — Your time zone setting, for example \`America/New\_York\`. - **`title` (required)** `string | null` — Your job title. - **`user_id` (required)** `integer`, format: `int64` — Your user ID. - **`webmail` (required)** `boolean` — Always \`false\`. - **`weekly_digest` (required)** `boolean` — Notification setting for the weekly digest email. - **`addon_credits`** `object` — Your unused credit-pack credits. Absent when you have none. - **`search_credits` (required)** `integer`, format: `int64` — Unused search credits. - **`verification_credits` (required)** `integer`, format: `int64` — Unused verification credits. - **`onboarding_data`** `object` — Your answers to the dashboard's onboarding questions. Absent when there are none. - **`workspace`** `object` — Your workspace membership. Absent when you aren't in a workspace. - **`limit` (required)** `object` — Your individual credit limits in the workspace, set by the owner. \`null\` when there's no individual limit. - **`search` (required)** `integer | null`, format: `int64` — Your search credit limit. - **`verifier` (required)** `integer | null`, format: `int64` — Your verification credit limit. - **`name` (required)** `string` — Workspace name. - **`owner` (required)** `object` — The workspace owner's plan and usage. Filled in for members who aren't the owner; for the owner, every field is \`null\`. - **`available_searches` (required)** `integer | null`, format: `int64` — The owner's search credits per usage window. - **`available_teams` (required)** `integer | null`, format: `int64` — The owner's maximum number of workspace members. - **`available_verifications` (required)** `integer | null`, format: `int64` — The owner's verification credits per usage window. - **`frequency` (required)** `string | null` — The owner's billing frequency. - **`name` (required)** `string | null` — The owner's full name. - **`usage` (required)** `object` — Credits used in the owner's current usage window, the pool that members draw from. - **`search` (required)** `integer | null`, format: `int64` — Search credits used. - **`verifier` (required)** `integer | null`, format: `int64` — Verification credits used. - **`permissions` (required)** `object` — What your role allows. - **`bulk` (required)** `boolean` — Whether you can use bulk jobs. \`false\` for guests. - **`export` (required)** `boolean` — Whether you can export data. \`false\` for guests. - **`manage_members` (required)** `boolean` — Whether you can manage members. Owners and admins only. - **`manage_settings` (required)** `boolean` — Whether you can change workspace settings. Owners and admins only. - **`share_data` (required)** `boolean` — Whether you share data with the workspace. \`false\` for guests. - **`role` (required)** `string`, possible values: `"owner", "admin", "member", "guest"` — Your role in the workspace. - **`slug` (required)** `string` — Workspace slug. - **`sso_enabled` (required)** `boolean` — Whether single sign-on is set up for the workspace. - **`sso_enforced` (required)** `string`, possible values: `"none", "optional", "required"` — Whether members must sign in with single sign-on. - **`workspace_id` (required)** `integer`, format: `int64` — Workspace ID. - **`logo_url`** `string` — Workspace logo URL. Absent when there's no logo. **Example:** ``` { "data": { "user_id": 1, "email": "", "first_name": "", "last_name": "", "secret_token": "", "role": 1, "confirmed": true, "blocked": true, "phone": null, "image": "", "deleted": true, "provider": "", "timezone": null, "newsletter": true, "activity": true, "title": null, "country": null, "created_at": "", "ip": "", "has_password": true, "onboarded": true, "onboarding_data": { "propertyName*": "anything" }, "weekly_digest": true, "product_updates": true, "important_updates": true, "webmail": true, "issued": "", "expired": "", "expired_subscription": "", "pricing": { "name": "", "pricing_id": 1, "available_searches": 1, "available_verifications": 1, "available_leads": 1, "available_list": 1, "available_attr": 1, "available_keys": 1, "available_teams": 1, "available_technology": 1, "available_sources": 1, "available_email_count": 1, "frequency": "", "price_monthly": "", "price_yearly": "", "subscription_id": null, "status": null, "pw_customer": null, "stripe_customer_id": null, "update_url": null, "cancel_url": null, "auto_upgrade": null, "plan_full_access": null, "rate_limits": { "propertyName*": { "rps": 1, "rpm": 1, "daily": 1 } } }, "workspace": { "workspace_id": 1, "name": "", "slug": "", "logo_url": "", "role": "owner", "sso_enabled": true, "sso_enforced": "none", "permissions": { "share_data": true, "export": true, "bulk": true, "manage_members": true, "manage_settings": true }, "limit": { "search": null, "verifier": null }, "owner": { "name": null, "available_teams": null, "available_searches": null, "available_verifications": null, "frequency": null, "usage": { "search": null, "verifier": null } } }, "requests": { "domains": { "available": 1, "used": 1 }, "verifications": { "available": 1, "used": 1 }, "count": { "available": 1, "used": 1 } }, "addon_credits": { "search_credits": 1, "verification_credits": 1 }, "intercom_user_jwt": "" } } ``` ### DomainSearch - **Type:**`object` Domain search response: the company in `data.organization`, one page of its email addresses in `data.emails`, and paging in `meta`. See [Company response](https://docs.tomba.io/attributes/company) and [Person response](https://docs.tomba.io/attributes/person). - **`data` (required)** `object` — The company and its email addresses. - **`emails` (required)** `array` — One page of the domain's email addresses. Empty when there are none. **Items:** - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string` — The email address. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. Empty when either is unknown. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`phone_data` (required)** `array` — Phone numbers for the person when you set \`enrich\_mobile=true\`, otherwise an empty array. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`seniority` (required)** `string | null` — \`junior\`, \`senior\`, or \`executive\`. - **`sources` (required)** `array` — Public pages where the address appears. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string`, possible values: `"personal", "generic"` — \`personal\` for an address that belongs to one person, \`generic\` for a role address. - **`verification` (required)** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`organization` (required)** `object` — The company that owns the domain. For a domain Tomba has no record of, and for a disposable or webmail domain, only \`website\_url\`, \`disposable\`, and \`webmail\` are set; the other fields are \`null\` or \`false\`. - **`accept_all` (required)** `boolean` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company_size` (required)** `string | null` — Employee count range, such as \`1-10\`. Free text; not a fixed list. - **`company_type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`description` (required)** `string | null` — Short description of the company. - **`disposable` (required)** `boolean` — \`true\` when the domain belongs to a disposable email provider. \`emails\` is then empty. - **`founded` (required)** `string | null` — Year the company was founded. - **`industries` (required)** `string | null` — Industry. Free text from several data sources, such as \`financial services\`; not a fixed list. - **`keywords` (required)** `array | null` — Keywords that describe the company. - **`last_updated` (required)** `string | null`, format: `date-time` — When Tomba last updated the company record, in RFC 3339 format. - **`location` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`postal_code` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`street_address` (required)** `string | null` — Street address. - **`organization` (required)** `string | null` — Company name. When Tomba has no name for the company, it's derived from the domain. - **`pattern` (required)** `string | null` — Email format used at the domain, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the company. Get it from the phone finder with \`domain\`. - **`ranking` (required)** `integer | null` — Popularity rank of the domain on the web. Lower is more popular. - **`revenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. Free text; not a fixed list. - **`social_links` (required)** `object` — URLs of the company's social profiles. - **`facebook_url` (required)** `string | null` — Facebook page URL. - **`github_url` (required)** `string | null` — GitHub organization URL. - **`instagram_url` (required)** `string | null` — Instagram profile URL. - **`linkedin_url` (required)** `string | null` — LinkedIn company page URL. - **`pinterest_url` (required)** `string | null` — Pinterest profile URL. - **`tiktok_url` (required)** `string | null` — TikTok profile URL. - **`twitter_url` (required)** `string | null` — Twitter (X) profile URL. - **`youtube_url` (required)** `string | null` — YouTube channel URL. - **`total_similar` (required)** `integer | null` — Number of similar companies Tomba has for the domain. List them with \`GET /similar\`. - **`webmail` (required)** `boolean` — \`true\` when the domain belongs to a webmail provider, such as Gmail. \`emails\` is then empty. - **`website_url` (required)** `string | null` — The domain. - **`whois` (required)** `object` — Domain registration from the WHOIS record. Each field is \`null\` when Tomba has no WHOIS data. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`meta` (required)** `object` — Paging for the email addresses, and the request as the API read it. - **`current` (required)** `integer` — The page returned. - **`pageSize` (required)** `integer` — Addresses per page, the \`limit\` you requested. \`10\` in a response without results. - **`params` (required)** `object` — The request parameters after normalization and defaults. - **`company` (required)** `string` — The \`company\` you sent, as a lowercase slug. Empty when not sent. - **`country` (required)** `string | null` — The \`country\` you sent, in uppercase. - **`department` (required)** `string | null` — The \`department\` you sent. - **`domain` (required)** `string` — The domain searched, in lowercase and without \`www.\`. When \`company\` matched a company, its domain. - **`enrich_mobile` (required)** `boolean` — The \`enrich\_mobile\` you sent. - **`limit` (required)** `integer` — The \`limit\` applied. - **`live` (required)** `boolean` — Not used; always \`false\` unless you send it. - **`page` (required)** `integer` — The page returned. - **`type` (required)** `string`, possible values: `"all", "personal", "generic"` — The \`type\` applied. - **`webhook_url` (required)** `string | null` — The \`webhook\_url\` you sent. - **`total` (required)** `integer` — Number of addresses Tomba has for the domain that match \`type\`. With a single \`department\`, or with \`country\`, the number for that department or country. - **`total_pages` (required)** `integer` — Number of pages at your \`limit\`, computed from the domain's total for \`type\` without the \`department\` or \`country\` filter. \`1\` in a response without results. **Example:** ``` { "data": { "organization": { "website_url": null, "organization": null, "location": { "country": null, "city": null, "state": null, "street_address": null, "postal_code": null }, "social_links": { "twitter_url": null, "facebook_url": null, "linkedin_url": null, "instagram_url": null, "github_url": null, "youtube_url": null, "pinterest_url": null, "tiktok_url": null }, "disposable": true, "webmail": true, "phone_number": true, "industries": null, "founded": null, "company_size": null, "company_type": null, "revenue": null, "accept_all": true, "description": null, "pattern": null, "total_similar": null, "keywords": [ "" ], "ranking": null, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "last_updated": null }, "emails": [ { "email": "", "first_name": null, "last_name": null, "full_name": null, "gender": null, "phone_number": true, "type": "personal", "country": null, "position": null, "department": null, "seniority": null, "twitter": null, "linkedin": null, "score": 0, "verification": { "date": null, "status": "valid" }, "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "...": "[Additional Properties Truncated]" } ], "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ] } ] }, "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1, "params": { "domain": "", "company": "", "page": 1, "limit": 1, "department": null, "country": null, "type": "all", "live": true, "enrich_mobile": true, "webhook_url": null } } } ``` ### EmailFinder - **Type:**`object` Email finder and email enrichment response. When no address is found, `data.email` is `null`, the other fields are `null`, `false`, or `0`, `sources` is `null`, and `verification` is left out. See [Person response](https://docs.tomba.io/attributes/person). - **`data` (required)** `object` — The person and their email address. - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string | null`, format: `email` — The email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Format of the address, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. Set \`enrich\_mobile=true\` to get it in \`phone\_data\`. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null`, possible values: `"personal", "generic", null` — \`personal\` for an address that belongs to one person, \`generic\` for a role address such as \`support@\`. - **`website_url` (required)** `string | null` — Company domain, such as \`stripe.com\`. - **`disposable`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a disposable email provider. - **`phone_data`** `array` — Phone numbers for the person when you set \`enrich\_mobile=true\`, otherwise an empty array. Left out when no address is found and for an address found by a live check. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`webmail`** `boolean` — Email enrichment only. \`true\` when the address's domain belongs to a webmail provider, such as Gmail. **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "disposable": true, "webmail": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } } ``` ### EmailSource - **Type:**`object` A public web page where Tomba found the email address. An address has at most 20 sources. When it has no public source, the list can contain one entry that isn't a published page: the address's page on Tomba (`website_url` `tomba.io`) when the address was verified as valid, or a Google search (`website_url` `google.com`) when Tomba matched the person to a LinkedIn profile. The dates of such an entry are the time of your request. - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. **Example:** ``` { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ``` ### FinderVerification - **Type:**`object` Result of Tomba's last check of the address. Both fields are `null` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). **Example:** ``` { "date": null, "status": "valid" } ``` ### PhoneData - **Type:**`object` A phone number with its formats, line type, carrier, region, and time zones. See [Phone response](https://docs.tomba.io/attributes/phone). - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. **Example:** ``` { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ``` ### EmailVerifier - **Type:**`object` Email verifier response. The checks are in `data.email`, the public pages where the address appears in `data.sources`, and phone numbers in `data.phone_data`. See [Email verifier response](https://docs.tomba.io/attributes/verifier). - **`data` (required)** `object` — The verification result. - **`email` (required)** `object` — The checks. - **`accept_all` (required)** `boolean` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`block` (required)** `boolean` — \`true\` when the mail server blocked or refused the check. Usually comes with status \`unknown\`. - **`disposable` (required)** `boolean` — \`true\` when the domain belongs to a disposable email provider. - **`email` (required)** `string` — The verified address. Empty when the domain is disposable. - **`gibberish` (required)** `boolean` — \`true\` when the part before \`@\` looks randomly generated. - **`greylisted` (required)** `boolean` — \`true\` when the mail server temporarily deferred the check. - **`mx` (required)** `object` — MX records of the domain. - **`records` (required)** `array | null` — MX host names. \`null\` when Tomba has no MX data for the domain. - **`mx_check` (required)** `boolean` — \`true\` when the domain has MX records. - **`regex` (required)** `boolean` — \`true\` when the address is syntactically valid. - **`result` (required)** `string`, possible values: `"deliverable", "undeliverable", "risky", ""` — Deliverability verdict: \`deliverable\`, \`undeliverable\`, or \`risky\`. Empty when the domain is disposable. See \[Result values]\(https\://docs.tomba.io/attributes/verifier#result-values). - **`score` (required)** `integer` — Confidence score: \`99\` for \`valid\`, \`77\` or more for \`accept\_all\`, \`55\` or more for an \`unknown\` check that the server blocked, \`11\` or more for \`invalid\` and other \`unknown\` results, and \`2\` for \`disposable\`. For an address Tomba has on record, each public source adds one point. - **`smtp_check` (required)** `boolean` — \`true\` when the domain has MX records, the same as \`mx\_check\`. It doesn't show whether the mailbox exists; use \`status\`. - **`smtp_provider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. - **`smtp_server` (required)** `boolean` — Same value as \`smtp\_check\`. - **`status` (required)** `string`, possible values: `"valid", "Valid", "accept_all", "invalid", "unknown", "disposable"` — Detailed outcome: \`valid\`, \`accept\_all\`, \`invalid\`, \`unknown\`, or \`disposable\`. A valid result from a live check of an address outside webmail domains is returned as \`Valid\`, with a capital V, so compare case-insensitively. There's no \`webmail\` status; check the \`webmail\` field. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`webmail` (required)** `boolean` — \`true\` when the domain belongs to a webmail provider, such as Gmail. - **`whois` (required)** `object` — Domain registration from the WHOIS record. Each field is \`null\` when Tomba has no WHOIS data for the domain. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`phone_data` (required)** `array | null` — Phone numbers for the address when you set \`enrich\_mobile=true\` and Tomba has the address on record; otherwise an empty array. \`null\` when Tomba has no record of the address, and for disposable and webmail addresses. - **`sources` (required)** `array` — Public pages where the address appears. When a valid address has no public source, the list can contain one entry that points to the address's page on Tomba. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. **Example:** ``` { "data": { "email": { "email": "", "result": "deliverable", "status": "valid", "score": 0, "smtp_provider": null, "mx": { "records": [ "" ] }, "mx_check": true, "smtp_server": true, "smtp_check": true, "accept_all": true, "greylisted": true, "block": true, "gibberish": true, "disposable": true, "webmail": true, "regex": true, "whois": { "registrar_name": null, "referral_url": null, "created_date": null } }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } } ``` ### EnrichmentPersonAPI - **Type:**`object` Person API response, in Clearbit's field format. - **`data` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#person-fields). - **`activeAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`avatar` (required)** `string | null` — Always \`null\`. - **`bio` (required)** `string | null` — Always \`null\`. - **`email` (required)** `string | null` — The email address. - **`emailProvider` (required)** `string | null` — Always \`null\`. - **`employment` (required)** `object` — Current employer and job. - **`domain` (required)** `string` — Employer's domain. - **`name` (required)** `string | null` — Employer's name. - **`role` (required)** `string | null` — Department, such as \`engineering\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`seniority` (required)** `string | null` — Always \`null\`. - **`subRole` (required)** `string | null` — Always \`null\`. - **`title` (required)** `string | null` — Job title. - **`facebook` (required)** `object` — Facebook profile. \`handle\` is always \`null\`. - **`handle` (required)** `string | null` - **`fuzzy` (required)** `boolean | null` — Always \`null\`. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`geo` (required)** `object` — Location. Only \`country\` and \`countryCode\` are filled. - **`city` (required)** `string | null` — Always \`null\`. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`state` (required)** `string | null` — Always \`null\`. - **`stateCode` (required)** `string | null` — Always \`null\`. - **`github` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`blog` (required)** `string | null` - **`company` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` - **`id` (required)** `string | null` - **`gravatar` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`avatars` (required)** `array | null` - **`handle` (required)** `string | null` - **`urls` (required)** `array | null` - **`inactiveAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`linkedin` (required)** `object` — LinkedIn profile. - **`handle` (required)** `string | null` — LinkedIn profile URL. Clearbit returns a handle here. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here. - **`name` (required)** `object` — The person's name. - **`familyName` (required)** `string` — Last name. - **`fullName` (required)** `string` — First and last name. - **`givenName` (required)** `string` — First name. - **`phone` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`site` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`favorites` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Twitter (X) profile URL. Clearbit returns a handle here. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`statuses` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`meta` (required)** `object` — The lookup. - **`email` (required)** `string` — The address you looked up. **Example:** ``` { "data": { "name": { "fullName": "", "givenName": "", "familyName": "" }, "email": null, "location": null, "gender": null, "timeZone": null, "utcOffset": null, "geo": { "city": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "bio": null, "site": null, "avatar": null, "employment": { "domain": "", "name": null, "title": null, "role": null, "subRole": null, "seniority": null }, "facebook": { "handle": null }, "github": { "handle": null, "id": null, "avatar": null, "company": null, "blog": null, "followers": null, "following": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "statuses": null, "favorites": null, "location": null, "site": null, "avatar": null }, "linkedin": { "handle": null }, "gravatar": { "handle": null, "urls": [ "" ], "avatar": null, "avatars": [ "" ] }, "verification": { "date": null, "status": "valid" }, "phone": true, "fuzzy": null, "emailProvider": null, "indexedAt": null, "activeAt": null, "inactiveAt": null }, "meta": { "email": "" } } ``` ### EnrichmentCompanyAPI - **Type:**`object` Company API response, in Clearbit's field format. - **`data` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#company-fields). - **`category` (required)** `object` — Industry codes. \`sector\`, \`industryGroup\`, \`industry\`, and \`subIndustry\` are always \`null\`. - **`industry` (required)** `string | null` - **`industryGroup` (required)** `string | null` - **`naics6Codes` (required)** `array | null` — Six-digit NAICS codes. - **`naics6Codes2022` (required)** `array | null` — Six-digit NAICS 2022 codes. - **`naicsCode` (required)** `string | null` — NAICS code. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`sector` (required)** `string | null` - **`sic4Codes` (required)** `array | null` — Four-digit SIC codes. - **`sicCode` (required)** `string | null` — SIC code. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`subIndustry` (required)** `string | null` - **`description` (required)** `string | null` — Short description of the company. - **`domain` (required)** `string | null` — The domain. - **`domainAliases` (required)** `array | null` — Always \`null\`. - **`emailProvider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. Clearbit returns a boolean here. - **`facebook` (required)** `object` — Facebook page. - **`handle` (required)** `string | null` — Handle of the company's Facebook page. - **`likes` (required)** `string | null` — Always \`null\`. - **`foundedYear` (required)** `string | null` — Year the company was founded, as a string. - **`geo` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`postalCode` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`stateCode` (required)** `string | null` — Same value as \`state\`. - **`streetAddress` (required)** `string | null` — Street address. - **`streetName` (required)** `string | null` — Same value as \`streetAddress\`. - **`streetNumber` (required)** `string | null` — Same value as \`streetAddress\`. - **`subPremise` (required)** `string | null` — Always \`null\`. - **`identifiers` (required)** `object` — Business identifiers. \`usEIN\` is always \`null\`. - **`usEIN` (required)** `string | null` - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`legalName` (required)** `string | null` — Same value as \`name\`. - **`linkedin` (required)** `object` — LinkedIn company page. - **`handle` (required)** `string | null` — Handle of the company's LinkedIn page. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`logo` (required)** `string | null` — Always \`null\`. Use the \[Logo API]\(https\://docs.tomba.io/logo-api). - **`metrics` (required)** `object` — Size and traffic. Only \`trafficRank\`, \`employees\`, \`annualRevenue\`, and \`estimatedAnnualRevenue\` are filled. - **`alexaGlobalRank` (required)** `string | null` — Always \`null\`. - **`alexaUsRank` (required)** `string | null` — Always \`null\`. - **`annualRevenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. - **`employees` (required)** `string | null` — Employee count range, such as \`51-200\`. Clearbit returns a number here. - **`estimatedAnnualRevenue` (required)** `string | null` — Same value as \`annualRevenue\`. - **`fiscalYearEnd` (required)** `string | null` — Always \`null\`. - **`marketCap` (required)** `string | null` — Always \`null\`. - **`raised` (required)** `string | null` — Always \`null\`. - **`trafficRank` (required)** `string | null` — Popularity rank of the domain on the web, as a number in a string. Lower is more popular. Clearbit returns a label such as \`very\_high\` here. - **`name` (required)** `string | null` — Company name. - **`parent` (required)** `object` — Parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`site` (required)** `object` — Contact details found on the website. - **`emailAddresses` (required)** `array | null` — Up to 6 generic (role) addresses at the domain. - **`phoneNumbers` (required)** `array | null` — The company's phone number, if Tomba has one. - **`tags` (required)** `array | null` — Keywords that describe the company. - **`tech` (required)** `array | null` — Names of the technologies detected on the website. - **`techCategories` (required)** `array | null` — Categories of those technologies. - **`ticker` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Handle of the company's Twitter (X) profile. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`ultimateParent` (required)** `object` — Ultimate parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`whois` (required)** `object` — Domain registration from the WHOIS record, with snake\_case keys. Not a Clearbit field. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`meta` (required)** `object` — The lookup. - **`domain` (required)** `string | null` — The domain you looked up. **Example:** ``` { "data": { "name": null, "legalName": null, "domain": null, "domainAliases": [ "" ], "site": { "phoneNumbers": [ "" ], "emailAddresses": [ "" ] }, "category": { "sector": null, "industryGroup": null, "industry": null, "subIndustry": null, "sicCode": null, "sic4Codes": [ "" ], "naicsCode": null, "naics6Codes": [ "" ], "naics6Codes2022": [ "" ] }, "tags": [ "" ], "description": null, "foundedYear": null, "location": null, "timeZone": null, "utcOffset": null, "geo": { "streetNumber": null, "streetName": null, "subPremise": null, "streetAddress": null, "city": null, "postalCode": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "logo": null, "facebook": { "handle": null, "likes": null }, "linkedin": { "handle": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "location": null, "site": null, "avatar": null }, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "emailProvider": null, "type": null, "ticker": null, "identifiers": { "usEIN": null }, "metrics": { "alexaUsRank": null, "alexaGlobalRank": null, "trafficRank": null, "employees": null, "marketCap": null, "raised": null, "annualRevenue": null, "estimatedAnnualRevenue": null, "fiscalYearEnd": null }, "indexedAt": null, "tech": [ "" ], "techCategories": [ "" ], "parent": { "domain": null }, "ultimateParent": { "domain": null } }, "meta": { "domain": null } } ``` ### EnrichmentCombinedAPI - **Type:**`object` Combined API response: the person and their company, in Clearbit's field format. When Tomba has no record of the address's domain, every `company` field is `null` (nested objects are still present, with `null` fields) and `meta.email` is empty. - **`data` (required)** `object` — The person and the company. - **`company` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#company-fields). - **`category` (required)** `object` — Industry codes. \`sector\`, \`industryGroup\`, \`industry\`, and \`subIndustry\` are always \`null\`. - **`industry` (required)** `string | null` - **`industryGroup` (required)** `string | null` - **`naics6Codes` (required)** `array | null` — Six-digit NAICS codes. - **`naics6Codes2022` (required)** `array | null` — Six-digit NAICS 2022 codes. - **`naicsCode` (required)** `string | null` — NAICS code. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`sector` (required)** `string | null` - **`sic4Codes` (required)** `array | null` — Four-digit SIC codes. - **`sicCode` (required)** `string | null` — SIC code. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`subIndustry` (required)** `string | null` - **`description` (required)** `string | null` — Short description of the company. - **`domain` (required)** `string | null` — The domain. - **`domainAliases` (required)** `array | null` — Always \`null\`. - **`emailProvider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. Clearbit returns a boolean here. - **`facebook` (required)** `object` — Facebook page. - **`handle` (required)** `string | null` — Handle of the company's Facebook page. - **`likes` (required)** `string | null` — Always \`null\`. - **`foundedYear` (required)** `string | null` — Year the company was founded, as a string. - **`geo` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`postalCode` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`stateCode` (required)** `string | null` — Same value as \`state\`. - **`streetAddress` (required)** `string | null` — Street address. - **`streetName` (required)** `string | null` — Same value as \`streetAddress\`. - **`streetNumber` (required)** `string | null` — Same value as \`streetAddress\`. - **`subPremise` (required)** `string | null` — Always \`null\`. - **`identifiers` (required)** `object` — Business identifiers. \`usEIN\` is always \`null\`. - **`usEIN` (required)** `string | null` - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`legalName` (required)** `string | null` — Same value as \`name\`. - **`linkedin` (required)** `object` — LinkedIn company page. - **`handle` (required)** `string | null` — Handle of the company's LinkedIn page. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`logo` (required)** `string | null` — Always \`null\`. Use the \[Logo API]\(https\://docs.tomba.io/logo-api). - **`metrics` (required)** `object` — Size and traffic. Only \`trafficRank\`, \`employees\`, \`annualRevenue\`, and \`estimatedAnnualRevenue\` are filled. - **`alexaGlobalRank` (required)** `string | null` — Always \`null\`. - **`alexaUsRank` (required)** `string | null` — Always \`null\`. - **`annualRevenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. - **`employees` (required)** `string | null` — Employee count range, such as \`51-200\`. Clearbit returns a number here. - **`estimatedAnnualRevenue` (required)** `string | null` — Same value as \`annualRevenue\`. - **`fiscalYearEnd` (required)** `string | null` — Always \`null\`. - **`marketCap` (required)** `string | null` — Always \`null\`. - **`raised` (required)** `string | null` — Always \`null\`. - **`trafficRank` (required)** `string | null` — Popularity rank of the domain on the web, as a number in a string. Lower is more popular. Clearbit returns a label such as \`very\_high\` here. - **`name` (required)** `string | null` — Company name. - **`parent` (required)** `object` — Parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`site` (required)** `object` — Contact details found on the website. - **`emailAddresses` (required)** `array | null` — Up to 6 generic (role) addresses at the domain. - **`phoneNumbers` (required)** `array | null` — The company's phone number, if Tomba has one. - **`tags` (required)** `array | null` — Keywords that describe the company. - **`tech` (required)** `array | null` — Names of the technologies detected on the website. - **`techCategories` (required)** `array | null` — Categories of those technologies. - **`ticker` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Handle of the company's Twitter (X) profile. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`ultimateParent` (required)** `object` — Ultimate parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`whois` (required)** `object` — Domain registration from the WHOIS record, with snake\_case keys. Not a Clearbit field. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. - **`person` (required)** `object` — 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]\(https\://docs.tomba.io/attributes/enrichment#person-fields). - **`activeAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`avatar` (required)** `string | null` — Always \`null\`. - **`bio` (required)** `string | null` — Always \`null\`. - **`email` (required)** `string | null` — The email address. - **`emailProvider` (required)** `string | null` — Always \`null\`. - **`employment` (required)** `object` — Current employer and job. - **`domain` (required)** `string` — Employer's domain. - **`name` (required)** `string | null` — Employer's name. - **`role` (required)** `string | null` — Department, such as \`engineering\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`seniority` (required)** `string | null` — Always \`null\`. - **`subRole` (required)** `string | null` — Always \`null\`. - **`title` (required)** `string | null` — Job title. - **`facebook` (required)** `object` — Facebook profile. \`handle\` is always \`null\`. - **`handle` (required)** `string | null` - **`fuzzy` (required)** `boolean | null` — Always \`null\`. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`geo` (required)** `object` — Location. Only \`country\` and \`countryCode\` are filled. - **`city` (required)** `string | null` — Always \`null\`. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`state` (required)** `string | null` — Always \`null\`. - **`stateCode` (required)** `string | null` — Always \`null\`. - **`github` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`blog` (required)** `string | null` - **`company` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` - **`id` (required)** `string | null` - **`gravatar` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`avatars` (required)** `array | null` - **`handle` (required)** `string | null` - **`urls` (required)** `array | null` - **`inactiveAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`linkedin` (required)** `object` — LinkedIn profile. - **`handle` (required)** `string | null` — LinkedIn profile URL. Clearbit returns a handle here. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here. - **`name` (required)** `object` — The person's name. - **`familyName` (required)** `string` — Last name. - **`fullName` (required)** `string` — First and last name. - **`givenName` (required)** `string` — First name. - **`phone` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`site` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`favorites` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Twitter (X) profile URL. Clearbit returns a handle here. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`statuses` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). - **`meta` (required)** `object` — The lookup. - **`email` (required)** `string` — The address you looked up. Empty when Tomba has no record of its domain. **Example:** ``` { "data": { "person": { "name": { "fullName": "", "givenName": "", "familyName": "" }, "email": null, "location": null, "gender": null, "timeZone": null, "utcOffset": null, "geo": { "city": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "bio": null, "site": null, "avatar": null, "employment": { "domain": "", "name": null, "title": null, "role": null, "subRole": null, "seniority": null }, "facebook": { "handle": null }, "github": { "handle": null, "id": null, "avatar": null, "company": null, "blog": null, "followers": null, "following": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "statuses": null, "favorites": null, "location": null, "site": null, "avatar": null }, "linkedin": { "handle": null }, "gravatar": { "handle": null, "urls": [ "" ], "avatar": null, "avatars": [ "" ] }, "verification": { "date": null, "status": "valid" }, "phone": true, "fuzzy": null, "emailProvider": null, "indexedAt": null, "activeAt": null, "inactiveAt": null }, "company": { "name": null, "legalName": null, "domain": null, "domainAliases": [ "" ], "site": { "phoneNumbers": [ "" ], "emailAddresses": [ "" ] }, "category": { "sector": null, "industryGroup": null, "industry": null, "subIndustry": null, "sicCode": null, "sic4Codes": [ "" ], "naicsCode": null, "naics6Codes": [ "" ], "naics6Codes2022": [ "" ] }, "tags": [ "" ], "description": null, "foundedYear": null, "location": null, "timeZone": null, "utcOffset": null, "geo": { "streetNumber": null, "streetName": null, "subPremise": null, "streetAddress": null, "city": null, "postalCode": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "logo": null, "facebook": { "handle": null, "likes": null }, "linkedin": { "handle": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "location": null, "site": null, "avatar": null }, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "emailProvider": null, "type": null, "ticker": null, "identifiers": { "usEIN": null }, "metrics": { "alexaUsRank": null, "alexaGlobalRank": null, "trafficRank": null, "employees": null, "marketCap": null, "raised": null, "annualRevenue": null, "estimatedAnnualRevenue": null, "fiscalYearEnd": null }, "indexedAt": null, "tech": [ "" ], "techCategories": [ "" ], "parent": { "domain": null }, "ultimateParent": { "domain": null } } }, "meta": { "email": "" } } ``` ### EmailCount - **Type:**`object` How many email addresses Tomba has for a domain, by email type, department, and seniority. An unknown, webmail, or disposable domain returns `0` in every count. See [Email count response](https://docs.tomba.io/attributes/email-count). - **`data` (required)** `object` — The counts. - **`department` (required)** `object` — Number of addresses of the requested \`type\` in each department. Every department is present, with \`0\` when there are none. - **`accounting` (required)** `integer` - **`administrative` (required)** `integer` - **`communication` (required)** `integer` - **`diversity` (required)** `integer` - **`education` (required)** `integer` - **`engineering` (required)** `integer` - **`executive` (required)** `integer` - **`facilities` (required)** `integer` - **`finance` (required)** `integer` - **`healthcare` (required)** `integer` - **`hr` (required)** `integer` - **`it` (required)** `integer` - **`legal` (required)** `integer` - **`management` (required)** `integer` - **`marketing` (required)** `integer` - **`operations` (required)** `integer` - **`pr` (required)** `integer` - **`sales` (required)** `integer` - **`security` (required)** `integer` - **`software` (required)** `integer` - **`support` (required)** `integer` - **`warehouse` (required)** `integer` - **`generic_emails` (required)** `integer` — Number of generic (role) addresses, such as \`support\@stripe.com\`. - **`personal_emails` (required)** `integer` — Number of personal addresses, such as \`jane.doe\@stripe.com\`. - **`seniority` (required)** `object` — Number of addresses of the requested \`type\` at each seniority level. - **`executive` (required)** `integer` - **`junior` (required)** `integer` - **`senior` (required)** `integer` - **`total` (required)** `integer` — Number of addresses of the requested \`type\`. - **`website_id` (required)** `integer` — Tomba's internal ID for the domain's company record. \`0\` when Tomba has no record of the domain. **Example:** ``` { "data": { "total": 1, "personal_emails": 1, "generic_emails": 1, "department": { "engineering": 1, "finance": 1, "hr": 1, "it": 1, "marketing": 1, "operations": 1, "management": 1, "sales": 1, "legal": 1, "support": 1, "communication": 1, "executive": 1, "accounting": 1, "administrative": 1, "diversity": 1, "facilities": 1, "pr": 1, "security": 1, "software": 1, "warehouse": 1, "healthcare": 1, "education": 1 }, "seniority": { "junior": 1, "senior": 1, "executive": 1 } }, "website_id": 1 } ``` ### Location - **Type:**`object` For each country, the number of a domain's email addresses that belong to people in that country. See [Location response](https://docs.tomba.io/attributes/location). - **`data` (required)** `array` — One entry per country, in no particular order. An empty array when Tomba has no location data for the domain. **Items:** - **`name` (required)** `string` — Two-letter country code (ISO 3166-1 alpha-2). Pass it to domain search in \`country\` to list those addresses. - **`total` (required)** `integer` — Number of the domain's email addresses in that country. **Example:** ``` { "data": [ { "name": "", "total": 1 } ] } ``` ### EmailSources - **Type:**`object` Public web pages where Tomba found an email address. See [Sources response](https://docs.tomba.io/attributes/sources). - **`data` (required)** `array` — The sources, at most 20. An empty array, with status \`201\`, when Tomba has none. **Items:** - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. - **`email` (required)** `string` — The address you asked about, trimmed and in lowercase. **Example:** ``` { "data": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "email": "" } ``` ### EmailFormat - **Type:**`object` The formats that a domain's email addresses follow, with the share of known addresses that use each one. See [Email format response](https://docs.tomba.io/attributes/format). - **`data` (required)** `array` — Up to 20 formats, in no particular order. An empty array when Tomba has no formats for the domain. **Items:** - **`format` (required)** `string` — The pattern, such as \`{first}.{last}\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`percentage` (required)** `integer` — Share of the domain's known addresses that use this pattern, from 0 to 100. **Example:** ``` { "data": [ { "format": "", "percentage": 0 } ] } ``` ### DomainSimilar - **Type:**`object` Similar companies for a domain, 25 per page. See [Similar domains response](https://docs.tomba.io/attributes/similar). - **`data` (required)** `array | null` — Similar companies. \`null\` when Tomba has none for the domain. - **`meta` (required)** `object` — Paging. - **`current` (required)** `integer` — The page returned. - **`pageSize` (required)** `integer` — Results per page. Always \`25\`. - **`params` (required)** `object` — Not used by this endpoint. Always present, with empty values. - **`company`** `string` - **`country`** `string | null` - **`department`** `string | null` - **`domain`** `string` - **`enrich_mobile`** `boolean` - **`limit`** `integer` - **`live`** `boolean` - **`page`** `integer` - **`type`** `string` - **`webhook_url`** `string | null` - **`total` (required)** `integer` — Number of similar companies Tomba has for the domain. - **`total_pages` (required)** `integer` — Number of pages. \`0\` when there are no results. **Example:** ``` { "data": [ { "website_url": "", "name": null, "industries": null } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1, "params": { "domain": "", "company": "", "page": 1, "limit": 1, "department": null, "country": null, "type": "", "live": true, "enrich_mobile": true, "webhook_url": null } } } ``` ### DomainTechnology - **Type:**`object` Technologies detected on a domain's website. See [Technology response](https://docs.tomba.io/attributes/technology). - **`data` (required)** `array | null` — One entry per technology. \`null\` when Tomba has no technology data for the domain. - **`domain`** `string` — The domain you asked about. Left out when \`data\` is \`null\`. **Example:** ``` { "domain": "", "data": [ { "slug": "", "name": "", "icon": "", "website": "", "description": "", "categories": [ { "id": 1, "slug": "", "name": "" } ] } ] } ``` ### PhoneFinder - **Type:**`object` Phone finder response. `data` is one phone number, preferring a valid one, or an array of every number found when you set `full=true`. When nothing is found, `data` is an empty array and the response repeats the identifiers you sent. - **`data` (required)** `object` — One phone number, or an array of phone numbers. An empty array when nothing is found. - **`domain`** `string` — The \`domain\` you sent, normalized. Only in a response without results. - **`email`** `string` — The \`email\` you sent, in lowercase. Only in a response without results. - **`linkedin`** `string` — The \`linkedin\` profile you sent, reduced to its permalink, such as \`jane-doe\`. Only in a response without results. **Example:** ``` { "email": "", "domain": "", "linkedin": "", "data": { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } } ``` ### Lead - **Type:**`object` * **`attributes` (required)** `object` — Custom attribute values, keyed by the attribute's \`identifier\`. Values are strings. Empty when the lead has none. At most 25 are returned. * **`company` (required)** `string | null` — Company name. * **`country` (required)** `string | null` — Two-letter country code, for example \`US\`. * **`created_at` (required)** `string`, format: `date-time` — When the lead was saved. * **`email` (required)** `string` — Email address, in lowercase. Empty when the lead was saved without one. * **`first_name` (required)** `string | null` — First name. * **`id` (required)** `integer`, format: `int64` — Lead ID. * **`last_name` (required)** `string | null` — Last name. * **`lead_source` (required)** `string | null` — Where the lead came from: \`domain\` (domain search), \`finder\` (email finder), \`verify\` (email verifier), or \`browser\` (browser extension). * **`leads_list` (required)** `object` — The lead's list. Every field is \`null\` when the lead isn't in a list you can see. - **`list_id` (required)** `integer | null`, format: `int64` — List ID. - **`name` (required)** `string | null` — List name. - **`size` (required)** `integer | null`, format: `int64` — Number of leads in the list. * **`linkedin` (required)** `string | null` — LinkedIn profile URL. * **`list_id` (required)** `integer | null`, format: `int64` — ID of the lead's list. * **`notes` (required)** `string | null` — Notes. * **`phone_number` (required)** `string | null` — Phone number. * **`position` (required)** `string | null` — Job title. * **`score` (required)** `integer | null` — Lead score, up to 100. * **`sync_airtable` (required)** `boolean | null` — Whether the lead was synced to Airtable. * **`sync_hubspot` (required)** `boolean | null` — Whether the lead was synced to HubSpot. * **`sync_mailchimp` (required)** `boolean | null` — Whether the lead was synced to Mailchimp. * **`sync_pipedrive` (required)** `boolean | null` — Whether the lead was synced to Pipedrive. * **`sync_status` (required)** `string | null` — State of the last sync to a connected app: \`pending\`, \`error\`, or \`success\`. * **`twitter` (required)** `string | null` — Twitter profile URL. * **`updated_at` (required)** `string`, format: `date-time` — When the lead was last changed. * **`user_id` (required)** `integer`, format: `int64` — User who saved the lead. * **`website_url` (required)** `string | null` — Company domain. **Example:** ``` { "id": 1, "user_id": 1, "email": "", "list_id": null, "first_name": null, "last_name": null, "country": null, "website_url": null, "position": null, "twitter": null, "linkedin": null, "phone_number": null, "company": null, "notes": null, "lead_source": null, "score": null, "sync_status": null, "sync_airtable": null, "sync_hubspot": null, "sync_mailchimp": null, "sync_pipedrive": null, "created_at": "", "updated_at": "", "leads_list": { "list_id": null, "size": null, "name": null }, "attributes": { "propertyName*": "" } } ``` ### LeadAttribute - **Type:**`object` * **`created_at` (required)** `string`, format: `date-time` — When the attribute was created. * **`id` (required)** `integer`, format: `int64` — Attribute ID. * **`identifier` (required)** `string` — Key for the attribute's values in a lead's \`attributes\`: the name as a lowercase slug, so \`Deal size\` becomes \`deal-size\`. * **`name` (required)** `string` — Attribute name. * **`type` (required)** `string` — Value type: \`string\`, \`date\`, or \`number\`. * **`updated_at` (required)** `string`, format: `date-time` — When the attribute was last changed. * **`user_id` (required)** `integer`, format: `int64` — User who created the attribute. **Example:** ``` { "id": 1, "user_id": 1, "name": "", "identifier": "", "type": "", "created_at": "", "updated_at": "" } ``` ### LeadsList - **Type:**`object` * **`created_at` (required)** `string`, format: `date-time` — When the list was created. * **`favorite` (required)** `boolean` — Whether the list is marked as a favorite. * **`id` (required)** `integer`, format: `int64` — List ID. * **`name` (required)** `string` — List name. * **`size` (required)** `integer`, format: `int64` — 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. * **`updated_at` (required)** `string`, format: `date-time` — When the list was last changed. * **`user_id` (required)** `integer`, format: `int64` — User who created the list. * **`type`** `string` — List type. Lists created with this API have \`campaigns\`. Absent when empty. **Example:** ``` { "id": 1, "user_id": 1, "size": 1, "name": "", "type": "", "favorite": true, "created_at": "", "updated_at": "" } ``` ### APIKey - **Type:**`object` * **`created_at` (required)** `string`, format: `date-time` — When the key was created. * **`expired` (required)** `boolean` — Whether the key is past its expiry date. * **`id` (required)** `integer`, format: `int64` — Key ID. * **`ip` (required)** `string` — IP address the key was created or last rotated from. * **`is_owner` (required)** `boolean` — \`true\` when the key is yours, \`false\` when it belongs to a workspace teammate. * **`key` (required)** `string` — The key value, \`ta\_\` followed by 37 characters. Send it as \`X-Tomba-Key\`. * **`name` (required)** `string` — Label for the key. * **`updated_at` (required)** `string`, format: `date-time` — When the key was last changed. * **`user_id` (required)** `integer`, format: `int64` — User ID of the key's owner. A key authenticates as its owner, and its requests are charged to the owner. * **`created_by`** `integer`, format: `int64` — User ID of whoever created the key. Absent on older keys. * **`creator_email`** `string` — Email address of whoever created the key. Absent when the creator is unknown. * **`creator_image`** `string` — Profile image URL of whoever created the key. Absent when there's none. * **`creator_name`** `string` — Name of whoever created the key, or their email address when they have no name. Absent when the creator is unknown. * **`expires_at`** `string`, format: `date-time` — 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. * **`expires_in_days`** `integer` — Whole days until the key expires, negative once it has expired. Absent when \`expires\_at\` is absent. * **`last_used_at`** `string`, format: `date-time` — Last time the key authenticated a request, updated at most once an hour. Absent if the key hasn't been used. **Example:** ``` { "id": 1, "user_id": 1, "key": "", "name": "CI runner", "ip": "", "expires_at": "", "created_by": 1, "last_used_at": "", "created_at": "", "updated_at": "", "is_owner": true, "expired": true, "expires_in_days": 87, "creator_name": "", "creator_email": "", "creator_image": "" } ``` ### Usage - **Type:**`object` Daily credit usage and totals for the requested range. - **`data` (required)** `array | null` — 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. - **`total` (required)** `object` — Sums over the rows in \`data\`. There's no \`email\_count\` total. - **`export` (required)** `integer` — Legacy export counter. - **`search` (required)** `integer` — Search credits. - **`source_api` (required)** `integer` — Credits charged through direct API calls. - **`source_bulk` (required)** `integer` — Credits charged for bulk job downloads. - **`source_extension` (required)** `integer` — Credits charged through the browser extension. - **`source_sheets` (required)** `integer` — Credits charged through the Google Sheets add-on. - **`source_website` (required)** `integer` — Credits charged through the Tomba website. - **`sources` (required)** `integer` — Email sources credits. - **`verifier` (required)** `integer` — Verification credits. **Example:** ``` { "data": [ { "id": 1, "user_id": 1, "search": 1, "verifier": 1, "export": 1, "sources": 1, "email_count": 1, "source_website": 1, "source_bulk": 1, "source_extension": 1, "source_api": 1, "source_sheets": 1, "created_at": "" } ], "total": { "search": 1, "verifier": 1, "export": 1, "sources": 1, "source_website": 1, "source_extension": 1, "source_bulk": 1, "source_api": 1, "source_sheets": 1 } } ``` ### Log - **Type:**`object` One billable lookup. Only requests to endpoints that cost credits, and that returned `200` with a result, are logged, including repeats charged `0`. - **`cost` (required)** `integer` — Credits charged. \`0\` for a repeat of a lookup already charged in the current usage window. - **`country` (required)** `string` — Two-letter country code of the caller's IP address. Empty when unknown. - **`created_at` (required)** `string`, format: `date-time` — When the request was made. - **`hash` (required)** `string` — Fingerprint of the request's parameters. Tomba uses it to recognize a repeat of a lookup already charged in the current usage window. - **`id` (required)** `integer`, format: `int64` — Log row ID. - **`ip_address` (required)** `string` — The caller's IP address. - **`params` (required)** `object | null` — The request's query parameters and top-level JSON body fields, as strings. - **`source` (required)** `string` — Where the request came from: \`API\`, \`Website\`, \`Browser extension\`, \`Google Sheets add-on\`, \`Bulk API\`, or \`MCP Agent\`. - **`type` (required)** `string` — 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\`. - **`uri` (required)** `string` — \`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. - **`user_agent` (required)** `string` — The request's \`User-Agent\` header. - **`user_id` (required)** `integer`, format: `int64` — User who made the request. - **`api_key_id`** `integer`, format: `int64` — ID of the API key that made the request. Absent for requests made with an OAuth access token or from the dashboard. - **`duration_ms`** `integer` — Time Tomba took to handle the request, in milliseconds. Absent on older rows. - **`endpoint`** `string` — Path you called, for example \`/v1/domain-search\`. Absent on older rows. - **`http_method`** `string` — HTTP method. Absent on older rows. - **`request_id`** `string` — Request ID, on rows that recorded one. Rows logged by the current API don't record it, so the field is usually absent. - **`route_name`** `string` — Internal route name, for example \`domain-search\`, \`enrich-finder\`, or \`SearchCompanies\`. Absent on older rows. - **`status_code`** `integer` — HTTP status of the response, always \`200\`. Absent on older rows. **Example:** ``` { "id": 1, "user_id": 1, "uri": "", "params": null, "type": "", "hash": "", "cost": 1, "route_name": "", "source": "", "country": "", "user_agent": "", "ip_address": "", "http_method": "", "status_code": 1, "request_id": "", "endpoint": "", "api_key_id": 1, "duration_ms": 1, "created_at": "" } ``` ### OperationSuccess - **Type:**`object` * **`data` (required)** `object` — Result of an update or delete. - **`code` (required)** `integer` — HTTP status code, \`200\`. - **`message` (required)** `string` — Human-readable confirmation. - **`status` (required)** `boolean` — Always \`true\`. Failures return an error response instead. **Example:** ``` { "data": { "status": true, "message": "", "code": 1 } } ``` ### APIErrorResponse - **Type:**`object` Standard error envelope returned by the API. `errors` is always a single object, never an array. - **`errors` (required)** `object` — Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "errors": { "type": "params_invalid", "message": "The domain parameter is required.", "code": 400 } } ``` ### BulkCreate - **Type:**`object` Parameters of `POST /bulk/{type}`. Send the input as one of `list`, `data`, or `file`. With `data` or `file`, each column is found from the header row unless you set its zero-based `*_field_index`. A parameter a type doesn't use returns `422`, except `verify_emails`, which is ignored; unknown parameters are ignored. See [Create a job](https://docs.tomba.io/bulks#create-a-job). - **`boost_score_from_sources`** `boolean`, default: `false` — 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. - **`company_name_field_index`** `integer` — Zero-based column of the company name. Used by \`search\`, \`similar\`, \`company\`, and \`finder\`. - **`country_field_index`** `integer` — Zero-based column of the country code. Used by \`phone-validator\`. - **`data`** `array` — 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. **Items:** **Array of:** `string` - **`delimiter`** `string`, default: `","` — Column separator of the uploaded file: \`,\`, \`;\`, \`|\`, or \`tab\`. Any other value is read as \`,\`. - **`departments`** `array` — Used by \`search\`. With \`departments\_mode\` \`only\`, only addresses in these departments are returned. **Items:** `string`, possible values: `"all", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"` - **`departments_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses in \`departments\`; \`priority\` returns every department. - **`domain`** `string` — The domain to export. Required for \`export\`, and used by no other type. - **`domain_field_index`** `integer` — Zero-based column of the domain or website. Used by \`search\`, \`similar\`, \`company\`, \`finder\`, and \`phone-finder\`. - **`email_field_index`** `integer` — Zero-based column of the email address. Used by \`enrich\`, \`verifier\`, and \`phone-finder\`. - **`email_type`** `string`, possible values: `"all", "personal", "generic"`, default: `"all"` — Used by \`search\`. With \`email\_type\_mode\` \`only\`, only addresses of this type are returned. - **`email_type_mode`** `string`, possible values: `"only", "priority"`, default: `"only"` — \`only\` returns only the addresses of \`email\_type\`; \`priority\` returns every type. - **`filter`** `string`, possible values: `"all", "personal", "generic", "engineering", "sales", "finance", "hr", "it", "marketing", "operations", "management", "executive", "legal", "support", "communication", "software", "security", "pr", "warehouse", "diversity", "administrative", "facilities", "accounting"`, default: `"all"` — Used by \`export\`. The addresses to export, by type or by department. - **`find_all_phones`** `boolean`, default: `false` — Used by \`phone-finder\`. Returns every phone number found instead of one. - **`find_phones`** `boolean`, default: `false` — Adds phone numbers, at an extra cost. Used by \`search\`, \`company\`, \`finder\`, \`enrich\`, \`linkedin\`, \`verifier\`, and \`export\`. - **`first_name_field_index`** `integer` — Zero-based column of the first name. Used by \`finder\`. - **`full_name_field_index`** `integer` — Zero-based column of the full name. Used by \`finder\`. - **`has_header`** `boolean`, default: `true` — Whether the first row of \`data\` or of the file is a header. A \`list\` has no header. - **`include_sources`** `boolean`, default: `false` — Adds the web pages where each address was found. Used by \`search\`, \`finder\`, \`enrich\`, \`linkedin\`, \`author\`, \`verifier\`, and \`export\`. - **`input_type`** `string`, possible values: `"domain", "company"` — 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. - **`last_name_field_index`** `integer` — Zero-based column of the last name. Used by \`finder\`. - **`launch`** `boolean`, default: `false` — 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. - **`linkedin_url_field_index`** `integer` — Zero-based column of the LinkedIn profile URL. Used by \`linkedin\` and \`phone-finder\`. - **`list`** `string` — 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\`. - **`max_emails_per_domain`** `integer`, possible values: `1, 10, 20, 50, 100`, default: `10` — Used by \`search\` and \`similar\`. Addresses returned per domain. - **`name`** `string` — Job name, 3 to 200 characters. Required, except for a domain export, which is named after its domain. - **`notify`** `boolean`, default: `false` — Emails you when the job finishes with at least one result. - **`phone_field_index`** `integer` — Zero-based column of the phone number. Used by \`phone-validator\`. - **`skip_rows_with_email`** `boolean`, default: `false` — Used by \`finder\`. Skips the rows that already have a value in a column named \`email\`. - **`technology_field_index`** `integer` — Zero-based column of the technology slug. Used by \`technology\`. - **`url_field_index`** `integer` — Zero-based column of the article URL. Used by \`author\`. - **`verify_emails`** `boolean`, default: `false` — 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]\(https\://docs.tomba.io/bulks#billing). - **`webhook_url`** `string`, format: `uri` — 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]\(https\://docs.tomba.io/webhook#bulk-job-events). **Example:** ``` { "name": "", "list": "", "data": [ [ "" ] ], "has_header": true, "delimiter": ",", "domain": "", "domain_field_index": 0, "company_name_field_index": 0, "first_name_field_index": 0, "last_name_field_index": 0, "full_name_field_index": 0, "email_field_index": 0, "linkedin_url_field_index": 0, "url_field_index": 0, "phone_field_index": 0, "country_field_index": 0, "technology_field_index": 0, "input_type": "domain", "max_emails_per_domain": 10, "email_type": "all", "email_type_mode": "only", "departments": [ "all" ], "departments_mode": "only", "verify_emails": false, "find_phones": false, "include_sources": false, "boost_score_from_sources": false, "skip_rows_with_email": false, "find_all_phones": false, "filter": "all", "notify": false, "launch": false, "webhook_url": "" } ``` ### BulkJob - **Type:**`object` A bulk job. `preview` is returned only by `GET /bulk/{type}/{id}`. - **`archived` (required)** `boolean` - **`billed` (required)** `boolean` — Whether the results were downloaded, which charges the job, once. - **`bulk_id` (required)** `integer`, format: `int64` — Job ID. - **`bulk_type` (required)** `string` — The job's type. Phone finder jobs are \`phone\`. - **`cancelled_at` (required)** `string | null`, format: `date-time` - **`completed_at` (required)** `string | null`, format: `date-time` - **`config` (required)** `object` — The job's input and options, as set when it was created. - **`input`** `object` - **`delimiter`** `string` — Column separator of the input. - **`fields`** `object` — Zero-based column of each field, as set or detected from the header. - **`file_size`** `integer` — Size of the uploaded file, in bytes. - **`has_header`** `boolean` — Whether the first row was a header. - **`original_file_name`** `string` — Name of the uploaded file. - **`rows`** `integer` — Rows accepted for processing. - **`source`** `string`, possible values: `"list", "data", "file"` — How the input was sent. - **`notify`** `boolean` — Whether an email is sent when the job finishes with results. - **`options`** `object` — The options, with their defaults filled in. See \`POST /bulk/{type}\` for each one. - **`boost_score_from_sources`** `boolean` - **`departments`** `array` **Items:** `string` - **`departments_mode`** `string` - **`email_type`** `string` - **`email_type_mode`** `string` - **`filter`** `string` - **`find_all_phones`** `boolean` - **`find_phones`** `boolean` - **`include_sources`** `boolean` - **`input_type`** `string` - **`max_emails_per_domain`** `integer` - **`skip_rows_with_email`** `boolean` - **`verify_emails`** `boolean` - **`quota_snapshot`** `object` — \`technology\` only: your search balance when the job was created, which caps the websites returned per technology. - **`searches`** `integer` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`webhook`** `object` — Where job events are sent. Absent without \`webhook\_url\`. - **`url`** `string` - **`created_at` (required)** `string`, format: `date-time` - **`error_message` (required)** `string | null` — Why the job failed. - **`expired` (required)** `boolean` — Whether \`expired\_at\` has passed. An expired job can no longer be downloaded, launched, or retried. - **`expired_at` (required)** `string`, format: `date-time` — 180 days after \`created\_at\`. Download the results before this date. - **`metrics` (required)** `object` — The job's results. They are updated while the job runs (\`partial\` is \`true\`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`name` (required)** `string` - **`processed` (required)** `integer` — Rows processed. - **`progress` (required)** `integer` — Percentage of the rows processed. - **`retry_count` (required)** `integer` — How many times the job was retried. - **`started_at` (required)** `string | null`, format: `date-time` - **`status` (required)** `string`, possible values: `"pending", "running", "completed", "failed", "cancelled"` — \`pending\` until launched, then \`running\`. \`completed\`, \`failed\`, and \`cancelled\` are final. - **`user_id` (required)** `integer`, format: `int64` — ID of the user who created the job. - **`preview`** `array` — The first rows of the results, once \`billed\` is \`true\`; an empty array before. Their fields depend on the type. **Items:** **Example:** ``` { "bulk_id": 1, "user_id": 1, "bulk_type": "", "name": "", "status": "pending", "archived": true, "progress": 0, "processed": 1, "billed": true, "error_message": null, "retry_count": 1, "created_at": "", "started_at": null, "completed_at": null, "cancelled_at": null, "expired": true, "expired_at": "", "config": { "v": 1, "input": { "source": "list", "has_header": true, "delimiter": "", "original_file_name": "", "file_size": 1, "rows": 1, "fields": { "propertyName*": 1 } }, "options": { "input_type": "", "max_emails_per_domain": 1, "email_type": "", "email_type_mode": "", "departments": [ "" ], "departments_mode": "", "verify_emails": true, "find_phones": true, "include_sources": true, "boost_score_from_sources": true, "find_all_phones": true, "skip_rows_with_email": true, "filter": "" }, "notify": true, "webhook": { "url": "" }, "quota_snapshot": { "searches": 1 } }, "metrics": { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } }, "preview": [ { "propertyName*": "anything" } ] } ``` ### BulkConfig - **Type:**`object` The job's input and options, as set when it was created. - **`input`** `object` - **`delimiter`** `string` — Column separator of the input. - **`fields`** `object` — Zero-based column of each field, as set or detected from the header. - **`file_size`** `integer` — Size of the uploaded file, in bytes. - **`has_header`** `boolean` — Whether the first row was a header. - **`original_file_name`** `string` — Name of the uploaded file. - **`rows`** `integer` — Rows accepted for processing. - **`source`** `string`, possible values: `"list", "data", "file"` — How the input was sent. - **`notify`** `boolean` — Whether an email is sent when the job finishes with results. - **`options`** `object` — The options, with their defaults filled in. See \`POST /bulk/{type}\` for each one. - **`boost_score_from_sources`** `boolean` - **`departments`** `array` **Items:** `string` - **`departments_mode`** `string` - **`email_type`** `string` - **`email_type_mode`** `string` - **`filter`** `string` - **`find_all_phones`** `boolean` - **`find_phones`** `boolean` - **`include_sources`** `boolean` - **`input_type`** `string` - **`max_emails_per_domain`** `integer` - **`skip_rows_with_email`** `boolean` - **`verify_emails`** `boolean` - **`quota_snapshot`** `object` — \`technology\` only: your search balance when the job was created, which caps the websites returned per technology. - **`searches`** `integer` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`webhook`** `object` — Where job events are sent. Absent without \`webhook\_url\`. - **`url`** `string` **Example:** ``` { "v": 1, "input": { "source": "list", "has_header": true, "delimiter": "", "original_file_name": "", "file_size": 1, "rows": 1, "fields": { "propertyName*": 1 } }, "options": { "input_type": "", "max_emails_per_domain": 1, "email_type": "", "email_type_mode": "", "departments": [ "" ], "departments_mode": "", "verify_emails": true, "find_phones": true, "include_sources": true, "boost_score_from_sources": true, "find_all_phones": true, "skip_rows_with_email": true, "filter": "" }, "notify": true, "webhook": { "url": "" }, "quota_snapshot": { "searches": 1 } } ``` ### BulkMetrics - **Type:**`object` The job's results. They are updated while the job runs (`partial` is `true`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. **Example:** ``` { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } } ``` ### BulkBucket - **Type:**`object` One share of a distribution. - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` **Example:** ``` { "key": "", "label": "", "count": 1, "percent": 1 } ``` ### BulkCredits - **Type:**`object` Credits of a job. Phone data is billed as search credits: `phone` is included in `search`, and `total` is `search` plus `verify`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` **Example:** ``` { "search": 1, "verify": 1, "phone": 1, "total": 1 } ``` ### BulkProgress - **Type:**`object` Progress of a bulk job. - **`error_message` (required)** `string | null` — Why the job failed. - **`eta_seconds` (required)** `integer | null` — Estimated seconds until the job completes. \`null\` until enough rows are processed. - **`metrics` (required)** `object` — The job's results. They are updated while the job runs (\`partial\` is \`true\`) and final once it completes. - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`distribution`** `object` — Only the distributions that apply to the type are present. - **`confidence`** `array` — Addresses by score range. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`departments`** `array` — Addresses by department. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`email_type`** `array` — Addresses by type, personal or generic. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`phone_type`** `array` — Phone numbers by line type. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`rows`** `array` — Rows found and not found. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`verification`** `array` — Addresses by verification status. **Items:** - **`count`** `integer` - **`key`** `string` - **`label`** `string` - **`percent`** `number` - **`emails`** `object` — Types that return email addresses only. - **`deliverable_rate`** `number` — Valid addresses as a percentage of the verified ones. - **`per_found_row`** `number` - **`total`** `integer` — Addresses found. - **`webmail`** `integer` - **`with_sources`** `integer` — Addresses found on at least one web page. - **`errors`** `object` - **`client`** `integer` - **`rate_limited`** `integer` - **`server`** `integer` - **`partial`** `boolean` — \`true\` while the job is running. - **`phones`** `object` — Types that return phone numbers only. - **`rows_with_phone`** `integer` - **`total`** `integer` - **`results`** `object` - **`found`** `integer` — Rows with at least one result. - **`hit_rate`** `number` — \`found\` as a percentage of \`found\` plus \`not\_found\`. - **`not_found`** `integer` — Rows without a result. - **`records`** `integer` — Rows in the \`full\` results file, such as addresses, websites, or phone numbers. - **`rows`** `object` - **`duplicates`** `integer` — Rows dropped at creation because they repeat an earlier value. - **`errors`** `integer` — Rows whose lookup failed. - **`input`** `integer` — Non-empty rows sent. - **`invalid_input`** `integer` — Rows dropped at creation because the value isn't valid for the type. - **`processed`** `integer` — Rows processed so far. - **`skipped`** `integer` — Rows not processed, because they were over the row limit or an option skipped them. - **`valid_input`** `integer` — Rows accepted for processing. - **`timing`** `object` - **`duration_ms`** `integer` — Processing time, in milliseconds. - **`queued_ms`** `integer` — Time between launch and start, in milliseconds. - **`rows_per_minute`** `number` - **`v`** `integer` — Version of this document. Currently \`1\`. - **`processed` (required)** `integer` — Rows processed so far. - **`progress` (required)** `integer` — Percentage of the rows processed. - **`rows_per_minute` (required)** `number | null` — Processing speed. \`null\` until enough rows are processed. - **`status` (required)** `string`, possible values: `"pending", "running", "completed", "failed", "cancelled"` — \`pending\` until the job is launched. \`completed\`, \`failed\`, and \`cancelled\` are final. **Example:** ``` { "status": "pending", "progress": 0, "processed": 1, "error_message": null, "rows_per_minute": null, "eta_seconds": null, "metrics": { "v": 1, "partial": true, "rows": { "input": 1, "valid_input": 1, "invalid_input": 1, "duplicates": 1, "skipped": 1, "processed": 1, "errors": 1 }, "results": { "found": 1, "not_found": 1, "hit_rate": 1, "records": 1 }, "distribution": { "rows": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "verification": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "email_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "confidence": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "departments": [ { "key": "", "label": "", "count": 1, "percent": 1 } ], "phone_type": [ { "key": "", "label": "", "count": 1, "percent": 1 } ] }, "emails": { "total": 1, "per_found_row": 1, "with_sources": 1, "webmail": 1, "deliverable_rate": 1 }, "phones": { "total": 1, "rows_with_phone": 1 }, "errors": { "client": 1, "server": 1, "rate_limited": 1 }, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "timing": { "queued_ms": 1, "duration_ms": 1, "rows_per_minute": 1 } } } ``` ### BulkEstimate - **Type:**`object` The credits of a job. Before it completes, an upper bound, as if every row returned the maximum. Once it completes, exactly what the first download charges. - **`basis`** `string`, possible values: `"upper_bound", "exact"` — \`upper\_bound\` before the job completes, \`exact\` after. - **`billed`** `boolean` — Whether the job was already charged. Later downloads are free. - **`bulk_id`** `integer`, format: `int64` - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`note`** `string` - **`remaining`** `object` — Your remaining search and verification credits. - **`search`** `integer` - **`verify`** `integer` - **`rows`** `integer` — Rows to process. - **`status`** `string` - **`sufficient`** `boolean` — Whether your remaining credits cover \`credits\`. Always \`true\` once billed. **Example:** ``` { "bulk_id": 1, "status": "", "basis": "upper_bound", "billed": true, "rows": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "remaining": { "search": 1, "verify": 1 }, "sufficient": true, "note": "" } ``` ### BulkEvent - **Type:**`object` One entry of a job's history. - **`actor`** `string`, possible values: `"user", "worker", "admin", "system"` - **`created_at`** `string`, format: `date-time` - **`event`** `string`, possible values: `"created", "launched", "started", "completed", "failed", "cancelled", "retried", "downloaded", "renamed", "archived", "restored", "deleted", "webhook_delivered", "webhook_failed"` - **`id`** `integer`, format: `int64` - **`message`** `string | null` — Why the job failed, for \`failed\` events. - **`meta`** `object | null` — 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. - **`user_id`** `integer | null`, format: `int64` — The user who acted, or \`null\` for Tomba. **Example:** ``` { "id": 1, "user_id": null, "event": "created", "actor": "user", "message": null, "meta": null, "created_at": "" } ``` ### BulkTypeInfo - **Type:**`object` A bulk type, with its input, options, and limits. - **`allows_upload`** `boolean` — Whether it accepts a file. - **`app_path`** `string` — Its page in the web app, under \`https\://app.tomba.io/bulk/\`. - **`auto_launch`** `boolean` — Whether its jobs start when created. - **`creates_per_day`** `integer` - **`description`** `string` - **`distributions`** `array` — The \`metrics.distribution\` keys it fills. **Items:** `string` - **`downloads`** `array` — The result files it can have. **Items:** `string` - **`downloads_per_job_per_day`** `integer` - **`fields`** `array` **Items:** - **`field`** `string` - **`header_synonyms`** `array` — Header names that are matched to this field, ignoring case, spaces, and punctuation. **Items:** `string` - **`label`** `string` - **`param`** `string` — Its \`\*\_field\_index\` parameter. - **`file_required`** `boolean` — Whether it needs \`data\` or \`file\`, and refuses a \`list\`. - **`label`** `string` - **`max_rows`** `integer` - **`options`** `array` — The options it accepts. **Items:** `string` - **`path`** `string` — The \`{type}\` in its URLs. - **`phone_credits_per_phone`** `integer` — Search credits per phone number found. - **`primary_field`** `string` — The field a \`list\` or a single column is read as. - **`storage`** `string` - **`type`** `string` — The \`bulk\_type\` of its jobs. - **`verify`** `object` - **`always`** `boolean` — Whether it always verifies (\`verifier\`). - **`max_emails_per_domain`** `integer` — Above this \`max\_emails\_per\_domain\`, \`verify\_emails\` is turned off. - **`max_rows`** `integer` — Above this many rows, \`verify\_emails\` is turned off. **Example:** ``` { "type": "", "path": "", "label": "", "description": "", "app_path": "", "storage": "", "allows_upload": true, "file_required": true, "primary_field": "", "fields": [ { "field": "", "param": "", "label": "", "header_synonyms": [ "" ] } ], "options": [ "" ], "max_rows": 1, "verify": { "always": true, "max_rows": 1, "max_emails_per_domain": 1 }, "creates_per_day": 1, "downloads_per_job_per_day": 1, "auto_launch": true, "downloads": [ "" ], "distributions": [ "" ], "phone_credits_per_phone": 1 } ``` ### BulkStats - **Type:**`object` Bulk activity of your account, or of your workspace, over a period. Credits count billed jobs only. - **`by_type`** `array` **Items:** - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`found`** `integer` - **`hit_rate`** `number` - **`jobs`** `integer` - **`label`** `string` - **`rows_processed`** `integer` - **`type`** `string` - **`credits`** `object` — Credits of a job. Phone data is billed as search credits: \`phone\` is included in \`search\`, and \`total\` is \`search\` plus \`verify\`. - **`phone`** `integer` - **`search`** `integer` - **`total`** `integer` - **`verify`** `integer` - **`daily`** `array` **Items:** - **`credits`** `integer` - **`date`** `string`, format: `date` - **`jobs`** `integer` - **`rows_processed`** `integer` - **`emails_found`** `integer` - **`found`** `integer` - **`from`** `string`, format: `date-time` - **`hit_rate`** `number` - **`jobs`** `object` — Jobs created in the period, by status. - **`cancelled`** `integer` - **`completed`** `integer` - **`failed`** `integer` - **`pending`** `integer` - **`running`** `integer` - **`total`** `integer` - **`rows_processed`** `integer` - **`to`** `string`, format: `date-time` **Example:** ``` { "from": "", "to": "", "jobs": { "total": 1, "pending": 1, "running": 1, "completed": 1, "failed": 1, "cancelled": 1 }, "rows_processed": 1, "found": 1, "emails_found": 1, "hit_rate": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 }, "by_type": [ { "type": "", "label": "", "jobs": 1, "rows_processed": 1, "found": 1, "hit_rate": 1, "credits": { "search": 1, "verify": 1, "phone": 1, "total": 1 } } ], "daily": [ { "date": "", "jobs": 1, "rows_processed": 1, "credits": 1 } ] } ``` ### BulkWebhookSecret - **Type:**`object` The key bulk job events are signed with. See [Bulk job events](https://docs.tomba.io/webhook#bulk-job-events). - **`created_at`** `string`, format: `date-time` - **`rotated_at`** `string | null`, format: `date-time` - **`secret`** `string` — \`whsec\_\` followed by the base64-encoded key. **Example:** ``` { "secret": "", "created_at": "", "rotated_at": null } ``` ### BulkActionResult - **Type:**`object` * **`code` (required)** `integer` — Always \`200\`. * **`message` (required)** `string` — What was done. * **`status` (required)** `boolean` — Always \`true\`. **Example:** ``` { "status": true, "message": "", "code": 1 } ``` ### BulkPutRename - **Type:**`object` * **`name` (required)** `string` — New name of the job, 3 to 200 characters. **Example:** ``` { "name": "" } ``` ### PaginationMeta - **Type:**`object` * **`current` (required)** `integer` — Current page number * **`pageSize` (required)** `integer` — Items per page * **`total` (required)** `integer` — Total number of items * **`total_pages` (required)** `number` — Total number of pages **Example:** ``` { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } ``` ### APIError - **Type:**`object` Error details object used in reusable error responses. - **`code` (required)** `integer` — HTTP status code associated with the error. - **`message` (required)** `string` — Human-readable error message. - **`type` (required)** `string`, possible values: `"params_invalid", "unknown_record", "unknown_route", "not_found", "rate_limit", "quota_exceeded", "api_error", "internal_error", "ip_blocked", "authentication_failed", "api_key_expired", "invalid_token", "insufficient_scope", "forbidden", "claimed_email", "claimed_linkedin", "claimed_phone", "proxy_error", "duplicate_record", "openai_error", "search_failed"` — Machine-readable error type. **Example:** ``` { "type": "rate_limit", "message": "Rate limit exceeded (daily). Limit is 4000 requests. Retry after 32400 seconds.", "code": 429 } ``` ### DomainSuggestionsResponse - **Type:**`object` Companies whose name or domain matches the query, at most five. See [Domain suggestions response](https://docs.tomba.io/attributes/domain-suggestions). - **`data` (required)** `array | null` — Suggested companies. An empty array when nothing matches, \`null\` if the lookup fails. - **`meta` (required)** `object` — The query and the maximum number of suggestions. - **`limit` (required)** `integer` — Maximum number of suggestions. Always \`5\`, or \`0\` if the lookup fails. - **`query` (required)** `string` — Your query, trimmed and in lowercase. Empty if the lookup fails. **Example:** ``` { "data": [ { "name": "Stripe", "domain": "stripe.com", "email_count": 1250 } ], "meta": { "query": "stripe", "limit": 5 } } ``` ### DomainSuggestion - **Type:**`object` A company whose name or domain matches the query. - **`domain` (required)** `string` — Company domain. - **`email_count` (required)** `integer` — Number of email addresses Tomba has for the domain. - **`name` (required)** `string` — Company name. **Example:** ``` { "name": "Stripe", "domain": "stripe.com", "email_count": 1250 } ``` ### SuggestionsMeta - **Type:**`object` The query and the maximum number of suggestions. - **`limit` (required)** `integer` — Maximum number of suggestions. Always \`5\`, or \`0\` if the lookup fails. - **`query` (required)** `string` — Your query, trimmed and in lowercase. Empty if the lookup fails. **Example:** ``` { "query": "stripe", "limit": 5 } ``` ### LinkedinFinder - **Type:**`object` LinkedIn finder response. `data` is one person, or an array of up to two addresses stored for the profile when you set `full=true`. When no address is found, `data` is a single object whose `email` is `null`, even with `full=true`. - **`data` (required)** `object` — One result, or an array of results with \`full=true\`. **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "...": "[Additional Properties Truncated]" } ] } } ``` ### LinkedinFinderData - **Type:**`object` A person found from a LinkedIn profile. When no address is found, `email` is `null`, the other fields are `null`, `false`, or `0`, `sources` is `null`, and `verification` is left out. See [Person response](https://docs.tomba.io/attributes/person). - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Department, such as \`engineering\`. Empty when unknown, \`null\` with \`full=true\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`email` (required)** `string | null`, format: `email` — The email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Format of the address, such as \`{first}.{last}\`. \`null\` with \`full=true\`. See \[Patterns]\(https\://docs.tomba.io/attributes/format#patterns). - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. Set \`enrich\_mobile=true\` to get it in \`phone\_data\`. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null`, possible values: `"personal", "generic", null` — \`personal\` for an address that belongs to one person, \`generic\` for a role address. \`null\` with \`full=true\`. - **`website_url` (required)** `string | null` — Company domain, such as \`stripe.com\`. - **`phone_data`** `array` — 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. **Items:** - **`carrier` (required)** `string | null` — Carrier the number was assigned to. Empty when unknown. - **`country_code` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the number. - **`e164_format` (required)** `string | null` — E.164 format, such as \`+14155550132\`. - **`intl_format` (required)** `string | null` — International format, such as \`+1 415-555-0132\`. - **`line_type` (required)** `string | null`, possible values: `"FIXED_LINE", "MOBILE", "FIXED_LINE_OR_MOBILE", "TOLL_FREE", "PREMIUM_RATE", "SHARED_COST", "VOIP", "PERSONAL_NUMBER", "PAGER", "UAN", "UNKNOWN", null` — 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]\(https\://docs.tomba.io/attributes/phone#line-types). - **`local_format` (required)** `string | null` — National format, such as \`(415) 555-0132\`. - **`region` (required)** `object | null` — State or province of the number. \`null\` when the number doesn't identify one. - **`code` (required)** `string` — ISO 3166-2 subdivision code without the country prefix, such as \`CA\`. - **`name` (required)** `string` — Subdivision name, such as \`California\`. - **`rfc3966_format` (required)** `string | null` — RFC 3966 URI, such as \`tel:+1-415-555-0132\`. - **`timezones` (required)** `array | null` — IANA time zones of the number, such as \`America/Los\_Angeles\`. - **`valid` (required)** `boolean | null` — \`true\` if the number is valid in its country's numbering plan. - **`domain`** `string` — Phone finder only. The domain the number was found for. Left out when empty. - **`email`** `string` — Phone finder only. The email address the number was found for. Left out when empty. - **`linkedin`** `string` — Phone finder only. The LinkedIn profile URL the number was found for. Left out when empty. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). **Example:** ``` { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": "personal", "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "phone_data": [ { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } ] } ``` ### LinkedinFinderSource - **Type:**`object` A public web page where Tomba found the email address. Same shape as `EmailSource`. - **`extracted_on` (required)** `string`, format: `date-time` — When Tomba first found the address on the page, in RFC 3339 format. - **`last_seen_on` (required)** `string`, format: `date-time` — When Tomba last saw the address on the page, in RFC 3339 format. - **`still_on_page` (required)** `boolean` — \`true\` if the address was on the page when Tomba last checked it. - **`uri` (required)** `string` — URL of the page where the address was found. - **`website_url` (required)** `string` — Host name of that page, such as \`stripe.com\`. **Example:** ``` { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ``` ### LinkedinFinderVerification - **Type:**`object` Result of Tomba's last check of the address. Same shape as `FinderVerification`. Both fields are `null` when Tomba hasn't checked the address. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check. **Example:** ``` { "date": null, "status": "valid" } ``` ### AuthorFinder - **Type:**`object` Author finder response. When no address is found, `data.email` is `null`, the other fields are `null`, `false`, or `0`, `sources` is `null`, and `verification` is left out; `info` is still returned when the page could be read. See [Person response](https://docs.tomba.io/attributes/person#author-finder). - **`data` (required)** `object` — The article's author and their email address. - **`accept_all` (required)** `boolean | null` — \`true\` when the domain's mail server accepts mail for any address (catch-all). - **`company` (required)** `string | null` — Company name. - **`country` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`department` (required)** `string | null` — Always \`null\` for the author finder. - **`email` (required)** `string | null`, format: `email` — The author's email address. \`null\` when no address is found. - **`first_name` (required)** `string | null` — First name. - **`full_name` (required)** `string | null` — First and last name. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`last_name` (required)** `string | null` — Last name. - **`linkedin` (required)** `string | null` — LinkedIn profile URL. - **`pattern` (required)** `string | null` — Always \`null\` for the author finder. - **`phone_number` (required)** `boolean` — \`true\` when Tomba has a phone number for the author. - **`position` (required)** `string | null` — Job title. - **`score` (required)** `integer` — 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. - **`sources` (required)** `array | null` — Public pages where the address appears. \`null\` when no address is found. - **`twitter` (required)** `string | null` — Twitter (X) profile URL. - **`type` (required)** `string | null` — Always \`null\` for the author finder. - **`website_url` (required)** `string | null` — Domain of the author's company, such as \`stripe.com\`. - **`info`** `object` — The article the author finder read, with every author candidate found on the page. Left out when the page couldn't be read. Text fields are empty strings when the page doesn't provide them. - **`article_domain` (required)** `string` — Domain that hosts the article. - **`candidates` (required)** `array | null` — People named as the author on the page, best match first. \`null\` when none were found. - **`description` (required)** `string` — Article description. - **`og_image` (required)** `string` — URL of the article's Open Graph image. - **`publish_date` (required)** `string` — Publication date, as it appears on the page. - **`publisher_name` (required)** `string` — Name of the publication. - **`title` (required)** `string` — Article title. - **`url` (required)** `string` — The article URL. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). **Example:** ``` { "data": { "email": null, "first_name": null, "last_name": null, "full_name": null, "website_url": null, "company": null, "pattern": null, "department": null, "type": null, "position": null, "country": null, "gender": null, "twitter": null, "linkedin": null, "score": 0, "accept_all": null, "phone_number": true, "verification": { "date": null, "status": "valid" }, "sources": [ { "uri": "", "website_url": "", "extracted_on": "", "last_seen_on": "", "still_on_page": true } ], "info": { "url": "", "title": "", "og_image": "", "description": "", "article_domain": "", "publisher_name": "", "publish_date": "", "candidates": [ { "full_name": "", "first_name": "", "last_name": "", "email": "", "image": "", "gravatar": true, "linkedin": "", "twitter": "", "facebook": "", "github": "", "...": "[Additional Properties Truncated]" } ] } } } ``` ### AuthorInfo - **Type:**`object` The article the author finder read, with every author candidate found on the page. Left out when the page couldn't be read. Text fields are empty strings when the page doesn't provide them. - **`article_domain` (required)** `string` — Domain that hosts the article. - **`candidates` (required)** `array | null` — People named as the author on the page, best match first. \`null\` when none were found. - **`description` (required)** `string` — Article description. - **`og_image` (required)** `string` — URL of the article's Open Graph image. - **`publish_date` (required)** `string` — Publication date, as it appears on the page. - **`publisher_name` (required)** `string` — Name of the publication. - **`title` (required)** `string` — Article title. - **`url` (required)** `string` — The article URL. **Example:** ``` { "url": "", "title": "", "og_image": "", "description": "", "article_domain": "", "publisher_name": "", "publish_date": "", "candidates": [ { "full_name": "", "first_name": "", "last_name": "", "email": "", "image": "", "gravatar": true, "linkedin": "", "twitter": "", "facebook": "", "github": "", "instagram": "", "youtube": "", "mastodon": "", "bluesky": "", "author_url": "", "website": "", "job_title": "", "bio": "", "sources": [ "" ], "name_confidence": 1, "score": 1, "count": 1 } ] } ``` ### FlagCreateRequest - **Type:**`object` * **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What you're reporting. * **`reason` (required)** `string`, possible values: `"hard_bounce", "invalid_email", "wrong_person", "outdated", "wrong_company", "wrong_phone", "broken_url", "other"` — 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. * **`value` (required)** `string` — The item you're reporting, such as the email address, domain, phone number, or URL. * **`comment`** `string` — Details that help Tomba review the report, such as the bounce message your mail server received. **Example:** ``` { "flag_type": "email", "value": "", "reason": "hard_bounce", "comment": "" } ``` ### FlagItem - **Type:**`object` * **`created_at` (required)** `string`, format: `date-time` — When you submitted the report. * **`credits_refunded` (required)** `integer` — Credits returned for the report: \`1\` when Tomba confirmed an \`email\` report with the reason \`hard\_bounce\` and returned a search credit, otherwise \`0\`. * **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What was reported. * **`id` (required)** `integer`, format: `int64` — Report ID. * **`reason` (required)** `string` — Why the data was reported. * **`status` (required)** `string`, possible values: `"pending", "confirmed", "rejected"` — Review status. A new report is \`pending\` until Tomba confirms or rejects it. * **`value` (required)** `string` — The reported item. * **`comment`** `string` — Your comment. Absent when you didn't send one. * **`resolved_at`** `string`, format: `date-time` — When Tomba reviewed the report. Absent until then. **Example:** ``` { "id": 1, "flag_type": "email", "value": "", "reason": "", "comment": "", "status": "pending", "credits_refunded": 1, "resolved_at": "", "created_at": "" } ``` ### FlagResponse - **Type:**`object` * **`data` (required)** `object` - **`created_at` (required)** `string`, format: `date-time` — When you submitted the report. - **`credits_refunded` (required)** `integer` — Credits returned for the report: \`1\` when Tomba confirmed an \`email\` report with the reason \`hard\_bounce\` and returned a search credit, otherwise \`0\`. - **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What was reported. - **`id` (required)** `integer`, format: `int64` — Report ID. - **`reason` (required)** `string` — Why the data was reported. - **`status` (required)** `string`, possible values: `"pending", "confirmed", "rejected"` — Review status. A new report is \`pending\` until Tomba confirms or rejects it. - **`value` (required)** `string` — The reported item. - **`comment`** `string` — Your comment. Absent when you didn't send one. - **`resolved_at`** `string`, format: `date-time` — When Tomba reviewed the report. Absent until then. **Example:** ``` { "data": { "id": 1, "flag_type": "email", "value": "", "reason": "", "comment": "", "status": "pending", "credits_refunded": 1, "resolved_at": "", "created_at": "" } } ``` ### FlagListResponse - **Type:**`object` * **`data` (required)** `array` — Your reports, one page at a time. **Items:** - **`created_at` (required)** `string`, format: `date-time` — When you submitted the report. - **`credits_refunded` (required)** `integer` — Credits returned for the report: \`1\` when Tomba confirmed an \`email\` report with the reason \`hard\_bounce\` and returned a search credit, otherwise \`0\`. - **`flag_type` (required)** `string`, possible values: `"email", "organization", "phone", "author_url", "website"` — What was reported. - **`id` (required)** `integer`, format: `int64` — Report ID. - **`reason` (required)** `string` — Why the data was reported. - **`status` (required)** `string`, possible values: `"pending", "confirmed", "rejected"` — Review status. A new report is \`pending\` until Tomba confirms or rejects it. - **`value` (required)** `string` — The reported item. - **`comment`** `string` — Your comment. Absent when you didn't send one. - **`resolved_at`** `string`, format: `date-time` — When Tomba reviewed the report. Absent until then. * **`meta` (required)** `object` - **`current` (required)** `integer` — Current page number - **`pageSize` (required)** `integer` — Items per page - **`total` (required)** `integer` — Total number of items - **`total_pages` (required)** `number` — Total number of pages **Example:** ``` { "data": [ { "id": 1, "flag_type": "email", "value": "", "reason": "", "comment": "", "status": "pending", "credits_refunded": 1, "resolved_at": "", "created_at": "" } ], "meta": { "total": 1, "pageSize": 1, "current": 1, "total_pages": 1 } } ``` ### RateLimits - **Type:**`object` Rate limits and current usage for each rate-limited route. - **`data` (required)** `object` — 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. **Example:** ``` { "data": { "propertyName*": { "limits": { "rps": 1, "rpm": 1, "daily": 1 }, "usage": { "rpm_used": 1, "daily_used": 1 } } } } ``` ### RouteLimits - **Type:**`object` Rate limits for one route. `0` means unlimited. - **`daily` (required)** `integer` — Requests per day. The day runs from 00:00 UTC. - **`rpm` (required)** `integer` — Requests per minute. - **`rps` (required)** `integer` — Requests per second. **Example:** ``` { "rps": 1, "rpm": 1, "daily": 1 } ``` ### PhoneValidator - **Type:**`object` Phone validator response. For a valid number, `data` holds its details. For a number that isn't valid, `data` is an empty array and `phone` repeats your input. - **`data` (required)** `object` — The number's details, or an empty array when the number isn't valid. - **`phone`** `string` — The \`phone\` you sent. Only in the response for a number that isn't valid. **Example:** ``` { "phone": "", "data": { "email": "", "domain": "", "linkedin": "", "valid": null, "local_format": null, "intl_format": null, "e164_format": null, "rfc3966_format": null, "country_code": null, "line_type": "FIXED_LINE", "carrier": null, "region": { "name": "", "code": "" }, "timezones": [ "" ] } } ``` ### EnrichmentPersonData - **Type:**`object` 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](https://docs.tomba.io/attributes/enrichment#person-fields). - **`activeAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`avatar` (required)** `string | null` — Always \`null\`. - **`bio` (required)** `string | null` — Always \`null\`. - **`email` (required)** `string | null` — The email address. - **`emailProvider` (required)** `string | null` — Always \`null\`. - **`employment` (required)** `object` — Current employer and job. - **`domain` (required)** `string` — Employer's domain. - **`name` (required)** `string | null` — Employer's name. - **`role` (required)** `string | null` — Department, such as \`engineering\`. See \[Departments]\(https\://docs.tomba.io/attributes/person#departments). - **`seniority` (required)** `string | null` — Always \`null\`. - **`subRole` (required)** `string | null` — Always \`null\`. - **`title` (required)** `string | null` — Job title. - **`facebook` (required)** `object` — Facebook profile. \`handle\` is always \`null\`. - **`handle` (required)** `string | null` - **`fuzzy` (required)** `boolean | null` — Always \`null\`. - **`gender` (required)** `string | null` — \`male\` or \`female\`. - **`geo` (required)** `object` — Location. Only \`country\` and \`countryCode\` are filled. - **`city` (required)** `string | null` — Always \`null\`. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`state` (required)** `string | null` — Always \`null\`. - **`stateCode` (required)** `string | null` — Always \`null\`. - **`github` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`blog` (required)** `string | null` - **`company` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` - **`id` (required)** `string | null` - **`gravatar` (required)** `object` — Every field is always \`null\`. - **`avatar` (required)** `string | null` - **`avatars` (required)** `array | null` - **`handle` (required)** `string | null` - **`urls` (required)** `array | null` - **`inactiveAt` (required)** `string | null`, format: `date-time` — Always \`null\`. - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`linkedin` (required)** `object` — LinkedIn profile. - **`handle` (required)** `string | null` — LinkedIn profile URL. Clearbit returns a handle here. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). Clearbit returns a full location here. - **`name` (required)** `object` — The person's name. - **`familyName` (required)** `string` — Last name. - **`fullName` (required)** `string` — First and last name. - **`givenName` (required)** `string` — First name. - **`phone` (required)** `boolean` — \`true\` when Tomba has a phone number for the person. - **`site` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`favorites` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Twitter (X) profile URL. Clearbit returns a handle here. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`statuses` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`verification`** `object` — Result of Tomba's last check of the address. Both fields are \`null\` when Tomba hasn't checked it. - **`date` (required)** `string | null`, format: `date-time` — When Tomba last checked the address, in RFC 3339 format. - **`status` (required)** `string | null`, possible values: `"valid", "accept_all", "invalid", "unknown", null` — Result of the last check: \`valid\`, \`accept\_all\`, \`invalid\`, or \`unknown\`. See \[Status values]\(https\://docs.tomba.io/attributes/verifier#status-values). **Example:** ``` { "name": { "fullName": "", "givenName": "", "familyName": "" }, "email": null, "location": null, "gender": null, "timeZone": null, "utcOffset": null, "geo": { "city": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "bio": null, "site": null, "avatar": null, "employment": { "domain": "", "name": null, "title": null, "role": null, "subRole": null, "seniority": null }, "facebook": { "handle": null }, "github": { "handle": null, "id": null, "avatar": null, "company": null, "blog": null, "followers": null, "following": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "statuses": null, "favorites": null, "location": null, "site": null, "avatar": null }, "linkedin": { "handle": null }, "gravatar": { "handle": null, "urls": [ "" ], "avatar": null, "avatars": [ "" ] }, "verification": { "date": null, "status": "valid" }, "phone": true, "fuzzy": null, "emailProvider": null, "indexedAt": null, "activeAt": null, "inactiveAt": null } ``` ### EnrichmentCompanyData - **Type:**`object` 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](https://docs.tomba.io/attributes/enrichment#company-fields). - **`category` (required)** `object` — Industry codes. \`sector\`, \`industryGroup\`, \`industry\`, and \`subIndustry\` are always \`null\`. - **`industry` (required)** `string | null` - **`industryGroup` (required)** `string | null` - **`naics6Codes` (required)** `array | null` — Six-digit NAICS codes. - **`naics6Codes2022` (required)** `array | null` — Six-digit NAICS 2022 codes. - **`naicsCode` (required)** `string | null` — NAICS code. See \[NAICS codes]\(https\://docs.tomba.io/attributes/naics). - **`sector` (required)** `string | null` - **`sic4Codes` (required)** `array | null` — Four-digit SIC codes. - **`sicCode` (required)** `string | null` — SIC code. See \[SIC codes]\(https\://docs.tomba.io/attributes/sic). - **`subIndustry` (required)** `string | null` - **`description` (required)** `string | null` — Short description of the company. - **`domain` (required)** `string | null` — The domain. - **`domainAliases` (required)** `array | null` — Always \`null\`. - **`emailProvider` (required)** `string | null` — Mail provider detected from the domain's MX records, such as \`Google\`. Clearbit returns a boolean here. - **`facebook` (required)** `object` — Facebook page. - **`handle` (required)** `string | null` — Handle of the company's Facebook page. - **`likes` (required)** `string | null` — Always \`null\`. - **`foundedYear` (required)** `string | null` — Year the company was founded, as a string. - **`geo` (required)** `object` — Headquarters address. - **`city` (required)** `string | null` — City. - **`country` (required)** `string | null` — Country name, such as \`United States\`. Empty when the country is unknown. - **`countryCode` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2). - **`lat` (required)** `number | null` — Always \`null\`. - **`lng` (required)** `number | null` — Always \`null\`. - **`postalCode` (required)** `string | null` — Postal code. - **`state` (required)** `string | null` — State or region. - **`stateCode` (required)** `string | null` — Same value as \`state\`. - **`streetAddress` (required)** `string | null` — Street address. - **`streetName` (required)** `string | null` — Same value as \`streetAddress\`. - **`streetNumber` (required)** `string | null` — Same value as \`streetAddress\`. - **`subPremise` (required)** `string | null` — Always \`null\`. - **`identifiers` (required)** `object` — Business identifiers. \`usEIN\` is always \`null\`. - **`usEIN` (required)** `string | null` - **`indexedAt` (required)** `string | null`, format: `date-time` — When Tomba last updated the record, in RFC 3339 format. - **`legalName` (required)** `string | null` — Same value as \`name\`. - **`linkedin` (required)** `object` — LinkedIn company page. - **`handle` (required)** `string | null` — Handle of the company's LinkedIn page. - **`location` (required)** `string | null` — Two-letter country code (ISO 3166-1 alpha-2) of the headquarters. - **`logo` (required)** `string | null` — Always \`null\`. Use the \[Logo API]\(https\://docs.tomba.io/logo-api). - **`metrics` (required)** `object` — Size and traffic. Only \`trafficRank\`, \`employees\`, \`annualRevenue\`, and \`estimatedAnnualRevenue\` are filled. - **`alexaGlobalRank` (required)** `string | null` — Always \`null\`. - **`alexaUsRank` (required)** `string | null` — Always \`null\`. - **`annualRevenue` (required)** `string | null` — Estimated annual revenue range, such as \`$10M-$50M\`. - **`employees` (required)** `string | null` — Employee count range, such as \`51-200\`. Clearbit returns a number here. - **`estimatedAnnualRevenue` (required)** `string | null` — Same value as \`annualRevenue\`. - **`fiscalYearEnd` (required)** `string | null` — Always \`null\`. - **`marketCap` (required)** `string | null` — Always \`null\`. - **`raised` (required)** `string | null` — Always \`null\`. - **`trafficRank` (required)** `string | null` — Popularity rank of the domain on the web, as a number in a string. Lower is more popular. Clearbit returns a label such as \`very\_high\` here. - **`name` (required)** `string | null` — Company name. - **`parent` (required)** `object` — Parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`site` (required)** `object` — Contact details found on the website. - **`emailAddresses` (required)** `array | null` — Up to 6 generic (role) addresses at the domain. - **`phoneNumbers` (required)** `array | null` — The company's phone number, if Tomba has one. - **`tags` (required)** `array | null` — Keywords that describe the company. - **`tech` (required)** `array | null` — Names of the technologies detected on the website. - **`techCategories` (required)** `array | null` — Categories of those technologies. - **`ticker` (required)** `string | null` — Always \`null\`. - **`timeZone` (required)** `string | null` — Always \`null\`. - **`twitter` (required)** `object` — Twitter (X) profile. Only \`handle\` is filled. - **`avatar` (required)** `string | null` - **`bio` (required)** `string | null` - **`followers` (required)** `string | null` - **`following` (required)** `string | null` - **`handle` (required)** `string | null` — Handle of the company's Twitter (X) profile. - **`id` (required)** `string | null` - **`location` (required)** `string | null` - **`site` (required)** `string | null` - **`type` (required)** `string | null` — Company type, such as \`private\`. Free text; not a fixed list. - **`ultimateParent` (required)** `object` — Ultimate parent company. \`domain\` is always \`null\`. - **`domain` (required)** `string | null` - **`utcOffset` (required)** `integer | null` — Always \`null\`. - **`whois` (required)** `object` — Domain registration from the WHOIS record, with snake\_case keys. Not a Clearbit field. - **`created_date` (required)** `string | null`, format: `date-time` — When the domain was registered, in RFC 3339 format. - **`referral_url` (required)** `string | null` — URL of the registrar. - **`registrar_name` (required)** `string | null` — Name of the registrar. **Example:** ``` { "name": null, "legalName": null, "domain": null, "domainAliases": [ "" ], "site": { "phoneNumbers": [ "" ], "emailAddresses": [ "" ] }, "category": { "sector": null, "industryGroup": null, "industry": null, "subIndustry": null, "sicCode": null, "sic4Codes": [ "" ], "naicsCode": null, "naics6Codes": [ "" ], "naics6Codes2022": [ "" ] }, "tags": [ "" ], "description": null, "foundedYear": null, "location": null, "timeZone": null, "utcOffset": null, "geo": { "streetNumber": null, "streetName": null, "subPremise": null, "streetAddress": null, "city": null, "postalCode": null, "state": null, "stateCode": null, "country": null, "countryCode": null, "lat": null, "lng": null }, "logo": null, "facebook": { "handle": null, "likes": null }, "linkedin": { "handle": null }, "twitter": { "handle": null, "id": null, "bio": null, "followers": null, "following": null, "location": null, "site": null, "avatar": null }, "whois": { "registrar_name": null, "created_date": null, "referral_url": null }, "emailProvider": null, "type": null, "ticker": null, "identifiers": { "usEIN": null }, "metrics": { "alexaUsRank": null, "alexaGlobalRank": null, "trafficRank": null, "employees": null, "marketCap": null, "raised": null, "annualRevenue": null, "estimatedAnnualRevenue": null, "fiscalYearEnd": null }, "indexedAt": null, "tech": [ "" ], "techCategories": [ "" ], "parent": { "domain": null }, "ultimateParent": { "domain": null } } ```