Endpoints

API & webhooks

API reference

The OmniLead REST API gives Agency workspaces programmatic access to search, reveals, leads, pipelines, sequences, suppressions, credits, exports and webhooks. Every contact field comes with its source. Authenticate with a bearer API key; send JSON; receive JSON. This page is generated from the OpenAPI 3.1.0 spec, so it always matches what the API does. The API is available on the Agency plan.

Base URL: https://omni.cloudgens.net/api/v1
Authentication: Authorization: Bearer ol_live_…
Version: OmniLead-Version: 2026-09-28
Rate limit: 120 requests per minute per key

New to the API? Start with Authentication, Errors and Webhooks.

Search

Search the four lenses and reveal contacts. These are the only calls that spend credits.

GET/searchSearch a lens
POST/revealsReveal a contact

Search a lens

GET/search1 credit per page

Runs a search in one lens and returns one page of 25 results. Each page costs 1 credit on a live key. Contact details are masked; call POST /reveals with a result's entity_id to see them. Filters use the same keys as the filter panel in the app, passed as filters[key]=value (repeat the key for several values).

Query parameters

lensstringrequired
Which lens to search.
One of leads, investors, researchers, grants.
qstring
Free-text query: names, topics, domains, programs.
Up to 200 characters.
filters[key]string map
Lens filters. Leads: industry, country, size, title. Investors: stage, sector, type, check_min, check_max, state. Researchers: region, country, institution, min_works, recency. Grants: agency, program, mechanism, deadline_before.
pageinteger
Page number, 1–40.
Default 1.Min 1, max 40.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

One page of results.

Show response attributes

objectstringrequired
Always search_results.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
querystringrequired
The query you sent.
pageintegerrequired
Page number returned.
Min 1.
per_pageintegerrequired
Results per page. Always 25.
has_morebooleanrequired
Whether another page exists.
credits_chargedintegerrequired
Credits charged for this page: 1 on a live key, 0 on a test key.
livemodebooleanrequired
false when called with a test key.
dataarray of SearchHitrequired
Results for this page. Contact details are masked until revealed.
Show child attributesHide child attributes
- entity_idstringrequired
  ID to pass to POST /reveals, prefixed ent_.
- lensstringrequired
  The lens the record came from.
  One of leads, investors, researchers, grants.
- namestringrequired
  Organization, grant program or person name.
- person_namestring | null
  Contact person, when the hit is an organization with a known contact.
- titlestring | null
  Role of the contact person.
- organizationstring | null
  Organization, fund, institution or agency.
- locationstring | null
  City, region and country.
- email_maskedstring | nullrequired
  Masked email, e.g. d•••••@harborpoint.example. null if no email is known yet.
- email_statusstring | null
  Verification result. null until the email is revealed and checked.
  One of valid, invalid, catch_all, risky, unknown.
- phone_maskedstring | null
  Masked phone number.
- revealedbooleanrequired
  Whether this workspace already revealed this entity. Revealing again is free.
- match_scoreinteger | null
  Investors lens: fit against your opportunity profile. null elsewhere.
  Min 0, max 100.
- detailsobjectrequired
  Lens-specific fields: stages, sectors and check size for investors; topics, works count and ORCID for researchers; agency, amount and deadline for grants.
- sourcesarray of Sourcerequired
  Where each shown value came from.
  Show child attributesHide child attributes
  fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
  valuestringrequired
  The value as found at the source.
  source_urlstring (uri)required
  Public URL where the value was found.
  providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
  fetched_atstring (date-time)required
  When the value was fetched from the source.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
402insufficient_credits The workspace doesn't have enough credits for a search page or reveal. Nothing was charged.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/search \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'lens=investors' \
  --data-urlencode 'q=fintech' \
  --data-urlencode 'filters[stage]=seed' \
  --data-urlencode 'filters[sector]=software'

const params = new URLSearchParams({ lens: "investors", q: "fintech", "filters[stage]": "seed", "filters[sector]": "software" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/search?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "lens": "investors",
        "q": "fintech",
        "filters[stage]": "seed",
        "filters[sector]": "software",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "search_results",
  "lens": "investors",
  "query": "fintech",
  "page": 1,
  "per_page": 25,
  "has_more": true,
  "credits_charged": 1,
  "livemode": true,
  "data": [
    {
      "entity_id": "ent_inv_3Jd8Kq",
      "lens": "investors",
      "name": "Harbor Point Ventures",
      "title": "Managing Partner",
      "person_name": "Daniel Okafor",
      "organization": "Harbor Point Ventures",
      "location": "Boston, MA, US",
      "email_masked": "d•••••@harborpoint.example",
      "email_status": "valid",
      "phone_masked": null,
      "revealed": false,
      "match_score": 82,
      "details": {
        "stages": [
          "seed",
          "series-a"
        ],
        "sectors": [
          "software",
          "fintech"
        ],
        "check_size_usd": {
          "min": 250000,
          "max": 1500000
        },
        "last_filing_at": "2026-08-21"
      },
      "sources": [
        {
          "field": "organization",
          "value": "Harbor Point Ventures",
          "source_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000000000&type=D",
          "provider": "sec_edgar",
          "fetched_at": "2026-09-02T06:00:12Z"
        }
      ]
    }
  ]
}

Reveal a contact

POST/reveals1 creditChanges data

Reveals the email and phone for a search result, verifies the email, and saves the result as a lead. Costs 1 credit. Revealing an entity this workspace already revealed is free. If no verifiable contact is found, the credit is refunded and status is no_contact_found.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

entity_idstringrequired
The entity_id from a search result.

Returns 200

Already revealed. Returned free of charge. 201: The revealed contact.

Show response attributes

idstringrequired
Unique ID, prefixed rev_.
objectstringrequired
Always reveal.
entity_idstringrequired
The entity you revealed.
lead_idstring | nullrequired
The lead created or updated in your CRM. null for test-key dry runs.
statusstringrequired
revealed: details returned. no_contact_found: nothing verifiable was found and the credit was refunded. dry_run: test key, nothing charged.
One of revealed, no_contact_found, dry_run.
emailstring | nullrequired
Revealed email.
email_statusstring | null
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Revealed phone number in E.164.
credits_chargedintegerrequired
Net credits charged: 1 for a first reveal, 0 for a repeat, a refund or a dry run.
Min 0, max 1.
already_revealedbooleanrequired
true when this workspace had already revealed the entity. Repeat reveals are free.
livemodebooleanrequired
false when called with a test key.
sourcesarray of Sourcerequired
Where each revealed value was found.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.
created_atstring (date-time)required
When the reveal happened.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
402insufficient_credits The workspace doesn't have enough credits for a search page or reveal. Nothing was charged.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/reveals \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_id": "ent_inv_3Jd8Kq"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/reveals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    entity_id: "ent_inv_3Jd8Kq",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/reveals",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "entity_id": "ent_inv_3Jd8Kq",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "rev_6Nq1xT8bWm",
  "object": "reveal",
  "entity_id": "ent_inv_3Jd8Kq",
  "lead_id": "lead_5Zr4kP7cNe",
  "status": "revealed",
  "email": "daniel@harborpoint.example",
  "email_status": "valid",
  "email_confidence": 94,
  "phone": null,
  "credits_charged": 0,
  "already_revealed": true,
  "livemode": true,
  "sources": [
    {
      "field": "email",
      "value": "daniel@harborpoint.example",
      "source_url": "https://harborpoint.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-28T09:41:07Z"
    }
  ],
  "created_at": "2026-09-28T09:41:08Z"
}

Leads

People and organizations in your CRM, each with provenance.

GET/leadsList leads
POST/leadsCreate a lead
GET/leads/{id}Retrieve a lead
PATCH/leads/{id}Update a lead
DELETE/leads/{id}Delete a lead

List leads

GET/leads

Lists leads in the workspace, newest first. Filter by lens, tag, pipeline stage or update time.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.
lensstring
Only leads from this lens.
One of leads, investors, researchers, grants.
tagstring
Only leads with this tag name.
stage_idstring
Only leads in this stage.
qstring
Match name, email or company.
updated_sincestring (date-time)
Only leads changed after this time.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of leads.

Show response attributes

objectstringrequired
Always list.
dataarray of Leadrequired
Leads on this page.
Show child attributesHide child attributes
- idstringrequiredread-only
  Unique ID, prefixed lead_.
- objectstringrequired
  Always lead.
- lensstringrequired
  The lens the record came from.
  One of leads, investors, researchers, grants.
- first_namestring | null
  First name.
- last_namestring | null
  Last name.
- full_namestringrequired
  Display name. For organizations (funds, grant programs) this is the organization name.
- titlestring | null
  Job title or role.
- emailstring | nullrequired
  Email address. null until revealed.
- email_statusstring | nullrequired
  Verification result. null until the email is revealed and checked.
  One of valid, invalid, catch_all, risky, unknown.
- email_confidenceinteger | null
  Verification confidence, 0–100.
  Min 0, max 100.
- phonestring | null
  Phone number in E.164 format.
- websitestring (uri) | null
  Website URL.
- company_idstring | null
  Linked company ID, prefixed co_.
- company_namestring | null
  Company or organization name.
- countrystring | null
  ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
- revealedbooleanrequired
  Whether contact details have been revealed in this workspace.
- lawful_basisstringrequired
  GDPR lawful basis recorded for this lead.
  One of legitimate_interest, consent, contract.
- owner_idstring | null
  Workspace member who owns the lead.
- tagsarray of stringsrequired
  Tag names.
- stageobject (StageRef) | nullrequired
  The lead's current pipeline stage, or null if the lead isn't in a pipeline.
  Show child attributesHide child attributes
  pipeline_idstringrequired
  Pipeline ID.
  stage_idstringrequired
  Stage ID.
  namestringrequired
  Stage name.
