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.

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" }

Consent matters. The consent block is your proof the consumer agreed in writing to receive AI/automated calls (TCPA requires it). A lead sent without it is stored but marked ineligible — it will never be dialed. Capture consent on your form and pass the timestamp and language version with every lead.

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.

Rate limits

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

Header	Meaning
`X-RateLimit-Limit`	Your key's allowance per minute
`X-RateLimit-Remaining`	Requests left in the current minute
`X-RateLimit-Reset`	When the window resets (Unix seconds)

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

Code	What it means
`401`	Missing, malformed or revoked API key
`403`	Key is valid but lacks the needed scope (read/write)
`422`	Lead failed validation (e.g. unusable phone) — response lists why
`429`	Rate limit exceeded — wait `Retry-After` seconds

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