Warm Transfer (Pre-Call Data)

A warm transfer (also called a live transfer) is when your source pre-qualifies a caller and then bridges the live call to your tracking number, instead of the caller dialing in cold. This guide shows how to send that caller's details a moment before the transfer, so Lead Distro AI can attach them to the call. For the basics of a call campaign first, see Call Tracking Setup.

When to use it

• Your buyer pays per qualified or passed call, not per lead, so each call needs to be tied to who the caller was.
• You want the caller's details (name, state, case type, TrustedForm, your own lead id) on the call record for reporting, reconciliation, and dispute review.
• Your source runs a warm or live transfer through a dialer that can send a quick web request before it bridges the call.

How it works

• Your source sends the caller's details to the call enrichment endpoint (a quick GET or POST) right before the transfer.
• Your source bridges the live call to your campaign's tracking number.
• Lead Distro AI matches the two by the caller's phone number and shows the details on the call record.

The thing to hold onto: two separate things are travelling, and they do not wait for each other. The call goes over the phone line. The caller's details go over the internet, as their own web request. Nothing ties them together except the caller's phone number, which is why the order they arrive in matters, and why almost every problem on this page is really a question of which one got there first.

Step 1: Turn on Pre-call Data and choose your fields

Open your call campaign, go to Settings, and turn on Pre-call Data. A Fields tab appears where you choose which parameters to accept: add whatever your vertical needs (first name, state, case type, ZIP, your own lead id, anything). There is no fixed list. We always keep the caller's name, phone, and email; the Fields tab is for the extra fields you want stored and shown on the call.

The same card has a Wait for source data box. Leave it at 0 for now. It only matters when a destination refuses calls that arrive without the data, which has its own section further down.

Step 2: Send the caller details

Send the fields to the enrichment endpoint using the same API key your source already uses. You can send them as a POST with a JSON body, or as a GET with query values, whichever your dialer supports. The callerid is the consumer's phone in E.164 format (like +13105551234) and is required, since it's the key we match on.

curl -X POST https://app.leaddistro.ai/api/v1/calls/enrich \
  -H "x-api-key: YOUR_SUPPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flo_campaign_id": "YOUR_CAMPAIGN_ID",
    "flo_supplier_id": "YOUR_SUPPLIER_ID",
    "callerid": "+13105551234",
    "first_name": "Maria",
    "state": "TX",
    "case_type": "MVA",
    "trustedform_url": "https://cert.trustedform.com/...",
    "lead_id": "YOUR-LEAD-ID"
  }'

Prefer a simple GET? Send the same values as query parameters (send the x-api-key as a header, and URL-encode the + in callerid as %2B):

https://app.leaddistro.ai/api/v1/calls/enrich?flo_campaign_id=YOUR_CAMPAIGN_ID&flo_supplier_id=YOUR_SUPPLIER_ID&callerid=%2B13105551234&first_name=Maria&state=TX&case_type=MVA&lead_id=YOUR-LEAD-ID

On success you get back a confirmation of exactly what we stored and will match on:

{
  "success": true,
  "mode": "call_enrichment",
  "stored": true,
  "matched": false,
  "caller_phone": "+13105551234",
  "fields_stored": ["first_name", "state", "case_type", "trustedform_url"],
  "external_lead_id": "YOUR-LEAD-ID",
  "expires_at": "...",
  "match_window_hours": 48
}

stored: true only means we saved the details and opened the 48 hour match window. It is not a promise that they reached a call. That is what matched tells you. Posting before the transfer, matched is normally false, because the call has not arrived yet, and it becomes true when the call lands and picks the details up.

If the call beat your post, we say so instead of staying quiet about it:

{
  "success": true,
  "stored": true,
  "matched": false,
  "warning_code": "call_already_received",
  "warning": "A call from this number arrived 1.7s before this post, so it was routed without this data."
}

Seeing call_already_received means your dialer is bridging before it finishes posting. Fix the order in your dialer. Posting faster will not close the gap reliably, because it is a race you only win by accident.

Step 3: Bridge the live call

Send the live call to your campaign's tracking number, passing the consumer's phone number as the caller ID. When the call lands, we match it to the details you sent and attach them.

Step 4: Set the destination to bill on connect

Because your buyer pays for a passed transfer rather than talk time, set the destination to bill when the call connects. Open the destination in Edit Target, set billing to bill on connect with a 1 second minimum, and save. If a transfer doesn't qualify, refund that call from the call's page and it shows as Returned. See Wallet & Top-Ups.