- custom_fieldsobject
  Custom field values keyed by field key.
- created_atstring (date-time)required
  When the lead was created.
- updated_atstring (date-time)required
  When the lead last changed.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/leads \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=northwind'

const params = new URLSearchParams({ limit: "25", q: "northwind" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/leads?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
        "q": "northwind",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "lead_7Hq2mR9xKd",
      "object": "lead",
      "lens": "leads",
      "first_name": "Maya",
      "last_name": "Lindqvist",
      "full_name": "Maya Lindqvist",
      "title": "Head of Operations",
      "email": "maya@northwind.example",
      "email_status": "valid",
      "email_confidence": 96,
      "phone": "+442071838750",
      "website": "https://northwind.example",
      "company_id": "co_4Tn8wQ2pLs",
      "company_name": "Northwind Logistics",
      "country": "GB",
      "revealed": true,
      "lawful_basis": "legitimate_interest",
      "owner_id": "usr_2Pk9sX1aVe",
      "tags": [
        "q4-outreach"
      ],
      "stage": {
        "pipeline_id": "pl_9Wc3nB6tYr",
        "stage_id": "st_Qualified01",
        "name": "Qualified"
      },
      "custom_fields": {
        "fleet_size": "120"
      },
      "created_at": "2026-09-12T08:15:40Z",
      "updated_at": "2026-09-20T14:02:11Z"
    }
  ],
  "has_more": true,
  "next_cursor": "lead_7Hq2mR9xKd"
}

Create a lead

POST/leadsChanges data

Adds a lead you found yourself. No credits are charged. The email is checked against your suppression list and the global opt-out list; suppressed addresses are saved but can't be enrolled. Send source_url so the lead has provenance.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

lensstring
The lens the record came from.
One of leads, investors, researchers, grants.Default "leads".
first_namestring
First name.
Up to 120 characters.
last_namestring
Last name.
Up to 120 characters.
full_namestring
Required when first and last name are empty, e.g. for an organization.
Up to 240 characters.
titlestring
Job title.
Up to 200 characters.
emailstring (email)
Email address. Checked against your suppression list.
phonestring
Phone number. Normalized to E.164.
websitestring (uri)
Website URL.
company_namestring
Company name. Matched to an existing company by domain, or created.
company_domainstring
Company domain, e.g. northwind.example.
countrystring
ISO 3166-1 alpha-2 country code.
Up to 2 characters.
lawful_basisstring
GDPR lawful basis.
One of legitimate_interest, consent, contract.Default "legitimate_interest".
source_urlstring (uri)
Where you found this person. Stored as provenance with provider api.
tagsarray of strings
Tag names. Missing tags are created.
Up to 20 items.
custom_fieldsobject
Values keyed by custom field key.

Returns 201

The created lead.

Show response attributes

idstringrequiredread-only
Unique ID, prefixed lead_.
objectstringrequired
Always lead.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
first_namestring | null
First name.
last_namestring | null
Last name.
full_namestringrequired
Display name. For organizations (funds, grant programs) this is the organization name.
titlestring | null
Job title or role.
emailstring | nullrequired
Email address. null until revealed.
email_statusstring | nullrequired
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Phone number in E.164 format.
websitestring (uri) | null
Website URL.
company_idstring | null
Linked company ID, prefixed co_.
company_namestring | null
Company or organization name.
countrystring | null
ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
revealedbooleanrequired
Whether contact details have been revealed in this workspace.
lawful_basisstringrequired
GDPR lawful basis recorded for this lead.
One of legitimate_interest, consent, contract.
owner_idstring | null
Workspace member who owns the lead.
tagsarray of stringsrequired
Tag names.
stageobject (StageRef) | nullrequired
The lead's current pipeline stage, or null if the lead isn't in a pipeline.
Show child attributesHide child attributes
- pipeline_idstringrequired
  Pipeline ID.
- stage_idstringrequired
  Stage ID.
- namestringrequired
  Stage name.
custom_fieldsobject
Custom field values keyed by field key.
created_atstring (date-time)required
When the lead was created.
updated_atstring (date-time)required
When the lead last changed.
sourcesarray of Sourcerequired
Provenance for every stored field.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/leads \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Maya",
  "last_name": "Lindqvist",
  "email": "maya@northwind.example",
  "title": "Head of Operations",
  "company_name": "Northwind Logistics",
  "company_domain": "northwind.example",
  "country": "GB",
  "source_url": "https://northwind.example/team",
  "tags": [
    "q4-outreach"
  ]
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "Maya",
    last_name: "Lindqvist",
    email: "maya@northwind.example",
    title: "Head of Operations",
    company_name: "Northwind Logistics",
    company_domain: "northwind.example",
    country: "GB",
    source_url: "https://northwind.example/team",
    tags: ["q4-outreach"],
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "first_name": "Maya",
        "last_name": "Lindqvist",
        "email": "maya@northwind.example",
        "title": "Head of Operations",
        "company_name": "Northwind Logistics",
        "company_domain": "northwind.example",
        "country": "GB",
        "source_url": "https://northwind.example/team",
        "tags": ["q4-outreach"],
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "id": "lead_7Hq2mR9xKd",
  "object": "lead",
  "lens": "leads",
  "first_name": "Maya",
  "last_name": "Lindqvist",
  "full_name": "Maya Lindqvist",
  "title": "Head of Operations",
  "email": "maya@northwind.example",
  "email_status": "valid",
  "email_confidence": 96,
  "phone": "+442071838750",
  "website": "https://northwind.example",
  "company_id": "co_4Tn8wQ2pLs",
  "company_name": "Northwind Logistics",
  "country": "GB",
  "revealed": true,
  "lawful_basis": "legitimate_interest",
  "owner_id": "usr_2Pk9sX1aVe",
  "tags": [
    "q4-outreach"
  ],
  "stage": {
    "pipeline_id": "pl_9Wc3nB6tYr",
    "stage_id": "st_Qualified01",
    "name": "Qualified"
  },
  "custom_fields": {
    "fleet_size": "120"
  },
  "created_at": "2026-09-12T08:15:40Z",
  "updated_at": "2026-09-20T14:02:11Z",
  "sources": [
    {
      "field": "email",
      "value": "maya@northwind.example",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    },
    {
      "field": "title",
      "value": "Head of Operations",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    }
  ]
}

Retrieve a lead

GET/leads/{id}

Returns one lead with sources[]: the source URL, provider and fetch date behind every stored field.

Path parameters

idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The lead.

Show response attributes

idstringrequiredread-only
Unique ID, prefixed lead_.
objectstringrequired
Always lead.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
first_namestring | null
First name.
last_namestring | null
Last name.
full_namestringrequired
Display name. For organizations (funds, grant programs) this is the organization name.
titlestring | null
Job title or role.
emailstring | nullrequired
Email address. null until revealed.
email_statusstring | nullrequired
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Phone number in E.164 format.
websitestring (uri) | null
Website URL.
company_idstring | null
Linked company ID, prefixed co_.
company_namestring | null
Company or organization name.
countrystring | null
ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
revealedbooleanrequired
Whether contact details have been revealed in this workspace.
lawful_basisstringrequired
GDPR lawful basis recorded for this lead.
One of legitimate_interest, consent, contract.
owner_idstring | null
Workspace member who owns the lead.
tagsarray of stringsrequired
Tag names.
stageobject (StageRef) | nullrequired
The lead's current pipeline stage, or null if the lead isn't in a pipeline.
Show child attributesHide child attributes
- pipeline_idstringrequired
  Pipeline ID.
- stage_idstringrequired
  Stage ID.
- namestringrequired
  Stage name.
custom_fieldsobject
Custom field values keyed by field key.
created_atstring (date-time)required
When the lead was created.
updated_atstring (date-time)required
When the lead last changed.
sourcesarray of Sourcerequired
Provenance for every stored field.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "lead_7Hq2mR9xKd",
  "object": "lead",
  "lens": "leads",
  "first_name": "Maya",
  "last_name": "Lindqvist",
  "full_name": "Maya Lindqvist",
  "title": "Head of Operations",
  "email": "maya@northwind.example",
  "email_status": "valid",
  "email_confidence": 96,
  "phone": "+442071838750",
  "website": "https://northwind.example",
  "company_id": "co_4Tn8wQ2pLs",
  "company_name": "Northwind Logistics",
  "country": "GB",
  "revealed": true,
  "lawful_basis": "legitimate_interest",
  "owner_id": "usr_2Pk9sX1aVe",
  "tags": [
    "q4-outreach"
  ],
  "stage": {
    "pipeline_id": "pl_9Wc3nB6tYr",
    "stage_id": "st_Qualified01",
    "name": "Qualified"
  },
  "custom_fields": {
    "fleet_size": "120"
  },
  "created_at": "2026-09-12T08:15:40Z",
  "updated_at": "2026-09-20T14:02:11Z",
  "sources": [
    {
      "field": "email",
      "value": "maya@northwind.example",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    },
    {
      "field": "title",
      "value": "Head of Operations",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    }
  ]
}

Update a lead

PATCH/leads/{id}Changes data

Changes the fields you send and leaves the rest. Emits lead.updated.

Path parameters

idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Request body

first_namestring
First name.
last_namestring
Last name.
titlestring
Job title.
phonestring | null
Phone number, or null to clear.
websitestring | null
Website URL, or null to clear.
countrystring | null
ISO country code, or null to clear.
lawful_basisstring
GDPR lawful basis.
One of legitimate_interest, consent, contract.
owner_idstring | null
Member ID to assign, or null to unassign.
custom_fieldsobject
Values to set. null clears a field.

Returns 200

The updated lead.

Show response attributes

