Lead Ingest API

Lead Ingest API

Send leads into Lead Distro AI using a simple POST request. Leads are validated against your campaign's field mapping, checked against inbound filters and suppression lists, then distributed to buyers automatically.

Endpoint

POST https://app.leaddistro.ai/api/v1/ingest

Authentication

Include your supplier's API key in the x-api-key header. You can find this in the supplier detail page.

x-api-key: your_supplier_api_key

Request Body

Send a JSON body with the required system fields and any custom fields defined in your campaign's field mapping.

Example Request

curl -X POST https://app.leaddistro.ai/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_supplier_api_key" \
  -d '{
    "flo_campaign_id": "campaign_abc123",
    "flo_supplier_id": "supplier_xyz789",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "5551234567",
    "email": "john@example.com",
    "state": "TX"
  }'

Response

On success the API returns the created lead with its assigned buyer and status.

{
  "data": {
    "id": "lead_id",
    "status": "ACCEPTED",
    "buyer_id": "buyer_abc",
    "campaign_id": "campaign_abc123"
  }
}

Ping-Post Mode

For ping-post campaigns, use the separate ping endpoint to check buyer availability before committing the lead.

POST https://app.leaddistro.ai/api/v1/ping

The ping endpoint returns available buyers and their bid prices without creating a lead. You then post the full lead to the ingest endpoint with the chosen buyer.

Buyer Postback Webhook (conversion and lead updates)

Buyers (destinations) push updates on a delivered lead by posting back to the postback webhook. A CRM uses it to mark a lead converted or not qualified, set the conversion revenue, record the deal value, or add a note. The outcome is optional, so you can post revenue on a lead you have sold before its outcome is set (send at least one updatable field).

POST https://app.leaddistro.ai/api/webhooks/buyer-outcome

There is no /api/v1/outcome endpoint; the URL above is the only postback endpoint. Authenticate with the buyer's webhook secret in the X-Buyer-Secret header (generated on the buyer's Postback Webhook page; this is NOT the supplier x-api-key). One buyer-level URL covers every campaign: the lead is matched from the body by lead_id (the UUID from the original delivery), by phone + campaign_id, by email + campaign_id, or by a custom campaign field such as a click ID (click_id + campaign_id, or match_field + match_value + campaign_id).

curl -X POST https://app.leaddistro.ai/api/webhooks/buyer-outcome \
  -H "Content-Type: application/json" \
  -H "X-Buyer-Secret: your_buyer_webhook_secret" \
  -d '{
    "lead_id": "<lead-uuid-from-the-original-delivery>",
    "outcome": "converted",
    "conversion_revenue": 200,
    "lead_value": 750,
    "note": "Signed retainer 2026-04-29",
    "idempotency_key": "crm-event-12345"
  }'