Versioning and changelog

The OmniLead API uses dated versions. The current version is 2026-09-28. When we make a change that could break an integration, we release it as a new version, and your code keeps getting the old behavior until you choose to upgrade. You'll never wake up to a broken integration because of a change on our side.

Send the version header

Send the version you built against in the OmniLead-Version header on every request:

curl https://omni.cloudgens.net/api/v1/leads \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28"

If you leave the header out, the request uses the version pinned on your API key, which is the current version on the day you created the key. Sending the header explicitly is still best: it makes the version visible in your code and lets you test a new version one request at a time.

Webhook events are rendered with the version pinned on the endpoint when you created it. Each event's api_version field tells you which one.

What counts as a breaking change

These changes always come in a new version:

• Removing or renaming a field, parameter or endpoint.
• Changing a field's type or format.
• Adding a new required parameter.
• Changing the meaning of a value or a status code.
• Changing the structure of a webhook event.

These changes can arrive in the current version at any time, so build your client to tolerate them:

• New endpoints.
• New optional request parameters.
• New fields in responses and webhook events.
• New values in an enum, such as a new skipped reason or a new event type you can subscribe to.
• New error codes. Handle unknown codes by their HTTP status.
• Changes to the length or format of IDs and opaque strings like cursors. Treat IDs as strings up to 255 characters.
• Wording of human-readable message fields.

The /v1 in the URL

The /v1 path is the API's major version and changes only if the API is redesigned from the ground up, which we don't plan to do. Dated versions handle everything else.

Upgrade to a new version

When a new version is released:

1. 1

   Read what changed

   Check the version's entry below and in the changelog.

2. 2

   Test with the new header

   Send OmniLead-Version with the new date from a test environment, using a test key, and fix anything that changed.

3. 3

   Deploy

   Ship your code with the new version in the header.

4. 4

   Update your keys and webhooks

   Create new keys and webhook endpoints so their pinned version is the new one, then revoke and delete the old ones.

We support each version for at least 12 months after the next one is released, and we email the owners of workspaces that still use an old version before it's retired.

Version history

2026-09-28

The first public version of the API.

• Search every lens with GET /search and reveal contacts with POST /reveals, with 1 credit per search page and per first reveal, and automatic refunds.
• Leads with full provenance in sources[], companies, pipelines and stages, tags, notes and tasks.
• Read sequences and manage enrollments, with the same suppression and country checks as the app.
• Suppressions, credits with the recent ledger, and background CSV and JSON exports.
• Webhook endpoints and ten event types, signed with OmniLead-Signature.
• Cursor pagination, idempotency keys on every POST, rate limits of 120 requests a minute per key, and one error format.
• Test keys that never spend credits or send email.

The full specification is in the API reference, generated from our OpenAPI 3.1 document.