idstringrequiredread-only
Unique ID, prefixed lead_.
objectstringrequired
Always lead.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
first_namestring | null
First name.
last_namestring | null
Last name.
full_namestringrequired
Display name. For organizations (funds, grant programs) this is the organization name.
titlestring | null
Job title or role.
emailstring | nullrequired
Email address. null until revealed.
email_statusstring | nullrequired
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Phone number in E.164 format.
websitestring (uri) | null
Website URL.
company_idstring | null
Linked company ID, prefixed co_.
company_namestring | null
Company or organization name.
countrystring | null
ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
revealedbooleanrequired
Whether contact details have been revealed in this workspace.
lawful_basisstringrequired
GDPR lawful basis recorded for this lead.
One of legitimate_interest, consent, contract.
owner_idstring | null
Workspace member who owns the lead.
tagsarray of stringsrequired
Tag names.
stageobject (StageRef) | nullrequired
The lead's current pipeline stage, or null if the lead isn't in a pipeline.
Show child attributesHide child attributes
- pipeline_idstringrequired
  Pipeline ID.
- stage_idstringrequired
  Stage ID.
- namestringrequired
  Stage name.
custom_fieldsobject
Custom field values keyed by field key.
created_atstring (date-time)required
When the lead was created.
updated_atstring (date-time)required
When the lead last changed.
sourcesarray of Sourcerequired
Provenance for every stored field.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X PATCH https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "COO",
  "custom_fields": {
    "fleet_size": "140"
  }
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "COO",
    custom_fields: {
      fleet_size: "140",
    },
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.patch(
    "https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    json={
        "title": "COO",
        "custom_fields": {
            "fleet_size": "140",
        },
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "lead_7Hq2mR9xKd",
  "object": "lead",
  "lens": "leads",
  "first_name": "Maya",
  "last_name": "Lindqvist",
  "full_name": "Maya Lindqvist",
  "title": "COO",
  "email": "maya@northwind.example",
  "email_status": "valid",
  "email_confidence": 96,
  "phone": "+442071838750",
  "website": "https://northwind.example",
  "company_id": "co_4Tn8wQ2pLs",
  "company_name": "Northwind Logistics",
  "country": "GB",
  "revealed": true,
  "lawful_basis": "legitimate_interest",
  "owner_id": "usr_2Pk9sX1aVe",
  "tags": [
    "q4-outreach"
  ],
  "stage": {
    "pipeline_id": "pl_9Wc3nB6tYr",
    "stage_id": "st_Qualified01",
    "name": "Qualified"
  },
  "custom_fields": {
    "fleet_size": "140"
  },
  "created_at": "2026-09-12T08:15:40Z",
  "updated_at": "2026-09-20T14:02:11Z",
  "sources": [
    {
      "field": "email",
      "value": "maya@northwind.example",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    },
    {
      "field": "title",
      "value": "Head of Operations",
      "source_url": "https://northwind.example/team",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:14:03Z"
    }
  ]
}

Delete a lead

DELETE/leads/{id}Changes data

Permanently deletes the lead, its notes, tasks and enrollments. Active sequences stop for this lead. To stop contacting someone but keep a record, add a suppression instead.

Path parameters

idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

Deleted.

Show response attributes

idstringrequired
ID of the deleted object.
objectstringrequired
Type of the deleted object.
deletedbooleanrequired
Always true.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.delete(
    "https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "lead_7Hq2mR9xKd",
  "object": "lead",
  "deleted": true
}

Companies

Companies linked to your leads.

GET/companiesList companies
GET/companies/{id}Retrieve a company

List companies

GET/companies

Lists companies linked to leads in your workspace.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.
qstring
Match name or domain.
countrystring
ISO country code.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of companies.

Show response attributes

objectstringrequired
Always list.
dataarray of Companyrequired
Companies on this page.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed co_.
- objectstringrequired
  Always company.
- namestringrequired
  Company name.
- domainstring | nullrequired
  Primary domain.
- industrystring | null
  Industry key.
- sizestring | null
  Employee range.
  One of 1-10, 11-50, 51-200, 201-500, 501-1000, 1001+.
- countrystring | null
  ISO country code.
- citystring | null
  City.
- descriptionstring | null
  Short description from the company's own site.
- lead_countintegerrequired
  Leads linked to this company in your workspace.
- sourcesarray of Sourcerequired
  Provenance for the company fields.
  Show child attributesHide child attributes
  fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
  valuestringrequired
  The value as found at the source.
  source_urlstring (uri)required
  Public URL where the value was found.
  providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
  fetched_atstring (date-time)required
  When the value was fetched from the source.
- created_atstring (date-time)required
  When the company was created.
- updated_atstring (date-time)required
  When the company last changed.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/companies \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=northwind'

