API documentation

POST /leads

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads

Send leads to your Trackdrive account.

Submit a new lead to Trackdrive using an offer or schedule lead_token. This is the primary unauthenticated lead-posting endpoint for external integrations: it creates or updates the matching lead, and depending on the parameters sent can restart a schedule, assign a dialing or SMS number, or schedule a callback. Subject to your account's per-second and daily lead rate limits.

Params

Param name	Description
lead_token Optional	The lead token is set to either the offer_lead_token you get at trackdrive.com/offers or a schedule_lead_token you get from trackdrive.com/schedules. The only difference is the use of offer_lead_token will just send data to the offer which is picked up when a call is made with the caller_id of the lead. EG: If a Call Center is transferring data before they send you a call. The schedule_lead_token will start the actions associated with the schedule. Must be a String
caller_id Optional	The callerID for the lead. This is the number Trackdrive will dial when making outbound calls to the lead. This is also the number where Trackdrive will send SMS. Must be a String
email Optional	The email address for the lead. The lead’s email is required for sending emails from schedules to leads. Must be a String
contact_field_type Optional	Pass an ID belonging to an `Agent Script & Field Type` to select that `Custom Contact Field Type` for this call. Must be a String
schedule_callback_at Optional	Schedule a callback with the submitted lead. Must be a valid time EG: 2021-07-23 14:26:43 +0000 Must be a valid time: 2026-10-07 02:28:32 +0000
schedule_callback_in_seconds Optional	Schedule a callback with the submitted lead in X seconds. Must be a valid integer EG: 3600 Must be a String
update_all_matching_leads Optional	If this is true, then the data sent in this request will be applied to all leads that match the Offer or Schedule and caller_id sent in the request. An example usecase is if you are sending a tracking token and want it applied to a lead that is present on two schedules (auto, life) under one offer (insurance) Must be a boolean value: 1, true, yes, on, 0, false, no, off
apply_to Optional	Should the data you’re sending also be applied to calls associated with this lead? Must be one of: `calls`.
unblock_contact Optional	Remove the caller_id from the company blacklist. Usage of this param requires passing an auth_token with permission to update Leads. Must be a boolean value: 1, true, yes, on, 0, false, no, off
blocked Optional	Set this to true in order to prevent this lead from calling any of your telephone numbers. This will also prevent all outbound actions from Trackdrive. Must be a boolean value: 1, true, yes, on, 0, false, no, off
assign_trackdrive_number Optional	Assign a dialing number and return it in the API response as trackdrive_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
assign_sms_number Optional	Assign an SMS number and return it in the API response as sms_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
expire_existing Optional	Expire existing live schedule leads that match the lead_token and caller_id Must be a boolean value: 1, true, yes, on, 0, false, no, off
delete_existing Optional	Delete existing leads that match the lead_token and caller_id Must be a boolean value: 1, true, yes, on, 0, false, no, off
update_only Optional	Only update leads that are still active. When true Trackdrive will only update existing active leads. New leads will not be created. Leads that have completed all their actions will not be updated. Must be a boolean value: 1, true, yes, on, 0, false, no, off
lead_priority Optional	Defines the lead’s priority for processing. Leads with lower values are processed first, influencing the order of scheduled actions such as calls, SMS, emails, and more. Must be a decimal number.
restart_schedule Optional	Restart the schedule for the lead from the beginning. Must be a boolean value: 1, true, yes, on, 0, false, no, off
auto_format_nested_fields Optional	Automatically extract contact fields that are nested inside non-standard incoming POST. Must be a boolean value: 1, true, yes, on, 0, false, no, off
next_action_at Optional	Change when the next action is scheduled to run. EG If you mistakenly scheduled leads to wait until next week, you can use this to bulk update them to run 1 second from now. Must be a valid time: 2026-10-07 02:28:32 +0000
hours_to_expire Optional	Expire the lead after this many hours. The lead will exit schedule and perform end of schedule actions. Must be a Integer
max_contact_attempts Optional	Expire the lead after this many outbound calls + SMS. The lead will exit schedule and perform end of schedule actions. Must be a Integer
data Optional	Trackdrive will convert this hash of JSON data into tokens. Inbound and Outbound calls made and received from this Lead will automatically inherit these tokens. `{interest: 'kittens', source: 'google', first_name: 'John', last_name: 'Smith'}` Emails and SMS also have access to these tokens, so it’s possible to send email and SMS messages that substitute tokens with values, such as {{first_name}}. Example SMS: “Hello {{first_name}} {{last_name}}, thanks for you inquiry. We will be calling you in 30 seconds from {{trackdrive_number}}” Must be a Hash
traffic_source_id Optional Blank value allowed	The traffic source this lead came from, as its Trackdrive id or the traffic source id you gave it (user_traffic_source_id).
opt_out Optional Blank value allowed	Mark the lead as opt-out or opt-in. Opt-out prevents outbound calls, SMS, and email to this caller, but still allows them to dial in to resubscribe.
contact_caller_permission_required Optional Blank value allowed	Whether this caller has given permission to be contacted, as required by your compliance settings.

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/leads/' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000",
  "caller_id": "+18005550100",
  "email": "example-lead@example.com",
  "data": {
    "first_name": "Example",
    "last_name": "Lead"
  }
}'