Step 5: Send the details on to your destination (optional)

The details are on your call record either way. If your destination wants them too, in their CRM, or in an inbox while the call is still live, you have two options, and you can use both.

• Data Delivery (per destination). Open the destination in Edit Target, turn on Data Delivery, and fill in the endpoint URL, method, any custom headers, and the body template. We post the caller's phone and location plus every pre-call field to their endpoint. Send Test fires a sample so you can validate their endpoint before a real call rings.
• When to send picks the timing. On connect (the default) fires the moment that destination answers, and only to the destination that actually took the call. Before dial fires just before we ring each destination, so the data is usually in their hands when the phone rings. It is a head start, not a guarantee: we give the send a 0.8 second head start, then ring anyway rather than leave a live caller sitting in silence, and a slower endpoint gets the data a beat after its phone starts.
• A Call Connected automation (campaign-wide). On the campaign's Overview tab, go to Triggers & Automations, add an automation with the Call Connected trigger, and choose the Email, Webhook, Slack, or Google Sheet action. The Fields picker includes a Pre-Call Data group, so you can drop the caller's fields straight into an email to your client.

When a destination only takes calls that have the data

Some destinations will not accept a transfer unless the caller's details are already attached. That is a routing rule, not a delivery preference, and it takes two settings working together. Turn on only one and the destination turns away calls whose details you did in fact send.

• Add the rule on the destination. Open the destination in Edit Target, go to Call Filters, and add Precall Data Is Not Empty. That destination now only rings for calls a source announced.
• Set the grace window on the campaign. In Settings, under Pre-call Data, set Wait for source data to 2 or 3 seconds. We hold the call just long enough for the details to land, then route. We check four times a second and stop waiting the instant they arrive, so the usual cost is your source's real lag, not the whole budget.

A greeting or a recording notice plays during the wait, so most callers never notice it. The cap is 10 seconds, and 0 means never wait, which is how every campaign behaves until you change it.

Telling versus asking

There are two ways to send a caller's details ahead of a call, and the difference between them is not technical. It is what you are actually saying to the destination.

Everything above on this page is telling. It is the right tool when the destination takes every call you send and simply wants to know who is on the line. The two settings in the last section make sure the telling arrives in time.

But telling has a ceiling: a filter can only screen a destination out of a call. It can never let that destination accept one, refuse one, or put a price on it. The moment your destination wants a say, you are asking, not telling, and asking is RTB. We send the caller's details to their bid endpoint and wait for the answer before anything rings, so a rejected transfer is one your source never bridges.

• In Edit Target, set Routing method to Dynamic routing (RTB) and fill in their bid endpoint.
• Set Ping when to Pre-call data arrives (pre-transfer). This is the setting that matters. We ping the destination the moment your source posts the caller's details, and your source gets the accept or reject in that same response, so it only bridges calls that were already accepted. Nobody is on the line yet, so the wait costs the caller nothing.
• In Ping parameters, add each pre-call field with the Lead field source, so their bid request carries the same details your source announced.
• Their response tells us whether they take it, what they pay, and which number to dial. If their endpoint only answers yes or no, set Target mode to Availability check and leave the forwarding number set, and we dial that.

Sending calls to another Lead Distro AI account

If your destination is another Lead Distro AI account, you are on both sides of this handoff: you send the call, they receive it on their tracking number. That works well, but there is one wiring mistake worth calling out, because it looks correct and fails silently.

Pick the mechanism by what the receiving side needs to do with the data:

If the receiving side only needs to know who is calling, send the details before the transfer. If they need to decide whether to take the call and what to pay for it, use RTB: the bid request carries the caller's details and their answer comes back before the transfer happens, so the ordering is guaranteed rather than left to timing.

Where the data shows up

Open the call from the Calls page. The Pre-call data card shows your lead id and every field you sent, tied to that exact call, ready for reporting, reconciliation, or a dispute.

Limits to know

• Matching needs the consumer's caller ID. If the transfer shows the dialer's own number instead, we can't match on the phone. Ask support about a dedicated number per lead.
• You have 48 hours from sending the details to bridge the call, then the saved details expire.
• The destination only gets the fields if you send them. The details always land on your call record. To pass them into the destination's own system, turn on Data Delivery or a Call Connected automation (see the step below).

FAQ