Lead ingest

Use a source webhook to create a person and one or more product interests in a channel or Company list. If you are configuring this in the product UI, start with the seller guide Connect source via webhook. This page covers the technical contract for integrators.

Endpoints

Channel source

POST /api/webhooks/channels/{channelId}/sources/{sourceId}/leads

Lead table (list) source

POST /api/webhooks/lead-tables/{tableId}/sources/{sourceId}/leads

Use only the webhook URL displayed for the configured source. Do not construct URLs from internal application routes.

Auth

Provide the configured source secret through X-Airlead-Webhook-Secret or a Bearer token. A source without a configured secret does not require this credential, but production sources should always use one.

Mapping vs native schema

If the source has a published mapping, send the agreed partner payload. Airlead transforms it into person, consent, capture, and interest fields.
Otherwise, send the native ingest schema.

Validate a mapping with synthetic data before sending production leads.

Minimal native example

{
  "externalId": "crm-lead-1001",
  "firstName": "Alex",
  "lastName": "Example",
  "email": "alex@example.com",
  "phone": "+491701234567",
  "postalCode": "10115",
  "city": "Berlin",
  "country": "DE",
  "consentStatus": "granted",
  "productSlug": "heat-pump",
  "routingReady": true,
  "triggerAutoDelivery": false,
  "fieldValues": {
    "current_heating": "oil"
  }
}

Start with triggerAutoDelivery: false while validating a source. When set to true, Airlead may request automated delivery evaluation, but delivery still depends on Airlead AI and the effective channel, buyer, eligibility, plan, and capacity settings.

Idempotency and duplicates

Send a stable externalId for every lead from your source system.

Repeating the same external ID on the same source returns the existing lead as idempotent_replay.
Source duplicate rules can independently match email or phone within the channel or workspace.
Depending on configuration, a duplicate is marked for review or rejected.

Treat idempotent_replay as a successful retry. Do not resend it with a new ID.

Batch

{
  "leads": [ { "...": "..." }, { "...": "..." } ]
}

Batch requests accept up to 100 leads. Each item can have its own acceptance, replay, duplicate, or validation result.

Response

Read the response body even for successful HTTP status codes. Important fields include:

status: accepted, duplicate, idempotent_replay, or rejected
leadId and requestIds
externalId
ingest.qualityStatus
ingest.duplicateStatus
ingest.duplicateMatch, when available
autoDelivery, when evaluation was requested

Retry behavior

Retry network errors, 429, and temporary 5xx responses with exponential backoff and jitter.
Reuse the original external ID.
Do not retry 400, 401, or 403 until the payload or configuration is corrected.
Record the request time, external ID, HTTP status, and response body without logging personal data or secrets.

Full schema: Ingest payload schema. For the complete product-to-API path, see End-to-end ingest example.

Start integrating

Send leads to Airlead

Receive leads from Airlead

Connect Airlead workspaces

Lead ingest

Lead ingest

Endpoints

Channel source

Lead table (list) source

Auth

Mapping vs native schema

Minimal native example

Idempotency and duplicates

Batch

Response

Retry behavior

​Lead ingest

​Endpoints

​Channel source

​Lead table (list) source

​Auth

​Mapping vs native schema

​Minimal native example

​Idempotency and duplicates

​Batch

​Response

​Retry behavior

Lead ingest

Endpoints

Channel source

Lead table (list) source

Auth

Mapping vs native schema

Minimal native example

Idempotency and duplicates

Batch

Response

Retry behavior