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

# Integration architecture

> Understand where source, buyer, lifecycle, and Connect integrations enter the Airlead data flow.

# Integration architecture

## Data flow

```mermaid theme={null}
sequenceDiagram
  participant Source as Source system
  participant Airlead
  participant Buyer as Buyer system

  Source->>Airlead: POST source ingest
  Airlead->>Airlead: Resolve external ID
  Airlead->>Airlead: Create person and interest
  Airlead->>Airlead: Validate and evaluate routing
  Airlead->>Buyer: POST lead.delivered
  Buyer->>Airlead: Confirmation, rejection, Storno, payout
```

## Source boundary

A source webhook is bound to a specific channel or list source. The source ID, external ID, mapping, and duplicate rules determine how incoming data is processed.

An HTTP success can mean the request was newly accepted or recognized as an idempotent replay. Read the response status instead of assuming every success created a new record.

## Buyer boundary

Airlead sends a `lead.delivered` event to the configured buyer webhook. The payload includes a `transactionId`, which the buyer must retain for later lifecycle callbacks.

Technical acceptance and commercial confirmation are separate:

1. Buyer webhook returns `2xx` to acknowledge receipt.
2. Buyer calls the lifecycle endpoint to report the commercial outcome.

## Connect boundary

Connect delivers between Airlead workspaces and is configured through a partnership, endpoint, terms, and field mapping. It is not a general API-key-based REST interface.

## Workspace isolation

All data belongs to a workspace. Webhook paths identify the target channel, source, or list and are protected by the secret configured for that resource.

Never reuse resource IDs or secrets from another workspace or environment.

## Auth layers

| Layer                 | Used for                                                       |
| --------------------- | -------------------------------------------------------------- |
| Source ingest secret  | Calls from a supplier system to an ingest webhook              |
| Buyer webhook secret  | Buyer lifecycle callbacks to Airlead                           |
| Connect secret        | Optional protection for resolving and using a Connect endpoint |
| Share or upload token | Access to a specific partner-facing link                       |
| User session          | Airlead web app only; not a partner API credential             |

Next: [Authentication](/developers/authentication) · [Lead ingest](/developers/lead-ingest) · [Outbound delivery](/developers/outbound-delivery)