Example Response 201

{
  "status": 201,
  "success": true,
  "errors": {},
  "lead": {
    "id": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "type": "Lead",
    "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": null,
    "routes_show_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "routes_edit_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/edit",
    "external_record_id": null,
    "contact_field_type": "example_view",
    "schedule_distribution_id": null,
    "name": "+18005550100",
    "caller_id": "+18005550100",
    "email": "example-lead@example.com",
    "full_name": ""
  },
  "metadata": {
    "root": "lead"
  }
}

POST /leads/create_or_update

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/create_or_update

Create or update a lead

Create a new lead if no active lead exists on the offer, or update the existing active lead.

Params

Param name	Description
lead_token Optional	The lead token is set to either the offer_lead_token you get at trackdrive.com/offers or a schedule_lead_token you get from trackdrive.com/schedules. The only difference is the use of offer_lead_token will just send data to the offer which is picked up when a call is made with the caller_id of the lead. EG: If a Call Center is transferring data before they send you a call. The schedule_lead_token will start the actions associated with the schedule. Must be a String
caller_id Optional	The callerID for the lead. This is the number Trackdrive will dial when making outbound calls to the lead. This is also the number where Trackdrive will send SMS. Must be a String
email Optional	The email address for the lead. The lead’s email is required for sending emails from schedules to leads. Must be a String
contact_field_type Optional	Pass an ID belonging to an `Agent Script & Field Type` to select that `Custom Contact Field Type` for this call. Must be a String
schedule_callback_at Optional	Schedule a callback with the submitted lead. Must be a valid time EG: 2021-07-23 14:26:43 +0000 Must be a valid time: 2026-10-07 02:28:32 +0000
schedule_callback_in_seconds Optional	Schedule a callback with the submitted lead in X seconds. Must be a valid integer EG: 3600 Must be a String
update_all_matching_leads Optional	If this is true, then the data sent in this request will be applied to all leads that match the Offer or Schedule and caller_id sent in the request. An example usecase is if you are sending a tracking token and want it applied to a lead that is present on two schedules (auto, life) under one offer (insurance) Must be a boolean value: 1, true, yes, on, 0, false, no, off
apply_to Optional	Should the data you’re sending also be applied to calls associated with this lead? Must be one of: `calls`.
assign_trackdrive_number Optional	Assign a dialing number and return it in the API response as trackdrive_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
assign_sms_number Optional	Assign an SMS number and return it in the API response as sms_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
lead_priority Optional	Defines the lead’s priority for processing. Leads with lower values are processed first, influencing the order of scheduled actions such as calls, SMS, emails, and more. Must be a decimal number.
restart_schedule Optional	Restart the schedule for the lead from the beginning. Must be a boolean value: 1, true, yes, on, 0, false, no, off
auto_format_nested_fields Optional	Automatically extract contact fields that are nested inside non-standard incoming POST. Must be a boolean value: 1, true, yes, on, 0, false, no, off
next_action_at Optional	Change when the next action is scheduled to run. EG If you mistakenly scheduled leads to wait until next week, you can use this to bulk update them to run 1 second from now. Must be a valid time: 2026-10-07 02:28:32 +0000
hours_to_expire Optional	Expire the lead after this many hours. The lead will exit schedule and perform end of schedule actions. Must be a Integer
max_contact_attempts Optional	Expire the lead after this many outbound calls + SMS. The lead will exit schedule and perform end of schedule actions. Must be a Integer
data Optional	Trackdrive will convert this hash of JSON data into tokens. Inbound and Outbound calls made and received from this Lead will automatically inherit these tokens. `{interest: 'kittens', source: 'google', first_name: 'John', last_name: 'Smith'}` Emails and SMS also have access to these tokens, so it’s possible to send email and SMS messages that substitute tokens with values, such as {{first_name}}. Example SMS: “Hello {{first_name}} {{last_name}}, thanks for you inquiry. We will be calling you in 30 seconds from {{trackdrive_number}}” Must be a Hash
traffic_source_id Optional Blank value allowed	The traffic source this lead came from, as its Trackdrive id or the traffic source id you gave it (user_traffic_source_id).
opt_out Optional Blank value allowed	Mark the lead as opt-out or opt-in. Opt-out prevents outbound calls, SMS, and email to this caller, but still allows them to dial in to resubscribe.
contact_caller_permission_required Optional Blank value allowed	Whether this caller has given permission to be contacted, as required by your compliance settings.

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/leads/create_or_update' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000",
  "caller_id": "+18005550101",
  "email": "example-lead-2@example.com",
  "data": {
    "first_name": "Example",
    "last_name": "Update"
  }
}'

