Quickstart

Send your first lead in about five minutes. Once a lead lands, our AI voice agent calls it, prequalifies the consumer, and warm-transfers live buyers to your destination number — you just feed it leads and collect the results.

Your plan subscription is billed when you sign up (there's no free trial). AI-call time draws a small per-minute platform fee from a prepaid balance, and new accounts start with $10 of free credit. If that balance hits $0, outbound calling pauses (nothing is charged automatically) until you add funds from the dashboard — lead intake through the API keeps working the whole time. See Billing & usage below.

1. Create an API key

In the dashboard, go to app.lead2inbound.com → Settings → API Keys and create a key.

• Keys start with l2i_ and are shown once — copy it somewhere safe.
• Scopes: write lets a key send leads, read lets it pull them back. Give a form or vendor only what it needs.
• Each key has its own rate limit (default 120 requests/minute).

2. Send a lead

POST the lead as JSON. Only phone is required, but send everything you have — name and state make the AI conversation better, and state keeps calls inside legal calling hours.

curl -X POST https://api.lead2inbound.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my-webform",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "5551234567",
    "state": "TX",
    "consent": {
      "consent_timestamp": "2026-07-05T12:00:00Z",
      "consent_text_version": "webform-v2",
      "source_url": "https://example.com/quote"
    }
  }'

A successful response looks like:

{ "outcome": "created", "lead_id": "6f1c2d3e-…", "status": "new" }

3. Check it arrived

curl https://api.lead2inbound.com/v1/leads?limit=5 \
  -H "Authorization: Bearer YOUR_API_KEY"

You'll get your newest leads with their current status — new, dialing, qualified, transferred, and so on.

4. Report call revenue (postback)

When your buyer platform (LeadRouter, Ringba, Retreaver, …) finishes a transferred call, have it fire your postback URL so lead2inbound records what the call paid. Copy the URL — it includes your private token — from Settings → Destinations → Revenue postbacks. It looks like:

https://api.lead2inbound.com/v1/postbacks/calls?token=YOUR_POSTBACK_TOKEN

Add whatever result fields your platform offers — common names are recognized automatically (caller_id, duration, buyer, payout in dollars or payout_cents). A test hit:

curl "https://api.lead2inbound.com/v1/postbacks/calls?token=YOUR_POSTBACK_TOKEN&caller_id=%2B15551234567&duration=247&buyer=Acme&payout=38.50"

We match the hit to the transferred call by caller ID (±4 hours) and the revenue shows up in your stats and on the transfer record.

Automate your whole setup over the API

Anything you can click in the dashboard you can also script — worth doing if you spin up a campaign per traffic source, or run accounts for clients.

Scopes decide what a key is allowed to do. Give each integration the smallest one that works:

Grant admin only to code you run yourself, server-side — never to a web form, a lead vendor, or anything living in a browser. A leaked write key can send you junk leads; a leaked admin key can swap out the AI account that talks to your consumers.

A full setup is three calls:

# 1. Add a buyer destination — the number we warm-transfer qualified consumers to.
curl -X POST https://api.lead2inbound.com/v1/destinations \
  -H "Authorization: Bearer WRITE_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Acme Final Expense", "phone": "5125550142" }'
# → { "id": "8d2f1a90-…" }

# 2. Create a campaign — one calling operation: which AI agent calls, when it may
#    call, and which buyers it transfers to. agent_id comes from GET /v1/agents
#    (no agent yet? an admin key can build one from a template with
#    POST /v1/agent-templates/provision).
curl -X POST https://api.lead2inbound.com/v1/campaigns \
  -H "Authorization: Bearer WRITE_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Final Expense — TX",
    "agent_id": "3c8b7a10-…",
    "destinations": [{ "destination_id": "8d2f1a90-…", "position": 0 }]
  }'
# → { "id": "0f9a1b2c-…" }  — created in draft, so it dials nobody yet.

# 3. Turn it on.
curl -X POST https://api.lead2inbound.com/v1/campaigns/0f9a1b2c-…/status \
  -H "Authorization: Bearer WRITE_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Now point your traffic at POST /v1/leads (step 2 above). Rather than making every vendor pass campaign_id, give each lead source its own API key with a default campaign (Settings → API Keys): leads sent on that key land in that campaign automatically, so moving a source to a different campaign is a dashboard change instead of an email to your vendor.

Then watch it run with GET /v1/stats — the funnel from leads received to transfers and revenue. Add ?group=day for a time series, ?group=campaign, ?group=source to see which vendor actually converts, or ?group=destination for per-buyer numbers, and ?from=/?to= to pick the window (default: last 30 days).

curl "https://api.lead2inbound.com/v1/stats?group=source&from=2026-07-01" \
  -H "Authorization: Bearer READ_KEY"

Rate limits

Limits are per key, per minute. Every authenticated response includes:

Go over and you'll get 429 with a Retry-After header — wait that many seconds and retry. Batch imports? Use the CSV importer in the dashboard instead of hammering the API.

Errors

Billing & usage

Your monthly (or annual) plan subscription is billed in advance when you sign up — there's no free trial. On top of the plan, AI-call time carries a small per-minute platform fee, and that fee is prepaid: it draws down a balance in real time rather than arriving on a month-end invoice.

New accounts start with $10 of free platform-fee credit. Manage the balance in the dashboard under Settings → Platform-fee balance: add funds on demand (minimum $20; quick $20 / $50 / $100) or turn on auto-recharge (off by default), which tops up $20 whenever the balance falls below $10.

Your voice and telephony vendors (Retell, Twilio, …) bill their own usage separately, at their prices, through your own accounts — that part is unchanged.

Full request/response details for every endpoint: API reference.