Copy page

Platform

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:

Code
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 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 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 documents only the current paths; use them in new code.

Tracking changes

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