Example Response 201

{
  "status": 201,
  "success": true,
  "errors": {},
  "lead": {
    "id": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "type": "Lead",
    "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": null,
    "routes_show_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "routes_edit_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/edit",
    "external_record_id": null,
    "contact_field_type": "example_view",
    "schedule_distribution_id": null,
    "name": "+18005550101",
    "caller_id": "+18005550101",
    "email": "example-lead-2@example.com",
    "full_name": ""
  },
  "metadata": {
    "root": "lead"
  }
}

PUT /leads/:caller_id/caller_opt_out

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:caller_id/caller_opt_out

Opt out a lead by caller ID

Mark a single lead as opt-out. Opted-out leads will no longer be sent SMS, Calls, or Emails.

Params

Param name

Description

lead_token
Required

The lead token is set to either the offer_lead_token you get at trackdrive.com/offers or a schedule_lead_token you get from trackdrive.com/schedules. The only difference is the use of offer_lead_token will just send data to the offer which is picked up when a call is made with the caller_id of the lead. EG: If a Call Center is transferring data before they send you a call. The schedule_lead_token will start the actions associated with the schedule.

Must be a String

Example Request

curl -X PUT -d '' trackdrive.com/api/v1/leads/17194977450/caller_opt_out?lead_token=yourtoken

# GET requests are supported
curl trackdrive.com/api/v1/leads/17194977450/caller_opt_out?lead_token=yourtoken

POST /leads/:caller_id/caller_remove

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:caller_id/caller_remove

Remove a lead by caller ID

Remove a single lead from a Schedule or Offer. This will prevent ANY additional actions being taken on behalf of the lead.

Params

Param name

Description

lead_token
Required

Must be a String

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/leads/+18005550100/caller_remove' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000"
}'

Example Response 200

{
  "status": 204
}

PUT /leads/:caller_id/caller_move_to_end_of_schedule

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:caller_id/caller_move_to_end_of_schedule

Requeue a lead by caller ID

