How to Submit Leads via API

API Endpoint

Leads are submitted with a POST to /api/v1/leads
(also accepts PUT).

The request accepts:

a lead_token that identifies the destination schedule or offer,
a caller_id that identifies the lead's phone number,
arbitrary additional fields that become Lead tokens.

Companion endpoints include /api/v1/leads/capture,
/api/v1/leads/create_or_update, and per-caller
operations such as caller_remove, caller_opt_out,
and caller_move_to_end_of_schedule.

Finding Your Lead Token in the App

Every schedule has a unique lead API token. To reveal
it:

Open the schedule's edit page at /schedules/:id/edit.
Click the API Token & Examples link near the top of the page.
The page that opens (/schedules/:id/submit_leads_help) displays the API Token value plus copy-ready code samples in tabs labeled Bash & Curl, PHP, Instapage, and Javascript.

The same page also includes a Webhook URL Example
and a URL Example With Traffic Source & Sub ID.
Treat the API token like a password - leaking it
allows third parties to enroll leads into your
schedule.

Example: HTTP Form POST

curl -X POST \
  "https://your-domain.com/api/v1/leads?lead_token=YOUR_TOKEN&caller_id=+18004506787&email=john@example.com&interest=kittens"

Form parameters on the query string are the simplest
integration path. Every non-reserved parameter becomes
a Lead token.

Example: JSON POST

curl -H "Content-Type: application/json" -X POST \
  -d '{"lead_token":"YOUR_TOKEN","caller_id":"+18004506787","expires_in":60,"data":{"interest":"kittens","email":"john@example.com"}}' \
  https://your-domain.com/api/v1/leads

JSON is preferred for structured data or when the lead
payload contains special characters that complicate URL
encoding. The data hash is a container for Lead
tokens; top-level keys are reserved for platform fields
like caller_id, expires_in, and lead_token.

Response

A successful submission returns HTTP 200 with the
serialized lead. Validation failures return HTTP 422
with a machine-readable error body. An unrecognized
lead_token returns 401.

Traffic Source and Sub ID Attribution

Two optional parameters power click-level attribution on
the submitted lead:

traffic_source_id: the ID of a traffic source record already configured on the company.
sub_id: a free-form identifier for a sub-publisher or creative within that traffic source.

Include them as query parameters alongside lead_token
and caller_id. Subsequent calls and conversions
attributed to the lead will roll up under the matching
source/sub-source in reporting.

Webhooks From Form Builders

Most web form builders (Instapage, Unbounce, LeadPages,
custom forms) support webhook integrations that POST
form submissions to a URL of your choice. Paste the
endpoint above into the form builder's webhook settings
with your lead_token in the query string, and
submissions will enroll into Trackdrive automatically.