const params = new URLSearchParams({ limit: "25", q: "northwind" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/companies?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/companies",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
        "q": "northwind",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "co_4Tn8wQ2pLs",
      "object": "company",
      "name": "Northwind Logistics",
      "domain": "northwind.example",
      "industry": "logistics",
      "size": "51-200",
      "country": "GB",
      "city": "London",
      "description": "Freight forwarding and warehousing for UK retailers.",
      "lead_count": 3,
      "sources": [
        {
          "field": "domain",
          "value": "northwind.example",
          "source_url": "https://northwind.example",
          "provider": "crawler",
          "fetched_at": "2026-09-12T08:13:51Z"
        }
      ],
      "created_at": "2026-09-12T08:13:51Z",
      "updated_at": "2026-09-12T08:15:40Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a company

GET/companies/{id}

Returns one company with provenance for its fields.

Path parameters

idstringrequired
Company ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The company.

Show response attributes

idstringrequired
Unique ID, prefixed co_.
objectstringrequired
Always company.
namestringrequired
Company name.
domainstring | nullrequired
Primary domain.
industrystring | null
Industry key.
sizestring | null
Employee range.
One of 1-10, 11-50, 51-200, 201-500, 501-1000, 1001+.
countrystring | null
ISO country code.
citystring | null
City.
descriptionstring | null
Short description from the company's own site.
lead_countintegerrequired
Leads linked to this company in your workspace.
sourcesarray of Sourcerequired
Provenance for the company fields.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.
created_atstring (date-time)required
When the company was created.
updated_atstring (date-time)required
When the company last changed.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/companies/co_4Tn8wQ2pLs", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/companies/co_4Tn8wQ2pLs",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "co_4Tn8wQ2pLs",
  "object": "company",
  "name": "Northwind Logistics",
  "domain": "northwind.example",
  "industry": "logistics",
  "size": "51-200",
  "country": "GB",
  "city": "London",
  "description": "Freight forwarding and warehousing for UK retailers.",
  "lead_count": 3,
  "sources": [
    {
      "field": "domain",
      "value": "northwind.example",
      "source_url": "https://northwind.example",
      "provider": "crawler",
      "fetched_at": "2026-09-12T08:13:51Z"
    }
  ],
  "created_at": "2026-09-12T08:13:51Z",
  "updated_at": "2026-09-12T08:15:40Z"
}

Pipelines

Pipelines, stages and moving leads between them.

GET/pipelinesList pipelines
PUT/leads/{id}/stageMove a lead to a stage

List pipelines

GET/pipelines

Lists every pipeline with its stages in order. Use the stage IDs with PUT /leads/{id}/stage.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

All pipelines.

Show response attributes

objectstringrequired
Always list.
dataarray of Pipelinerequired
Pipelines.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed pl_.
- objectstringrequired
  Always pipeline.
- namestringrequired
  Pipeline name.
- lensstring | null
  Lens the pipeline template was made for, if any.
  One of leads, investors, researchers, grants.
- is_defaultbooleanrequired
  Whether new leads land in this pipeline.
- stagesarray of Stagerequired
  Stages in order.
  Show child attributesHide child attributes
  idstringrequired
  Stage ID, prefixed st_.
  namestringrequired
  Stage name.
  positionintegerrequired
  Zero-based order in the pipeline.
  kindstringrequired
  won and lost stages close the deal.
  One of open, won, lost.
- created_atstring (date-time)required
  When the pipeline was created.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/pipelines", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/pipelines",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "pl_9Wc3nB6tYr",
      "object": "pipeline",
      "name": "Sales",
      "lens": "leads",
      "is_default": true,
      "stages": [
        {
          "id": "st_New000001",
          "name": "New",
          "position": 0,
          "kind": "open"
        },
        {
          "id": "st_Contacted1",
          "name": "Contacted",
          "position": 1,
          "kind": "open"
        },
        {
          "id": "st_Replied001",
          "name": "Replied",
          "position": 2,
          "kind": "open"
        },
        {
          "id": "st_Qualified01",
          "name": "Qualified",
          "position": 3,
          "kind": "open"
        },
        {
          "id": "st_Won0000001",
          "name": "Won",
          "position": 4,
          "kind": "won"
        },
        {
          "id": "st_Lost000001",
          "name": "Lost",
          "position": 5,
          "kind": "lost"
        }
      ],
      "created_at": "2026-08-30T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Move a lead to a stage

PUT/leads/{id}/stageChanges data

Puts the lead in the given pipeline stage, adding it to the pipeline if needed. Emits lead.stage_changed.

Path parameters

idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Request body

pipeline_idstringrequired
Pipeline ID.
stage_idstringrequired
Stage ID in that pipeline.

Returns 200

The new stage.

Show response attributes

objectstringrequired
Always lead_stage.
lead_idstringrequired
Lead ID.
pipeline_idstringrequired
Pipeline ID.
stage_idstringrequired
New stage ID.
previous_stage_idstring | nullrequired
Stage before the move, or null if the lead wasn't in this pipeline.
changed_atstring (date-time)required
When the move happened.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X PUT https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/stage \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Content-Type: application/json" \
  -d '{
  "pipeline_id": "pl_9Wc3nB6tYr",
  "stage_id": "st_Won0000001"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/stage", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pipeline_id: "pl_9Wc3nB6tYr",
    stage_id: "st_Won0000001",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.put(
    "https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/stage",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    json={
        "pipeline_id": "pl_9Wc3nB6tYr",
        "stage_id": "st_Won0000001",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "lead_stage",
  "lead_id": "lead_7Hq2mR9xKd",
  "pipeline_id": "pl_9Wc3nB6tYr",
  "stage_id": "st_Won0000001",
  "previous_stage_id": "st_Qualified01",
  "changed_at": "2026-09-28T10:40:00Z"
}

Notes & tasks

Timeline notes and follow-up tasks.

POST/leads/{id}/notesAdd a note
GET/tasksList tasks
POST/tasksCreate a task
PATCH/tasks/{id}Update a task

Add a note

POST/leads/{id}/notesChanges data

Adds a note to the lead's timeline.

Path parameters

idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

bodystringrequired
Note text. Plain text or Markdown.
Up to 10000 characters.

Returns 201

The note.

Show response attributes

idstringrequired
Unique ID, prefixed note_.
objectstringrequired
Always note.
lead_idstringrequired
Lead ID.
bodystringrequired
Note text.
author_idstring | nullrequired
Member who wrote it. null for notes created with an API key.
created_atstring (date-time)required
When the note was created.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/notes \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Asked for pricing for 3 seats. Follow up after their board meeting on Oct 6."
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/notes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    body: "Asked for pricing for 3 seats. Follow up after their board meeting on Oct 6.",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/leads/lead_7Hq2mR9xKd/notes",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "body": "Asked for pricing for 3 seats. Follow up after their board meeting on Oct 6.",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "id": "note_8Lp2dW5rTy",
  "object": "note",
  "lead_id": "lead_7Hq2mR9xKd",
  "body": "Asked for pricing for 3 seats. Follow up after their board meeting on Oct 6.",
  "author_id": null,
  "created_at": "2026-09-28T10:12:44Z"
}

List tasks

GET/tasks

Lists tasks, soonest due first.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.
statusstring
Filter by status.
One of open, done.
lead_idstring
Only tasks for this lead.
due_beforestring (date-time)
Only tasks due before this time.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of tasks.

Show response attributes

objectstringrequired
Always list.
dataarray of Taskrequired
Tasks.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed task_.
- objectstringrequired
  Always task.
- titlestringrequired
  What needs doing.
- lead_idstring | nullrequired
  Related lead, if any.
- assignee_idstring | nullrequired
  Member responsible.
- statusstringrequired
  Task status.
  One of open, done.
- due_atstring (date-time) | nullrequired
  Due date and time.
- completed_atstring (date-time) | nullrequired
  When the task was marked done.
- created_atstring (date-time)required
  When the task was created.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/tasks \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25'

const params = new URLSearchParams({ limit: "25" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/tasks?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "task_1Vb7nH3kZe",
      "object": "task",
      "title": "Send pricing to Maya",
      "lead_id": "lead_7Hq2mR9xKd",
      "assignee_id": "usr_2Pk9sX1aVe",
      "status": "open",
      "due_at": "2026-10-06T09:00:00Z",
      "completed_at": null,
      "created_at": "2026-09-28T10:13:02Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a task

POST/tasksChanges data

Creates a task, optionally linked to a lead. Tasks with a due date show on the assignee's home screen.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

titlestringrequired
What needs doing.
Up to 300 characters.
lead_idstring
Related lead.
assignee_idstring
Member to assign. Defaults to the workspace owner.
due_atstring (date-time)
Due date and time.

Returns 201

The task.

Show response attributes

idstringrequired
Unique ID, prefixed task_.
objectstringrequired
Always task.
titlestringrequired
What needs doing.
lead_idstring | nullrequired
Related lead, if any.
assignee_idstring | nullrequired
Member responsible.
statusstringrequired
Task status.
One of open, done.
due_atstring (date-time) | nullrequired
Due date and time.
completed_atstring (date-time) | nullrequired
When the task was marked done.
created_atstring (date-time)required
When the task was created.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/tasks \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Send pricing to Maya",
  "lead_id": "lead_7Hq2mR9xKd",
  "due_at": "2026-10-06T09:00:00Z"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Send pricing to Maya",
    lead_id: "lead_7Hq2mR9xKd",
    due_at: "2026-10-06T09:00:00Z",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Send pricing to Maya",
        "lead_id": "lead_7Hq2mR9xKd",
        "due_at": "2026-10-06T09:00:00Z",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "id": "task_1Vb7nH3kZe",
  "object": "task",
  "title": "Send pricing to Maya",
  "lead_id": "lead_7Hq2mR9xKd",
  "assignee_id": "usr_2Pk9sX1aVe",
  "status": "open",
  "due_at": "2026-10-06T09:00:00Z",
  "completed_at": null,
  "created_at": "2026-09-28T10:13:02Z"
}

Update a task

PATCH/tasks/{id}Changes data

Changes a task. Set status to done to complete it.

Path parameters

idstringrequired
Task ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Request body

titlestring
What needs doing.
statusstring
Set to done to complete the task.
One of open, done.
due_atstring (date-time) | null
Due date, or null to clear.
assignee_idstring | null
Member to assign, or null to unassign.

Returns 200

The task.

Show response attributes

idstringrequired
Unique ID, prefixed task_.
objectstringrequired
Always task.
titlestringrequired
What needs doing.
lead_idstring | nullrequired
Related lead, if any.
assignee_idstring | nullrequired
Member responsible.
statusstringrequired
Task status.
One of open, done.
due_atstring (date-time) | nullrequired
Due date and time.
completed_atstring (date-time) | nullrequired
When the task was marked done.
created_atstring (date-time)required
When the task was created.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X PATCH https://omni.cloudgens.net/api/v1/tasks/task_1Vb7nH3kZe \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "done"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/tasks/task_1Vb7nH3kZe", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    status: "done",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.patch(
    "https://omni.cloudgens.net/api/v1/tasks/task_1Vb7nH3kZe",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    json={
        "status": "done",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "task_1Vb7nH3kZe",
  "object": "task",
  "title": "Send pricing to Maya",
  "lead_id": "lead_7Hq2mR9xKd",
  "assignee_id": "usr_2Pk9sX1aVe",
  "status": "done",
  "due_at": "2026-10-06T09:00:00Z",
  "completed_at": "2026-10-06T08:12:00Z",
  "created_at": "2026-09-28T10:13:02Z"
}

Sequences

Read sequences and manage who is enrolled.

GET/sequencesList sequences
GET/sequences/{id}Retrieve a sequence
POST/sequences/{id}/enrollmentsEnroll leads
DELETE/sequences/{id}/enrollments/{lead_id}Remove a lead from a sequence

List sequences

GET/sequences

Lists sequences with their steps and stats. Sequences are created and launched in the app, where the pre-launch checklist runs.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.
statusstring
Filter by status.
One of draft, active, paused, completed.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of sequences.

Show response attributes

objectstringrequired
Always list.
dataarray of Sequencerequired
Sequences.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed seq_.
- objectstringrequired
  Always sequence.
- namestringrequired
  Sequence name.
- lensstring | null
  Lens template it was built from, if any.
  One of leads, investors, researchers, grants.
- statusstringrequired
  Sequence status. Only active sequences send.
  One of draft, active, paused, completed.
- mailbox_idsarray of stringsrequired
  Mailboxes it rotates through.
- business_days_onlybooleanrequired
  Whether waits count business days only.
- stepsarray of SequenceSteprequired
  Steps in order.
  Show child attributesHide child attributes
  positionintegerrequired
  1-based order.
  typestringrequired
  Step type.
  One of email, wait.
  subjectstring | nullrequired
  Subject line with merge tags, for email steps.
  wait_daysinteger | nullrequired
  Days to wait, for wait steps.
- statsobjectrequired
  Show child attributesHide child attributes
  enrolledintegerrequired
  Leads ever enrolled.
  activeintegerrequired
  Leads still in progress.
  sentintegerrequired
  Emails sent.
  repliedintegerrequired
  Leads who replied.
  bouncedintegerrequired
  Hard bounces.
  unsubscribedintegerrequired
  Unsubscribes.
- created_atstring (date-time)required
  When the sequence was created.
- launched_atstring (date-time) | nullrequired
  When it was first launched.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/sequences \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25'

const params = new URLSearchParams({ limit: "25" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/sequences?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/sequences",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "seq_5Kd9wP2xLm",
      "object": "sequence",
      "name": "Seed round — first touch",
      "lens": "investors",
      "status": "active",
      "mailbox_ids": [
        "mbx_8Tq3rN6yHs"
      ],
      "business_days_only": true,
      "steps": [
        {
          "position": 1,
          "type": "email",
          "subject": "{{company|Our}} seed round",
          "wait_days": null
        },
        {
          "position": 2,
          "type": "wait",
          "subject": null,
          "wait_days": 3
        },
        {
          "position": 3,
          "type": "email",
          "subject": "Re: {{company|Our}} seed round",
          "wait_days": null
        }
      ],
      "stats": {
        "enrolled": 64,
        "active": 38,
        "sent": 102,
        "replied": 9,
        "bounced": 1,
        "unsubscribed": 0
      },
      "created_at": "2026-09-10T15:20:00Z",
      "launched_at": "2026-09-11T08:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a sequence

GET/sequences/{id}

Returns one sequence with its steps and stats.

Path parameters

idstringrequired
Sequence ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The sequence.

Show response attributes

idstringrequired
Unique ID, prefixed seq_.
objectstringrequired
Always sequence.
namestringrequired
Sequence name.
lensstring | null
Lens template it was built from, if any.
One of leads, investors, researchers, grants.
statusstringrequired
Sequence status. Only active sequences send.
One of draft, active, paused, completed.
mailbox_idsarray of stringsrequired
Mailboxes it rotates through.
business_days_onlybooleanrequired
Whether waits count business days only.
stepsarray of SequenceSteprequired
Steps in order.
Show child attributesHide child attributes
- positionintegerrequired
  1-based order.
- typestringrequired
  Step type.
  One of email, wait.
- subjectstring | nullrequired
  Subject line with merge tags, for email steps.
- wait_daysinteger | nullrequired
  Days to wait, for wait steps.
statsobjectrequired
Show child attributesHide child attributes
- enrolledintegerrequired
  Leads ever enrolled.
- activeintegerrequired
  Leads still in progress.
- sentintegerrequired
  Emails sent.
- repliedintegerrequired
  Leads who replied.
- bouncedintegerrequired
  Hard bounces.
- unsubscribedintegerrequired
  Unsubscribes.
created_atstring (date-time)required
When the sequence was created.
launched_atstring (date-time) | nullrequired
When it was first launched.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "seq_5Kd9wP2xLm",
  "object": "sequence",
  "name": "Seed round — first touch",
  "lens": "investors",
  "status": "active",
  "mailbox_ids": [
    "mbx_8Tq3rN6yHs"
  ],
  "business_days_only": true,
  "steps": [
    {
      "position": 1,
      "type": "email",
      "subject": "{{company|Our}} seed round",
      "wait_days": null
    },
    {
      "position": 2,
      "type": "wait",
      "subject": null,
      "wait_days": 3
    },
    {
      "position": 3,
      "type": "email",
      "subject": "Re: {{company|Our}} seed round",
      "wait_days": null
    }
  ],
  "stats": {
    "enrolled": 64,
    "active": 38,
    "sent": 102,
    "replied": 9,
    "bounced": 1,
    "unsubscribed": 0
  },
  "created_at": "2026-09-10T15:20:00Z",
  "launched_at": "2026-09-11T08:00:00Z"
}

Enroll leads

POST/sequences/{id}/enrollmentsChanges data

Adds leads to a sequence. Each lead is checked the same way as in the app: suppressed addresses, invalid emails, leads already enrolled and recipients blocked by your country sending rules are skipped with a reason. On a test key nothing is enrolled; the response shows what would happen.

Path parameters

idstringrequired
Sequence ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

lead_idsarray of stringsrequired
Leads to enroll. Up to 500 per request.
At least 1 item, up to 500 items.

Returns 201

Enrolled and skipped leads.

Show response attributes

objectstringrequired
Always enrollment_result.
livemodebooleanrequired
false for a test-key dry run: nothing was enrolled.
enrolledarray of Enrollmentrequired
Leads enrolled by this request.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed enr_.
- objectstringrequired
  Always enrollment.
- sequence_idstringrequired
  Sequence ID.
- lead_idstringrequired
  Lead ID.
- statusstringrequired
  Enrollment status.
  One of active, paused, completed, stopped.
- current_stepintegerrequired
  Position of the next step to run.
- next_send_atstring (date-time) | nullrequired
  When the next email is scheduled.
- enrolled_atstring (date-time)required
  When the lead was enrolled.
- stopped_atstring (date-time) | nullrequired
  When it stopped.
- stop_reasonstring | nullrequired
  Why it stopped.
  One of replied, bounced, unsubscribed, removed, suppressed.
skippedarray of objectsrequired
Leads not enrolled, with the reason.
Show child attributesHide child attributes
- lead_idstringrequired
  Lead ID.
- reasonstringrequired
  Why it was skipped.
  One of already_enrolled, suppressed, no_email, email_invalid, country_blocked, not_found.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "lead_ids": [
    "lead_7Hq2mR9xKd",
    "lead_5Zr4kP7cNe"
  ]
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lead_ids: ["lead_7Hq2mR9xKd", "lead_5Zr4kP7cNe"],
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "lead_ids": ["lead_7Hq2mR9xKd", "lead_5Zr4kP7cNe"],
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "object": "enrollment_result",
  "livemode": true,
  "enrolled": [
    {
      "id": "enr_2Mx6qT9vBc",
      "object": "enrollment",
      "sequence_id": "seq_5Kd9wP2xLm",
      "lead_id": "lead_7Hq2mR9xKd",
      "status": "active",
      "current_step": 1,
      "next_send_at": "2026-09-29T08:30:00Z",
      "enrolled_at": "2026-09-28T10:20:00Z",
      "stopped_at": null,
      "stop_reason": null
    }
  ],
  "skipped": [
    {
      "lead_id": "lead_5Zr4kP7cNe",
      "reason": "suppressed"
    }
  ]
}

Remove a lead from a sequence

DELETE/sequences/{id}/enrollments/{lead_id}Changes data

Stops the sequence for one lead. No further steps are sent. The lead stays in your CRM.

Path parameters

idstringrequired
Sequence ID.
lead_idstringrequired
Lead ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The stopped enrollment.

Show response attributes

idstringrequired
Unique ID, prefixed enr_.
objectstringrequired
Always enrollment.
sequence_idstringrequired
Sequence ID.
lead_idstringrequired
Lead ID.
statusstringrequired
Enrollment status.
One of active, paused, completed, stopped.
current_stepintegerrequired
Position of the next step to run.
next_send_atstring (date-time) | nullrequired
When the next email is scheduled.
enrolled_atstring (date-time)required
When the lead was enrolled.
stopped_atstring (date-time) | nullrequired
When it stopped.
stop_reasonstring | nullrequired
Why it stopped.
One of replied, bounced, unsubscribed, removed, suppressed.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X DELETE https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments/lead_7Hq2mR9xKd \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28"

const res = await fetch("https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments/lead_7Hq2mR9xKd", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.delete(
    "https://omni.cloudgens.net/api/v1/sequences/seq_5Kd9wP2xLm/enrollments/lead_7Hq2mR9xKd",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "enr_2Mx6qT9vBc",
  "object": "enrollment",
  "sequence_id": "seq_5Kd9wP2xLm",
  "lead_id": "lead_7Hq2mR9xKd",
  "status": "stopped",
  "current_step": 1,
  "next_send_at": null,
  "enrolled_at": "2026-09-28T10:20:00Z",
  "stopped_at": "2026-09-28T10:45:00Z",
  "stop_reason": "removed"
}

Suppressions

Addresses and domains that are never emailed.

GET/suppressionsList suppressions
POST/suppressionsSuppress an email or domain

List suppressions

GET/suppressions

Lists addresses and domains that will never be emailed from this workspace, including global opt-outs.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.
typestring
Filter by type.
One of email, domain.
qstring
Match the address or domain.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of suppressions.

Show response attributes

objectstringrequired
Always list.
dataarray of Suppressionrequired
Suppressions.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed sup_.
- objectstringrequired
  Always suppression.
- typestringrequired
  What is suppressed.
  One of email, domain.
- valuestringrequired
  The email address or domain.
- reasonstringrequired
  Why it was added.
  One of unsubscribe, bounce, complaint, opt_out, manual.
- scopestringrequired
  workspace entries are yours. global entries come from the public opt-out portal and apply to every workspace.
  One of workspace, global.
- created_atstring (date-time)required
  When it was added.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/suppressions \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=acme.example'

const params = new URLSearchParams({ limit: "25", q: "acme.example" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/suppressions?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/suppressions",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
        "q": "acme.example",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "sup_4Rk8mZ1nWd",
      "object": "suppression",
      "type": "email",
      "value": "no-contact@acme.example",
      "reason": "manual",
      "scope": "workspace",
      "created_at": "2026-09-28T10:25:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Suppress an email or domain

POST/suppressionsChanges data

Adds an email or domain to the workspace suppression list. Takes effect immediately: queued emails to it are cancelled and active enrollments stop. Emits unsubscribe.created when reason is unsubscribe.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

emailstring (email)
Email address to suppress. Send exactly one of email or domain.
domainstring
Domain to suppress, e.g. acme.example. Blocks every address at that domain.
reasonstring
Why you're adding it.
One of unsubscribe, complaint, manual.Default "manual".

Returns 201

The suppression.

Show response attributes

idstringrequired
Unique ID, prefixed sup_.
objectstringrequired
Always suppression.
typestringrequired
What is suppressed.
One of email, domain.
valuestringrequired
The email address or domain.
reasonstringrequired
Why it was added.
One of unsubscribe, bounce, complaint, opt_out, manual.
scopestringrequired
workspace entries are yours. global entries come from the public opt-out portal and apply to every workspace.
One of workspace, global.
created_atstring (date-time)required
When it was added.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/suppressions \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "no-contact@acme.example",
  "reason": "manual"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/suppressions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "no-contact@acme.example",
    reason: "manual",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/suppressions",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "email": "no-contact@acme.example",
        "reason": "manual",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "id": "sup_4Rk8mZ1nWd",
  "object": "suppression",
  "type": "email",
  "value": "no-contact@acme.example",
  "reason": "manual",
  "scope": "workspace",
  "created_at": "2026-09-28T10:25:00Z"
}

Credits

Balances and the credit ledger.

GET/creditsRetrieve credit balance

Retrieve credit balance

GET/credits

Returns plan and pack balances and the 20 most recent ledger entries. Plan credits are used before pack credits.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The balance.

Show response attributes

objectstringrequired
Always credit_balance.
planstringrequired
Current plan.
One of free, starter, growth, agency.
balanceobjectrequired
Show child attributesHide child attributes
- planintegerrequired
  Plan credits left this period. Used first; reset at renewal.
- packintegerrequired
  Credit-pack credits. Never expire; used after plan credits.
- totalintegerrequired
  plan + pack.
period_ends_atstring (date-time) | nullrequired
When plan credits renew.
ledgerarray of LedgerEntryrequired
The 20 most recent ledger entries, newest first.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed cl_.
- typestringrequired
  Ledger entry type.
  One of grant, purchase, consume, refund, expire.
- amountintegerrequired
  Signed amount. Negative for consumption and expiry.
- reasonstringrequired
  What caused it, e.g. search_page, reveal, reveal_failed, plan_renewal, pack_2000.
- refstring | nullrequired
  Related object ID, e.g. a reveal or Stripe invoice.
- poolstringrequired
  Which balance it affected.
  One of plan, pack.
- created_atstring (date-time)required
  When it was recorded.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/credits", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/credits",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "credit_balance",
  "plan": "agency",
  "balance": {
    "plan": 18240,
    "pack": 2000,
    "total": 20240
  },
  "period_ends_at": "2026-10-14T00:00:00Z",
  "ledger": [
    {
      "id": "cl_9Hn2kV5rXe",
      "type": "consume",
      "amount": -1,
      "reason": "reveal",
      "ref": "rev_6Nq1xT8bWm",
      "pool": "plan",
      "created_at": "2026-09-28T09:41:08Z"
    },
    {
      "id": "cl_7Bq4mS1tYa",
      "type": "refund",
      "amount": 1,
      "reason": "reveal_failed",
      "ref": "rev_3Cw8pL2nQz",
      "pool": "plan",
      "created_at": "2026-09-28T09:38:51Z"
    },
    {
      "id": "cl_5Dx1nR8wKp",
      "type": "purchase",
      "amount": 2000,
      "reason": "pack_2000",
      "ref": "cs_test_a1b2c3",
      "pool": "pack",
      "created_at": "2026-09-20T12:00:00Z"
    },
    {
      "id": "cl_3Ft6vH9mLs",
      "type": "grant",
      "amount": 20000,
      "reason": "plan_renewal",
      "ref": "in_1Q2w3E4r",
      "pool": "plan",
      "created_at": "2026-09-14T00:00:05Z"
    }
  ]
}

Webhooks

Endpoints that receive signed event notifications.

GET/webhook_endpointsList webhook endpoints
POST/webhook_endpointsCreate a webhook endpoint
DELETE/webhook_endpoints/{id}Delete a webhook endpoint

List webhook endpoints

GET/webhook_endpoints

Lists endpoints that receive events. Secrets are never returned here.

Query parameters

limitinteger
Objects per page, 1–100.
Default 25.Min 1, max 100.
starting_afterstring
Cursor from the previous page's next_cursor.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

A page of endpoints.

Show response attributes

objectstringrequired
Always list.
dataarray of WebhookEndpointrequired
Endpoints.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed we_.
- objectstringrequired
  Always webhook_endpoint.
- urlstring (uri)required
  HTTPS URL that receives events.
- descriptionstring | nullrequired
  Your label.
- eventsarray of stringsrequired
  Subscribed event types. * means all.
- statusstringrequired
  disabled endpoints receive nothing.
  One of enabled, disabled.
- created_atstring (date-time)required
  When it was created.
has_morebooleanrequired
Whether another page exists after this one.
next_cursorstring | nullrequired
Pass as starting_after to fetch the next page. null on the last page.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -G https://omni.cloudgens.net/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  --data-urlencode 'limit=25'

const params = new URLSearchParams({ limit: "25" });
const res = await fetch(`https://omni.cloudgens.net/api/v1/webhook_endpoints?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/webhook_endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    params={
        "limit": "25",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "we_6Gp3tX8kNr",
      "object": "webhook_endpoint",
      "url": "https://hooks.example.com/omnilead",
      "description": "CRM sync",
      "events": [
        "lead.created",
        "lead.stage_changed",
        "email.replied"
      ],
      "status": "enabled",
      "created_at": "2026-09-28T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a webhook endpoint

POST/webhook_endpointsChanges data

Registers an HTTPS URL for events. The response includes the signing secret once. Store it; you can't retrieve it again.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

urlstring (uri)required
HTTPS URL that receives events.
eventsarray of stringsrequired
Event types to send, or ["*"] for all.
At least 1 item.
descriptionstring
Your label.
Up to 200 characters.

Returns 201

The endpoint and its secret.

Show response attributes

idstringrequired
Unique ID, prefixed we_.
objectstringrequired
Always webhook_endpoint.
urlstring (uri)required
HTTPS URL that receives events.
descriptionstring | nullrequired
Your label.
eventsarray of stringsrequired
Subscribed event types. * means all.
statusstringrequired
disabled endpoints receive nothing.
One of enabled, disabled.
created_atstring (date-time)required
When it was created.
secretstringrequired
Signing secret, prefixed whsec_. Returned only once, at creation.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/omnilead",
  "events": [
    "lead.created",
    "lead.stage_changed",
    "email.replied"
  ],
  "description": "CRM sync"
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/omnilead",
    events: ["lead.created", "lead.stage_changed", "email.replied"],
    description: "CRM sync",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/webhook_endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "url": "https://hooks.example.com/omnilead",
        "events": ["lead.created", "lead.stage_changed", "email.replied"],
        "description": "CRM sync",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 201 Created

{
  "id": "we_6Gp3tX8kNr",
  "object": "webhook_endpoint",
  "url": "https://hooks.example.com/omnilead",
  "description": "CRM sync",
  "events": [
    "lead.created",
    "lead.stage_changed",
    "email.replied"
  ],
  "status": "enabled",
  "created_at": "2026-09-28T10:30:00Z",
  "secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}

Delete a webhook endpoint

DELETE/webhook_endpoints/{id}Changes data

Stops deliveries to the endpoint immediately. Deliveries already in retry are dropped.

Path parameters

idstringrequired
Endpoint ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

Deleted.

Show response attributes

idstringrequired
ID of the deleted object.
objectstringrequired
Type of the deleted object.
deletedbooleanrequired
Always true.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/webhook_endpoints/we_6Gp3tX8kNr", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.delete(
    "https://omni.cloudgens.net/api/v1/webhook_endpoints/we_6Gp3tX8kNr",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "we_6Gp3tX8kNr",
  "object": "webhook_endpoint",
  "deleted": true
}

Exports

Background CSV and JSON exports.

POST/exportsStart an export
GET/exports/{id}Retrieve an export

Start an export

POST/exportsChanges data

Starts a background export of leads as CSV or JSON. Poll GET /exports/{id} until status is completed, then download from download_url. Only revealed contact fields are exported. Exports are recorded in the audit log.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.
Idempotency-Keystring
A unique value (a UUID works) that makes a POST safe to retry. Replays within 24 hours return the original response.
Up to 255 characters.

Request body

formatstringrequired
File format.
One of csv, json.
filterobject (ExportFilter)
All fields optional. An empty filter exports every lead.
Show child attributesHide child attributes
- lensstring
  The lens the record came from.
  One of leads, investors, researchers, grants.
- tagstring
  Only leads with this tag.
- pipeline_idstring
  Only leads in this pipeline.
- stage_idstring
  Only leads in this stage.
- list_idstring
  Only leads in this list.
- updated_sincestring (date-time)
  Only leads changed after this time.

Returns 202

The export job was queued.

Show response attributes

idstringrequired
Unique ID, prefixed exp_.
objectstringrequired
Always export.
statusstringrequired
Job status.
One of queued, processing, completed, failed.
formatstringrequired
File format.
One of csv, json.
filterobject (ExportFilter)required
All fields optional. An empty filter exports every lead.
Show child attributesHide child attributes
- lensstring
  The lens the record came from.
  One of leads, investors, researchers, grants.
- tagstring
  Only leads with this tag.
- pipeline_idstring
  Only leads in this pipeline.
- stage_idstring
  Only leads in this stage.
- list_idstring
  Only leads in this list.
- updated_sincestring (date-time)
  Only leads changed after this time.
row_countinteger | nullrequired
Rows in the file, once completed.
download_urlstring (uri) | nullrequired
Signed download URL, once completed. Valid for 24 hours.
expires_atstring (date-time) | nullrequired
When download_url stops working.
created_atstring (date-time)required
When the job was created.
completed_atstring (date-time) | nullrequired
When the file was ready.

Errors

400invalid_request A parameter is missing, has the wrong type or fails validation. error.param names the field.
401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
409conflict The request conflicts with current state, for example a duplicate email or an Idempotency-Key reused with a different body.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

curl -X POST https://omni.cloudgens.net/api/v1/exports \
  -H "Authorization: Bearer $OMNILEAD_API_KEY" \
  -H "OmniLead-Version: 2026-09-28" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "format": "csv",
  "filter": {
    "lens": "investors",
    "tag": "seed-round"
  }
}'

const res = await fetch("https://omni.cloudgens.net/api/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    format: "csv",
    filter: {
      lens: "investors",
      tag: "seed-round",
    },
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os
import uuid

import requests

resp = requests.post(
    "https://omni.cloudgens.net/api/v1/exports",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "format": "csv",
        "filter": {
            "lens": "investors",
            "tag": "seed-round",
        },
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 202 Accepted

{
  "id": "exp_8Wn2cK5vHt",
  "object": "export",
  "status": "queued",
  "format": "csv",
  "filter": {
    "lens": "investors",
    "tag": "seed-round"
  },
  "row_count": null,
  "download_url": null,
  "expires_at": null,
  "created_at": "2026-09-28T10:32:00Z",
  "completed_at": null
}

Retrieve an export

GET/exports/{id}

Returns the export job. download_url is set once status is completed and works for 24 hours.

Path parameters

idstringrequired
Export ID.

Headers

OmniLead-Versionstring (date)
API version. Defaults to the version pinned on your key. Current: 2026-09-28.

Returns 200

The export.

Show response attributes

idstringrequired
Unique ID, prefixed exp_.
objectstringrequired
Always export.
statusstringrequired
Job status.
One of queued, processing, completed, failed.
formatstringrequired
File format.
One of csv, json.
filterobject (ExportFilter)required
All fields optional. An empty filter exports every lead.
Show child attributesHide child attributes
- lensstring
  The lens the record came from.
  One of leads, investors, researchers, grants.
- tagstring
  Only leads with this tag.
- pipeline_idstring
  Only leads in this pipeline.
- stage_idstring
  Only leads in this stage.
- list_idstring
  Only leads in this list.
- updated_sincestring (date-time)
  Only leads changed after this time.
row_countinteger | nullrequired
Rows in the file, once completed.
download_urlstring (uri) | nullrequired
Signed download URL, once completed. Valid for 24 hours.
expires_atstring (date-time) | nullrequired
When download_url stops working.
created_atstring (date-time)required
When the job was created.
completed_atstring (date-time) | nullrequired
When the file was ready.

Errors

401authentication_failed The Authorization header is missing, malformed, or the key was revoked.
403permission_denied The workspace's plan doesn't include the API, or the lens you asked for isn't on your plan.
404not_found No object with that ID exists in this workspace.
429rate_limited More than 120 requests in one minute with this key.
500internal_error Something failed on our side. The request may be retried safely with the same Idempotency-Key.

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

const res = await fetch("https://omni.cloudgens.net/api/v1/exports/exp_8Wn2cK5vHt", {
  headers: {
    Authorization: `Bearer ${process.env.OMNILEAD_API_KEY}`,
    "OmniLead-Version": "2026-09-28",
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import os

import requests

resp = requests.get(
    "https://omni.cloudgens.net/api/v1/exports/exp_8Wn2cK5vHt",
    headers={
        "Authorization": f"Bearer {os.environ['OMNILEAD_API_KEY']}",
        "OmniLead-Version": "2026-09-28",
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response · 200 OK

{
  "id": "exp_8Wn2cK5vHt",
  "object": "export",
  "status": "completed",
  "format": "csv",
  "filter": {
    "lens": "investors",
    "tag": "seed-round"
  },
  "row_count": 212,
  "download_url": "https://omni.cloudgens.net/api/v1/exports/exp_8Wn2cK5vHt/download?sig=3b1f0c",
  "expires_at": "2026-09-29T10:33:10Z",
  "created_at": "2026-09-28T10:32:00Z",
  "completed_at": "2026-09-28T10:33:10Z"
}

Webhook events

OmniLead sends these events as signed POST requests to your webhook endpoints. Each delivery is an event envelope; data.object holds the object below. See Receive webhooks for signature verification and retries.

`lead.created`

Sent when a lead is added by a reveal, an import, the app or the API.

data.object Lead

Show attributes

idstringrequiredread-only
Unique ID, prefixed lead_.
objectstringrequired
Always lead.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
first_namestring | null
First name.
last_namestring | null
Last name.
full_namestringrequired
Display name. For organizations (funds, grant programs) this is the organization name.
titlestring | null
Job title or role.
emailstring | nullrequired
Email address. null until revealed.
email_statusstring | nullrequired
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Phone number in E.164 format.
websitestring (uri) | null
Website URL.
company_idstring | null
Linked company ID, prefixed co_.
company_namestring | null
Company or organization name.
countrystring | null
ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
revealedbooleanrequired
Whether contact details have been revealed in this workspace.
lawful_basisstringrequired
GDPR lawful basis recorded for this lead.
One of legitimate_interest, consent, contract.
owner_idstring | null
Workspace member who owns the lead.
tagsarray of stringsrequired
Tag names.
stageobject (StageRef) | nullrequired
The lead's current pipeline stage, or null if the lead isn't in a pipeline.
Show child attributesHide child attributes
- pipeline_idstringrequired
  Pipeline ID.
- stage_idstringrequired
  Stage ID.
- namestringrequired
  Stage name.
custom_fieldsobject
Custom field values keyed by field key.
created_atstring (date-time)required
When the lead was created.
updated_atstring (date-time)required
When the lead last changed.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "lead.created",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "lead_7Hq2mR9xKd",
      "object": "lead",
      "lens": "leads",
      "first_name": "Maya",
      "last_name": "Lindqvist",
      "full_name": "Maya Lindqvist",
      "title": "Head of Operations",
      "email": "maya@northwind.example",
      "email_status": "valid",
      "email_confidence": 96,
      "phone": "+442071838750",
      "website": "https://northwind.example",
      "company_id": "co_4Tn8wQ2pLs",
      "company_name": "Northwind Logistics",
      "country": "GB",
      "revealed": true,
      "lawful_basis": "legitimate_interest",
      "owner_id": "usr_2Pk9sX1aVe",
      "tags": [
        "q4-outreach"
      ],
      "stage": {
        "pipeline_id": "pl_9Wc3nB6tYr",
        "stage_id": "st_Qualified01",
        "name": "Qualified"
      },
      "custom_fields": {
        "fleet_size": "120"
      },
      "created_at": "2026-09-12T08:15:40Z",
      "updated_at": "2026-09-20T14:02:11Z"
    }
  }
}

`lead.updated`

Sent when lead fields change. previous_attributes holds the old values of changed fields.

data.object Lead

Show attributes

idstringrequiredread-only
Unique ID, prefixed lead_.
objectstringrequired
Always lead.
lensstringrequired
The lens the record came from.
One of leads, investors, researchers, grants.
first_namestring | null
First name.
last_namestring | null
Last name.
full_namestringrequired
Display name. For organizations (funds, grant programs) this is the organization name.
titlestring | null
Job title or role.
emailstring | nullrequired
Email address. null until revealed.
email_statusstring | nullrequired
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Phone number in E.164 format.
websitestring (uri) | null
Website URL.
company_idstring | null
Linked company ID, prefixed co_.
company_namestring | null
Company or organization name.
countrystring | null
ISO 3166-1 alpha-2 country code. Drives per-country sending rules.
revealedbooleanrequired
Whether contact details have been revealed in this workspace.
lawful_basisstringrequired
GDPR lawful basis recorded for this lead.
One of legitimate_interest, consent, contract.
owner_idstring | null
Workspace member who owns the lead.
tagsarray of stringsrequired
Tag names.
stageobject (StageRef) | nullrequired
The lead's current pipeline stage, or null if the lead isn't in a pipeline.
Show child attributesHide child attributes
- pipeline_idstringrequired
  Pipeline ID.
- stage_idstringrequired
  Stage ID.
- namestringrequired
  Stage name.
custom_fieldsobject
Custom field values keyed by field key.
created_atstring (date-time)required
When the lead was created.
updated_atstring (date-time)required
When the lead last changed.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "lead.updated",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "lead_7Hq2mR9xKd",
      "object": "lead",
      "lens": "leads",
      "first_name": "Maya",
      "last_name": "Lindqvist",
      "full_name": "Maya Lindqvist",
      "title": "COO",
      "email": "maya@northwind.example",
      "email_status": "valid",
      "email_confidence": 96,
      "phone": "+442071838750",
      "website": "https://northwind.example",
      "company_id": "co_4Tn8wQ2pLs",
      "company_name": "Northwind Logistics",
      "country": "GB",
      "revealed": true,
      "lawful_basis": "legitimate_interest",
      "owner_id": "usr_2Pk9sX1aVe",
      "tags": [
        "q4-outreach"
      ],
      "stage": {
        "pipeline_id": "pl_9Wc3nB6tYr",
        "stage_id": "st_Qualified01",
        "name": "Qualified"
      },
      "custom_fields": {
        "fleet_size": "120"
      },
      "created_at": "2026-09-12T08:15:40Z",
      "updated_at": "2026-09-20T14:02:11Z"
    },
    "previous_attributes": {
      "title": "Head of Operations"
    }
  }
}

`lead.stage_changed`

Sent when a lead moves to another pipeline stage, from the kanban, a reply, or the API.

data.object LeadStage

Show attributes

objectstringrequired
Always lead_stage.
lead_idstringrequired
Lead ID.
pipeline_idstringrequired
Pipeline ID.
stage_idstringrequired
New stage ID.
previous_stage_idstring | nullrequired
Stage before the move, or null if the lead wasn't in this pipeline.
changed_atstring (date-time)required
When the move happened.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "lead.stage_changed",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "object": "lead_stage",
      "lead_id": "lead_7Hq2mR9xKd",
      "pipeline_id": "pl_9Wc3nB6tYr",
      "stage_id": "st_Replied001",
      "previous_stage_id": "st_Contacted1",
      "changed_at": "2026-09-30T11:02:00Z"
    }
  }
}

`reveal.completed`

Sent after every reveal, including refunded ones with status: no_contact_found.

data.object Reveal

Show attributes

idstringrequired
Unique ID, prefixed rev_.
objectstringrequired
Always reveal.
entity_idstringrequired
The entity you revealed.
lead_idstring | nullrequired
The lead created or updated in your CRM. null for test-key dry runs.
statusstringrequired
revealed: details returned. no_contact_found: nothing verifiable was found and the credit was refunded. dry_run: test key, nothing charged.
One of revealed, no_contact_found, dry_run.
emailstring | nullrequired
Revealed email.
email_statusstring | null
Verification result. null until the email is revealed and checked.
One of valid, invalid, catch_all, risky, unknown.
email_confidenceinteger | null
Verification confidence, 0–100.
Min 0, max 100.
phonestring | null
Revealed phone number in E.164.
credits_chargedintegerrequired
Net credits charged: 1 for a first reveal, 0 for a repeat, a refund or a dry run.
Min 0, max 1.
already_revealedbooleanrequired
true when this workspace had already revealed the entity. Repeat reveals are free.
livemodebooleanrequired
false when called with a test key.
sourcesarray of Sourcerequired
Where each revealed value was found.
Show child attributesHide child attributes
- fieldstringrequired
  Which field this source backs, e.g. email, title, organization.
- valuestringrequired
  The value as found at the source.
- source_urlstring (uri)required
  Public URL where the value was found.
- providerstringrequired
  Provider that fetched it.
  One of crawler, sec_edgar, openalex, orcid, crossref, nih_reporter, nsf_awards, grants_gov, google_places, serpapi, opencorporates, import, api, manual.
- fetched_atstring (date-time)required
  When the value was fetched from the source.
created_atstring (date-time)required
When the reveal happened.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "reveal.completed",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "rev_6Nq1xT8bWm",
      "object": "reveal",
      "entity_id": "ent_inv_3Jd8Kq",
      "lead_id": "lead_5Zr4kP7cNe",
      "status": "revealed",
      "email": "daniel@harborpoint.example",
      "email_status": "valid",
      "email_confidence": 94,
      "phone": null,
      "credits_charged": 1,
      "already_revealed": false,
      "livemode": true,
      "sources": [
        {
          "field": "email",
          "value": "daniel@harborpoint.example",
          "source_url": "https://harborpoint.example/team",
          "provider": "crawler",
          "fetched_at": "2026-09-28T09:41:07Z"
        }
      ],
      "created_at": "2026-09-28T09:41:08Z"
    }
  }
}

`email.sent`

Sent when a sequence step or inbox reply leaves a mailbox.

data.object EmailMessage

Show attributes

idstringrequired
Unique ID, prefixed msg_.
lead_idstringrequired
Lead ID.
sequence_idstring | nullrequired
Sequence that sent it, if any.
mailbox_idstringrequired
Mailbox used.
directionstringrequired
Direction.
One of outbound, inbound.
fromstringrequired
From address.
tostringrequired
To address.
subjectstringrequired
Subject.
snippetstringrequired
First 200 characters of the plain-text body.
sent_atstring (date-time)required
When it was sent or received.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "email.sent",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "msg_3Qw8eR2tYu",
      "lead_id": "lead_7Hq2mR9xKd",
      "sequence_id": "seq_5Kd9wP2xLm",
      "mailbox_id": "mbx_8Tq3rN6yHs",
      "direction": "outbound",
      "from": "sam@yourcompany.example",
      "to": "maya@northwind.example",
      "subject": "Northwind's Q4 shipping volume",
      "snippet": "Hi Maya, I noticed Northwind added a Leeds warehouse this month…",
      "sent_at": "2026-09-29T08:30:04Z"
    }
  }
}

`email.replied`

Sent when a reply is detected. The lead's sequence stops and it moves to Replied. Out-of-office replies don't trigger this event.

data.object EmailMessage

Show attributes

idstringrequired
Unique ID, prefixed msg_.
lead_idstringrequired
Lead ID.
sequence_idstring | nullrequired
Sequence that sent it, if any.
mailbox_idstringrequired
Mailbox used.
directionstringrequired
Direction.
One of outbound, inbound.
fromstringrequired
From address.
tostringrequired
To address.
subjectstringrequired
Subject.
snippetstringrequired
First 200 characters of the plain-text body.
sent_atstring (date-time)required
When it was sent or received.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "email.replied",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "msg_7Yu2iO5pAs",
      "lead_id": "lead_7Hq2mR9xKd",
      "sequence_id": "seq_5Kd9wP2xLm",
      "mailbox_id": "mbx_8Tq3rN6yHs",
      "direction": "inbound",
      "from": "maya@northwind.example",
      "to": "sam@yourcompany.example",
      "subject": "Re: Northwind's Q4 shipping volume",
      "snippet": "Thanks Sam, happy to talk next week. Tuesday works.",
      "sent_at": "2026-09-30T11:01:48Z"
    }
  }
}

`email.bounced`

Sent on a hard bounce. The address is marked invalid and suppressed. Five percent bounces pauses the sequence.

data.object EmailMessage

Show attributes

idstringrequired
Unique ID, prefixed msg_.
lead_idstringrequired
Lead ID.
sequence_idstring | nullrequired
Sequence that sent it, if any.
mailbox_idstringrequired
Mailbox used.
directionstringrequired
Direction.
One of outbound, inbound.
fromstringrequired
From address.
tostringrequired
To address.
subjectstringrequired
Subject.
snippetstringrequired
First 200 characters of the plain-text body.
sent_atstring (date-time)required
When it was sent or received.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "email.bounced",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "msg_1Df4gH7jKl",
      "lead_id": "lead_7Hq2mR9xKd",
      "sequence_id": "seq_5Kd9wP2xLm",
      "mailbox_id": "mbx_8Tq3rN6yHs",
      "direction": "outbound",
      "from": "sam@yourcompany.example",
      "to": "maya@northwind.example",
      "subject": "Northwind's Q4 shipping volume",
      "snippet": "550 5.1.1 The email account that you tried to reach does not exist.",
      "sent_at": "2026-09-29T08:30:04Z"
    }
  }
}

`sequence.completed`

Sent when a lead reaches the end of a sequence without replying.

data.object Enrollment

Show attributes

idstringrequired
Unique ID, prefixed enr_.
objectstringrequired
Always enrollment.
sequence_idstringrequired
Sequence ID.
lead_idstringrequired
Lead ID.
statusstringrequired
Enrollment status.
One of active, paused, completed, stopped.
current_stepintegerrequired
Position of the next step to run.
next_send_atstring (date-time) | nullrequired
When the next email is scheduled.
enrolled_atstring (date-time)required
When the lead was enrolled.
stopped_atstring (date-time) | nullrequired
When it stopped.
stop_reasonstring | nullrequired
Why it stopped.
One of replied, bounced, unsubscribed, removed, suppressed.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "sequence.completed",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "enr_2Mx6qT9vBc",
      "object": "enrollment",
      "sequence_id": "seq_5Kd9wP2xLm",
      "lead_id": "lead_7Hq2mR9xKd",
      "status": "completed",
      "current_step": 3,
      "next_send_at": null,
      "enrolled_at": "2026-09-28T10:20:00Z",
      "stopped_at": "2026-10-09T08:30:00Z",
      "stop_reason": null
    }
  }
}

`unsubscribe.created`

Sent when a recipient unsubscribes by one-click header, footer link or reply, or opts out through the public portal.

data.object Suppression

Show attributes

idstringrequired
Unique ID, prefixed sup_.
objectstringrequired
Always suppression.
typestringrequired
What is suppressed.
One of email, domain.
valuestringrequired
The email address or domain.
reasonstringrequired
Why it was added.
One of unsubscribe, bounce, complaint, opt_out, manual.
scopestringrequired
workspace entries are yours. global entries come from the public opt-out portal and apply to every workspace.
One of workspace, global.
created_atstring (date-time)required
When it was added.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "unsubscribe.created",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "id": "sup_4Rk8mZ1nWd",
      "object": "suppression",
      "type": "email",
      "value": "maya@northwind.example",
      "reason": "unsubscribe",
      "scope": "workspace",
      "created_at": "2026-09-28T10:25:00Z"
    }
  }
}

`credits.low`

Sent once per period when the total balance drops below 10% of the plan's monthly credits.

data.object CreditBalance

Show attributes

objectstringrequired
Always credit_balance.
planstringrequired
Current plan.
One of free, starter, growth, agency.
balanceobjectrequired
Show child attributesHide child attributes
- planintegerrequired
  Plan credits left this period. Used first; reset at renewal.
- packintegerrequired
  Credit-pack credits. Never expire; used after plan credits.
- totalintegerrequired
  plan + pack.
period_ends_atstring (date-time) | nullrequired
When plan credits renew.
ledgerarray of LedgerEntryrequired
The 20 most recent ledger entries, newest first.
Show child attributesHide child attributes
- idstringrequired
  Unique ID, prefixed cl_.
- typestringrequired
  Ledger entry type.
  One of grant, purchase, consume, refund, expire.
- amountintegerrequired
  Signed amount. Negative for consumption and expiry.
- reasonstringrequired
  What caused it, e.g. search_page, reveal, reveal_failed, plan_renewal, pack_2000.
- refstring | nullrequired
  Related object ID, e.g. a reveal or Stripe invoice.
- poolstringrequired
  Which balance it affected.
  One of plan, pack.
- created_atstring (date-time)required
  When it was recorded.

POST your endpoint · OmniLead-Signature signed

{
  "id": "evt_1Sx9fK3mQz",
  "object": "event",
  "type": "credits.low",
  "api_version": "2026-09-28",
  "created": "2026-09-30T11:02:01Z",
  "workspace_id": "ws_1Aa2Bb3Cc4",
  "livemode": true,
  "data": {
    "object": {
      "object": "credit_balance",
      "plan": "agency",
      "balance": {
        "plan": 1700,
        "pack": 0,
        "total": 1700
      },
      "period_ends_at": "2026-10-14T00:00:00Z",
      "ledger": []
    }
  }
}

Search

Search a lens

Query parameters

Headers

Returns 200

Errors

Reveal a contact

Headers

Request body

Returns 200

Errors

Leads

List leads

Query parameters

Headers

Returns 200

Errors

Create a lead

Headers

Request body

Returns 201

Errors

Retrieve a lead

Path parameters

Headers

Returns 200

Errors

Update a lead

Path parameters

Headers

Request body

Returns 200

Errors

Delete a lead

Path parameters

Headers

Returns 200

Errors

Companies

List companies

Query parameters

Headers

Returns 200

Errors

Retrieve a company

Path parameters

Headers

Returns 200

Errors

Pipelines

List pipelines

Headers

Returns 200

Errors

Move a lead to a stage

Path parameters

Headers

Request body

Returns 200

Errors

Tags

List tags

Query parameters

Headers

Returns 200

Errors

Tag a lead

Path parameters

Headers

Request body

Returns 200

Errors

Notes & tasks

Add a note

Path parameters

Headers

Request body

Returns 201

Errors

List tasks