Move every active lead matching the given lead_token and caller_id to the end of its schedule, so those leads are processed again after the ones ahead of them.

Params

Param name

Description

lead_token
Required

Must be a String

Example Request

curl -X PUT 'https://[your-subdomain].trackdrive.com/api/v1/leads/+18005550100/caller_move_to_end_of_schedule' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000"
}'

Example Response 200

{
  "status": 204
}

POST /leads/:lead_id/lead_update

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:lead_id/lead_update

Update a lead by lead ID

Update one specific lead by its Trackdrive lead id. Unlike the caller_id endpoints, only the lead you name is changed.

Params

Param name	Description
lead_token Required	The lead token is set to either the offer_lead_token you get at trackdrive.com/offers or a schedule_lead_token you get from trackdrive.com/schedules. The only difference is the use of offer_lead_token will just send data to the offer which is picked up when a call is made with the caller_id of the lead. EG: If a Call Center is transferring data before they send you a call. The schedule_lead_token will start the actions associated with the schedule. Must be a String
lead_id Required	The Trackdrive lead id (uuid) returned in the response when the lead was submitted. Identifies exactly one lead, so updates never touch another lead that shares the same caller_id. Must be a String
email Optional	The email address for the lead. The lead’s email is required for sending emails from schedules to leads. Must be a String
contact_field_type Optional	Pass an ID belonging to an `Agent Script & Field Type` to select that `Custom Contact Field Type` for this call. Must be a String
schedule_callback_at Optional	Schedule a callback with the submitted lead. Must be a valid time EG: 2021-07-23 14:26:43 +0000 Must be a valid time: 2026-10-07 02:28:32 +0000
schedule_callback_in_seconds Optional	Schedule a callback with the submitted lead in X seconds. Must be a valid integer EG: 3600 Must be a String
update_all_matching_leads Optional	If this is true, then the data sent in this request will be applied to all leads that match the Offer or Schedule and caller_id sent in the request. An example usecase is if you are sending a tracking token and want it applied to a lead that is present on two schedules (auto, life) under one offer (insurance) Must be a boolean value: 1, true, yes, on, 0, false, no, off
apply_to Optional	Should the data you’re sending also be applied to calls associated with this lead? Must be one of: `calls`.
unblock_contact Optional	Remove the caller_id from the company blacklist. Usage of this param requires passing an auth_token with permission to update Leads. Must be a boolean value: 1, true, yes, on, 0, false, no, off
blocked Optional	Set this to true in order to prevent this lead from calling any of your telephone numbers. This will also prevent all outbound actions from Trackdrive. Must be a boolean value: 1, true, yes, on, 0, false, no, off
assign_trackdrive_number Optional	Assign a dialing number and return it in the API response as trackdrive_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
assign_sms_number Optional	Assign an SMS number and return it in the API response as sms_number_plain Must be a boolean value: 1, true, yes, on, 0, false, no, off
lead_priority Optional	Defines the lead’s priority for processing. Leads with lower values are processed first, influencing the order of scheduled actions such as calls, SMS, emails, and more. Must be a decimal number.
restart_schedule Optional	Restart the schedule for the lead from the beginning. Must be a boolean value: 1, true, yes, on, 0, false, no, off
auto_format_nested_fields Optional	Automatically extract contact fields that are nested inside non-standard incoming POST. Must be a boolean value: 1, true, yes, on, 0, false, no, off
next_action_at Optional	Change when the next action is scheduled to run. EG If you mistakenly scheduled leads to wait until next week, you can use this to bulk update them to run 1 second from now. Must be a valid time: 2026-10-07 02:28:32 +0000
hours_to_expire Optional	Expire the lead after this many hours. The lead will exit schedule and perform end of schedule actions. Must be a Integer
max_contact_attempts Optional	Expire the lead after this many outbound calls + SMS. The lead will exit schedule and perform end of schedule actions. Must be a Integer
data Optional	Trackdrive will convert this hash of JSON data into tokens. Inbound and Outbound calls made and received from this Lead will automatically inherit these tokens. `{interest: 'kittens', source: 'google', first_name: 'John', last_name: 'Smith'}` Emails and SMS also have access to these tokens, so it’s possible to send email and SMS messages that substitute tokens with values, such as {{first_name}}. Example SMS: “Hello {{first_name}} {{last_name}}, thanks for you inquiry. We will be calling you in 30 seconds from {{trackdrive_number}}” Must be a Hash
traffic_source_id Optional Blank value allowed	The traffic source this lead came from, as its Trackdrive id or the traffic source id you gave it (user_traffic_source_id).
opt_out Optional Blank value allowed	Mark the lead as opt-out or opt-in. Opt-out prevents outbound calls, SMS, and email to this caller, but still allows them to dial in to resubscribe.
contact_caller_permission_required Optional Blank value allowed	Whether this caller has given permission to be contacted, as required by your compliance settings.

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/lead_update' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000",
  "email": "example-lead-updated@example.com"
}'

