Partner API

Overview

The Lead Distro AI Partner API lets external platforms exchange lead data, push post-delivery updates, and receive real-time events. It is designed for analytics platforms (like Attribute), CRMs (Salesforce, HubSpot, GHL), affiliate networks, and any system that needs bi-directional data flow with a lead distribution pipeline.

There are two directions of data flow: inbound (your platform sends data to Lead Distro AI) and outbound (Lead Distro AI sends events to your platform via webhooks).

Lead Distro AI can also send events to your platform via outbound webhooks. See the Outbound Webhooks section below.

Authentication

All Partner API endpoints authenticate with a Supplier API Key passed in the x-api-key header. Each supplier gets a unique API key when created in the dashboard. The key scopes all operations to the supplier's organization.

x-api-key: YOUR_SUPPLIER_API_KEY

Lead Ingest (POST /api/v1/ingest)

Send new leads into Lead Distro AI for validation, scoring, and distribution to buyers. Accepts both JSON and form-encoded bodies.

curl -X POST https://www.leaddistro.ai/api/v1/ingest \
  -H "x-api-key: YOUR_SUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flo_campaign_id": "campaign-uuid",
    "flo_supplier_id": "supplier-uuid",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "5551234567",
    "email": "jane@example.com",
    "state": "TX",
    "zip_code": "75001"
  }'

Required fields: flo_campaign_id, flo_supplier_id, first_name, last_name, phone, email. Additional fields depend on the campaign's field mapping configuration.

Response (201): Returns success: true, lead_id, status, price, and distribution details (buyer name, delivery result). For ping-post campaigns, also includes the deliveries array with per-buyer bid and delivery status.

Ping Endpoint (POST /api/v1/ping)

For ping-post campaigns, the ping endpoint lets suppliers submit partial lead data to get real-time bids from buyers before committing the full lead. The response includes the BAM (Bid After Margin) price and a ping_id token used in the follow-up POST.

curl -X POST https://www.leaddistro.ai/api/v1/ping \
  -H "x-api-key: YOUR_SUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flo_campaign_id": "campaign-uuid",
    "flo_supplier_id": "supplier-uuid",
    "state": "CA",
    "zip_code": "90210"
  }'

Response (200, accepted): accepted: true, ping_id, price (BAM), expires_at (5-minute TTL). Use the ping_id in the follow-up /api/v1/ingest POST to complete the transaction.

Lead Update (POST /api/v1/lead-update)

Push post-delivery data back to Lead Distro AI. This is the primary integration point for analytics platforms, CRMs, and any system that tracks what happens after a lead is delivered. Accepts fields like sales rep, speed-to-lead, call count, outcome, and revenue.

curl -X POST https://www.leaddistro.ai/api/v1/lead-update \
  -H "x-api-key: YOUR_SUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "lead-uuid",
    "call_outcome": "appointment_set",
    "call_outcome_raw": "Requested Appointment",
    "sales_rep": "John Smith",
    "outcome": "converted",
    "revenue": 2500.00,
    "note": "Signed retainer agreement"
  }'

Response (200): Returns success: true, lead_id, external_id, outcome (with change details), call_count, speed_to_lead_seconds, and fields_updated.

Outbound Webhooks (Lead Distro AI to Your Platform)

Lead Distro AI sends lead events to your platform via automation webhooks. Agencies configure these per campaign in the Automations section. No code changes needed on the Lead Distro AI side.

Webhooks are HTTP POST requests with a JSON payload containing all lead fields, campaign context, buyer/supplier details, UTM data, and custom fields from the campaign's field mapping. Outbound webhooks include an HMAC-SHA256 signature in the X-LeadDistro-Signature header for verification. See the Webhook Signing doc for verification recipes.

Rate Limits

Rate-limited responses return HTTP 429 with a Retry-After header (seconds). Back off and retry after the indicated delay. For high-volume integrations, contact support for limit increases.

Error Codes