Copy page

Resources

API changelog

This page lists changes to the Tomba API (v1), newest first. Refreshes of Tomba's data are listed in Data updates, and SDK release notes are on each SDK's GitHub repository, linked from SDKs. API versioning explains which changes count as breaking.

September 2026

• Breaking September 30: Bulk jobs take new parameter names, and the old ones are ignored. maximum is now max_emails_per_domain; the email_type and department objects are email_type with email_type_mode, and departments with departments_mode; verify is verify_emails, sources is include_sources, phone is find_phones, full is find_all_phones, valid is boost_score_from_sources, skip is skip_rows_with_email, and notifie is notify. The one-based column and column_* parameters are replaced by zero-based *_field_index parameters, and columns are found from the header row when you don't set them. Downloads take file instead of type, and lists take archived=true instead of filter=archived. Update your create requests; see Create a job.
• Breaking September 30: Bulk jobs return their options in config and their results in metrics. These replace input_type, maximum, email_type, department, sources, verify, phone, full, notifie, upload, total, total_list, total_emails, chart, time_track, search_cost, verify_cost, phone_cost, launched, and processed_email; used is now billed, and table is preview. GET /v1/bulk/{type}/{id} returns the job as an object in data, and 404 unknown_record for a missing job instead of an empty array. The progress of a job that isn't launched has the status pending instead of {"data": []}, and an action that the job's status doesn't allow returns 409 invalid_state instead of 404. DELETE /v1/bulk/linkedin/{id} is removed; use DELETE /v1/bulk/linkedin/{id}/delete. A job past its expired_at, 180 days after it was created, can no longer be downloaded, launched, or retried: those requests return 409 invalid_state. See Job fields.
• September 30: Bulk jobs accept rows as JSON data, start when created with launch, and send a signed event to webhook_url when they end. Lists take expired=true or false. New routes cancel, retry, restore, and estimate a job and return its history, and GET /v1/bulk/types, GET /v1/bulk/stats, and GET /v1/bulk/webhook-secret return the bulk types, your bulk activity, and the key events are signed with. The limit of 2 jobs per type now counts running jobs only. See Bulk operations and Bulk job events.
• September 21: People can now remove their phone number or LinkedIn profile from Tomba, as well as their email address. Phone Finder, Phone Validator, and LinkedIn Finder return 451 with error type claimed_phone or claimed_linkedin for removed data; delete that data from your records. See Data removal.
• Breaking September 20: A key and secret that don't match an account now return 401 instead of 400, as do requests from an account that is unconfirmed, has no password set, or has an expired subscription. Missing, malformed, and expired credentials still return 400; if your client branches on the status code, handle both. See Authentication errors.
• Breaking September 20: API keys now expire, and existing keys were given an expiry date. A request with an expired key fails with 400 and error type api_key_expired, and the X-Tomba-Key-Expired header gives the expiry time. Keys also gain a name, expires_at, and last_used_at; POST /v1/keys accepts name and expires_in_days, and PATCH /v1/keys/{id} renames a key. Check your keys' expires_at and rotate them before they lapse. See Key expiry.
• September 8: OAuth apps can register themselves with dynamic client registration at POST /v1/oauth/register. See OAuth 2.0.

August 2026

• August 29: The API accepts OAuth 2.0 access tokens, sent as Authorization: Bearer <access_token>, as an alternative to a key and secret. Apps get tokens through the authorization code flow with PKCE or the device flow, and discover the endpoints at https://api.tomba.io/.well-known/oauth-authorization-server. See OAuth 2.0.
• Breaking August 28: GET /v1/logs is now paginated: it returns 20 entries per page by default, with a meta object, instead of up to 3,000 entries in one response. Use page and limit to read further pages. Entries gain http_method, status_code, endpoint, duration_ms, and api_key_id, the endpoint accepts filters such as type, status_code, start, and end, and GET /v1/logs/{id} returns one entry. See Retrieve API logs.
• August 25: POST /v1/flag reports an incorrect result, and GET /v1/flag lists your reports. See Flag incorrect data and Refunds for incorrect data.
• August 12: A request can now run for up to 180 seconds before the gateway ends it with 504. Set your client timeout to at least 180 seconds. See Response format.
• August 12: Higher-tier plans no longer have per-endpoint rate limits. See Limits by plan.
• August 3: Rate limits now depend on your plan and apply to each endpoint per second, per minute, and per day. Responses carry RateLimit, RateLimit-Policy, and x-*-rate-limit headers, a 429 carries Retry-After, and GET /v1/rate-limits returns the limits that apply to your account. See Rate limits and Retrieve rate limits.

July 2026

• July 30: Email addresses whose owners asked Tomba to remove them are left out of Domain Search results. Email Finder, Email Verifier, Author Finder, Email Enrichment, and the person and combined enrichment endpoints return 451 with error type claimed_email for them; delete that address from your records. See Data removal.

April 2026

• Breaking April 21: When your search or verification balance is lower than a request's cost, the request now fails with 402 and error type quota_exceeded, instead of 429 and rate_limit. Domain Search returns the request's estimated cost in the X-Estimated-Cost header, and Email Verifier in X-Estimated-Verify-Cost. Handle 402 separately from 429, and don't retry it. See Credit costs.

March 2026

• March 28: Finder, verifier, enrichment, and phone finder endpoints accept an optional webhook_url parameter. Tomba returns the result as usual and also posts it to that URL. See Per-request callbacks.

February 2026

• February 26: LinkedIn Finder accepts full=true to return every address Tomba has stored for the profile instead of the single most likely one. See LinkedIn Finder.
• February 4: Email Finder, Email Enrichment, and LinkedIn Finder accept enrich_mobile=true to include the person's phone numbers in data.phone_data. Phone numbers cost extra credits; see Credit costs.

January 2026

• Breaking January 19: Email Format reports its quota in the X-Count-Limit and X-Count-Remaining headers instead of X-Search-Limit and X-Search-Remaining. Update any code that reads those headers from Email Format responses. See Check usage.

December 2025

• December 29: Similar domains is paginated: it accepts page and limit and returns a meta object. See Similar.

September 2025

• September 3: POST /v1/reveal/search accepts an API key and secret. See Search companies.

June 2025

• June 13: GET /v1/location returns, for each country, how many of a domain's email addresses belong to people there. See Location.

May 2025

• May 22: Phone Finder is available at GET /v1/phone-finder. The older /v1/phone/{email} path keeps working; see Legacy paths.
• May 21: GET /v1/phone-validator checks whether a phone number is valid, and Phone Finder accepts a domain as well as an email. See Phone validator and Phone finder.
• May 21: GET /v1/domain-suggestions returns companies whose name or domain matches a query, with their domains. See Get domain suggestions.

April 2025

• April 17: GET /v1/people/find, GET /v1/companies/find, and GET /v1/combined/find enrich a person, a company, or both. See Person API, Company API, and Combined API.