Example Response 200

{
  "status": 200,
  "success": true,
  "errors": {},
  "lead": {
    "id": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "type": "Lead",
    "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": null,
    "routes_show_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "routes_edit_path": "/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/edit",
    "external_record_id": null,
    "contact_field_type": "example_view",
    "schedule_distribution_id": null,
    "name": "+18005550100",
    "caller_id": "+18005550100",
    "email": "example-lead-updated@example.com",
    "full_name": ""
  },
  "metadata": {
    "root": "lead"
  }
}

PUT /leads/:lead_id/lead_opt_out

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:lead_id/lead_opt_out

Opt out a lead by lead ID

Mark a lead as opt-out by its Trackdrive lead id. Opted-out leads will no longer be sent SMS, Calls, or Emails. Opt-out applies to the contact, so every lead sharing that caller_id is opted out.

Params

Param name

Description

lead_token
Required

Must be a String

lead_id
Required

The Trackdrive lead id (uuid) returned in the response when the lead was submitted. Identifies exactly one lead, so updates never touch another lead that shares the same caller_id.

Must be a String

Example Request

curl -X PUT -d '' trackdrive.com/api/v1/leads/74da9151-d988-4428-8087-c8dcf47ae9a2/lead_opt_out?lead_token=yourtoken

# The lead id can also be passed as a param:
curl -X PUT -d '' trackdrive.com/api/v1/leads/lead_opt_out?lead_token=yourtoken&lead_id=74da9151-d988-4428-8087-c8dcf47ae9a2

POST /leads/:lead_id/lead_remove

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:lead_id/lead_remove

Remove a lead by lead ID

Remove one specific lead from a Schedule or Offer by its Trackdrive lead id. This will prevent ANY additional actions being taken on behalf of the lead.

Params

Param name

Description

lead_token
Required

Must be a String

lead_id
Required

The Trackdrive lead id (uuid) returned in the response when the lead was submitted. Identifies exactly one lead, so updates never touch another lead that shares the same caller_id.

Must be a String

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/lead_remove' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000"
}'

Example Response 200

{
  "status": 204
}

PUT /leads/:lead_id/lead_move_to_end_of_schedule

Lead token required

https://[your-subdomain].trackdrive.com/api/v1/leads/:lead_id/lead_move_to_end_of_schedule

Requeue a lead by lead ID

Move a single lead, identified by its lead_id (uuid) and lead_token, to the end of its schedule for reprocessing.

Params

Param name

Description

lead_token
Required

Must be a String

lead_id
Required

The Trackdrive lead id (uuid) returned in the response when the lead was submitted. Identifies exactly one lead, so updates never touch another lead that shares the same caller_id.

Must be a String

Example Request

curl -X PUT 'https://[your-subdomain].trackdrive.com/api/v1/leads/a6af7847-1b1e-4760-ac0d-e1813a6d3a09/lead_move_to_end_of_schedule' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lead_token": "de65622aaeaebe3938b06b96fdad5000"
}'

Example Response 200

{
  "status": 204
}