> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airlead.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead ingest

> Push persons and interests into channel or list sources via JSON webhooks.

# 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](/guides/lead-capture/webhook-setup). This page covers the technical contract for integrators.

## Endpoints

### Channel source

```http theme={null}
POST /api/webhooks/channels/{channelId}/sources/{sourceId}/leads
```

### Lead table (list) source

```http theme={null}
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

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

Validate a mapping with synthetic data before sending production leads.

## Minimal native example

```json theme={null}
{
  "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"
  }
}
```

<Note>
  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.
</Note>

## 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

```json theme={null}
{
  "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](/api-reference/ingest/payload-schema).

For the complete product-to-API path, see [End-to-end ingest example](/developers/end-to-end-ingest).