Lead Ingest API

Actions API (manage your account)

Everything you can do by chat through the MCP, you can also do over plain HTTPS from a script, a workflow tool, or your own app: create and update campaigns, destinations, sources and funnels, look up leads and their routing trail, post back outcomes, pull reports, and manage Partner Portal access. Same action names, same inputs, same permissions.

Authentication

Use an organization API key (created in Settings, MCP & API) as a bearer token. A key holds per-area permissions, read or write, and starts read only. See Authentication.

Authorization: Bearer ldk_live_...

Endpoints

Example

curl -X POST https://www.leaddistro.ai/api/v1/actions/get_campaign \
  -H "Authorization: Bearer ldk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"campaign_id": "<campaign uuid>"}'

{
  "success": true,
  "data": { "id": "...", "name": "Auto Insurance CA", "status": "ACTIVE" }
}

Responses and errors

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. Authenticate with the buyer's webhook secret in the X-Buyer-Secret header (generated in the destination's Postback Webhook settings; this is NOT the supplier x-api-key). A system that cannot set a custom header uses the Postback URL instead (below), which carries its own key in the address. The body can be JSON or a form (application/x-www-form-urlencoded or multipart/form-data). 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"
  }'

To check what a CRM sent, open the lead and go to the Logs tab. The Postbacks section lists every postback for that lead, with the body that arrived, the reply we sent, and why it failed if it did. In the lead's History, click View request on an Outcome Received row to jump to it. A postback that matched no lead (wrong lead_id, or no lead with that phone) is on the Logs page instead: filter it to Outcome.

Postback URL (for systems that can only paste a URL)

Many CRMs, call trackers and affiliate platforms can only fire a URL: no custom header. For them, each destination has its own Postback URL with a key built into the address, so nothing else is needed to authenticate. Find it in the destination's Postback Webhook settings (the destination's ⋮ menu on the campaign, then Postback Webhook): click Generate Webhook Secret and the Postback URL (No Header) box appears with a copy button. Regenerating the secret changes the URL, and disabling the webhook turns it off.

GET or POST https://app.leaddistro.ai/api/webhooks/buyer-outcome/<key>?lead_id={lead_id}&outcome={outcome}&conversion_revenue={revenue}

It accepts every field the header version accepts, in the query string, a JSON body, or a form body (a body field wins over the same query field). Send outcome every time you want the status to change: firing the URL without one never marks anything converted. A lead then only takes the revenue, value or note you sent, and a call update with no outcome returns 400. call_revenue, payout and conversion_payout are read as conversion_revenue, and money like $1,250.00 is read as 1250. A value still left as a template token (such as {lead_id} or [tag:call_id]) returns 400 naming the field, so fix the mapping in the system that fires the URL. Keep the URL private: anyone with it can update that destination's leads.