# API versioning

This page explains how the Tomba API is versioned, which changes you should expect within a version, and where changes are announced.

## Current version

The current and only version of the API is v1. The major version is part of every endpoint path:

```text
https://api.tomba.io/v1/email-finder
```

## Backward-compatible changes

These changes ship within v1, without a new version:

- New endpoints.
- New optional parameters on existing endpoints.
- New fields in response objects, including in `meta` and in nested objects.
- New response headers.
- New values in enumerated fields, including new `errors.type` values.

Write your client so that these changes don't break it:

- Ignore response fields and headers your client doesn't recognize. Don't use strict schema validation that rejects unknown fields.
- Don't fail on an unrecognized enum value. Treat it like the closest value you handle, or log it.
- When `errors.type` has a value you don't handle, fall back to the HTTP status code. [Errors](/error-handling#status-codes) lists what each status means and whether to retry.

## Breaking changes

A breaking change is one that can make a working integration fail or misread a response:

- Removing or renaming an endpoint, parameter, response field, or header.
- Changing a field's type, format, or meaning.
- Making an optional parameter required, or rejecting a value that was accepted before.
- Changing the status code or `errors.type` returned for an existing condition.
- Changing the default page size or the shape of a paginated response.

Breaking changes have shipped within v1. The [API changelog](/changelog) lists each one with its date, marked Breaking, and says what to change in your client.

## Legacy paths

These older paths still work. Each one runs the same handler as its current path, with the same parameters, credit costs, and rate limit counters. The [API reference](/api) documents only the current paths; use them in new code.

| Legacy path                      | Current path                                                    |
| -------------------------------- | --------------------------------------------------------------- |
| `GET /v1/email-verifier/{email}` | [`GET /v1/email-verifier?email=`](/api/verifier#email-verifier) |
| `GET /v1/phone/{email}`          | [`GET /v1/phone-finder?email=`](/api/phone#phone-finder)        |
| `GET /v1/phone`                  | [`GET /v1/phone-finder`](/api/phone#phone-finder)               |

## Tracking changes

- [API changelog](/changelog): dated changes to endpoints, parameters, headers, and status codes.
- [SDKs](/libraries): each SDK's GitHub repository publishes its own releases.
- [Data updates](/data/updates): refreshes of Tomba's email and company data.