# API changelog

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

## September 2026

- <Badge variant="warning">Breaking</Badge> 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](/bulks#create-a-job).
- <Badge variant="warning">Breaking</Badge> 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](/bulks#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](/bulks) and [Bulk job events](/webhook#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](/data#data-removal).
- <Badge variant="warning">Breaking</Badge> 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](/authentication#errors).
- <Badge variant="warning">Breaking</Badge> 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](/authentication#key-expiry).
- September 8: OAuth apps can register themselves with dynamic client registration at `POST /v1/oauth/register`. See [OAuth 2.0](/authentication#oauth-20).

## 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](/authentication#oauth-20).
- <Badge variant="warning">Breaking</Badge> 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](/api/account#retrieve-api-logs).
- August 25: `POST /v1/flag` reports an incorrect result, and `GET /v1/flag` lists your reports. See [Flag incorrect data](/api/flag#flag-incorrect-data) and [Refunds for incorrect data](/usage-and-quotas#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](/introduction#response-format).
- August 12: Higher-tier plans no longer have per-endpoint rate limits. See [Limits by plan](/rate-limits#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](/rate-limits) and [Retrieve rate limits](/api/account#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](/data#data-removal).

## April 2026

- <Badge variant="warning">Breaking</Badge> 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](/usage-and-quotas#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](/webhook#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](/api/finder#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](/usage-and-quotas#credit-costs).

## January 2026

- <Badge variant="warning">Breaking</Badge> 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](/usage-and-quotas#check-usage).

## December 2025

- December 29: Similar domains is paginated: it accepts `page` and `limit` and returns a `meta` object. See [Similar](/api/domain#similar).

## September 2025

- September 3: `POST /v1/reveal/search` accepts an API key and secret. See [Search companies](/api/reveal#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](/api/finder#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](/versioning#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](/api/phone#phone-validator) and [Phone finder](/api/phone#phone-finder).
- May 21: `GET /v1/domain-suggestions` returns companies whose name or domain matches a query, with their domains. See [Get domain suggestions](/api/domain-suggestions#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](/api/enrichment#person-api), [Company API](/api/enrichment#company-api), and [Combined API](/api/enrichment#combined-api).