Leads

Manage the leads in your Trackdrive account via API.

GET /leads

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

List your leads.

Search and list leads in your account with filtering, sorting, and pagination. Also supports specialized modes for leads waiting on Instant Agent permission, leads with a scheduled callback ready to run, or currently live billable leads.

Params

Param name Description
serializer
Optional Blank value allowed

This endpoint supports multiple response formats. Pass serializer=name to retrieve data in an alternate format.

  • Must be a value contained in the pick list:
    Acceptable ValueDescription
    leadLead
    lead_gridLead Grid
    lead_externalLead External
page
Optional

Return the next page of results.

  • Must be a number.
per_page
Optional

How many results to return per page. The default is 25.

  • Must be a number.
created_at_to
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
created_at_from
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
fulltext
Optional

Search for any record that matches this text

  • Must be a String
time_zone
Optional

Date ranges will be parsed using this time zone.
columns
Optional 		Specify the columns you would like returned by the API for a given resource. Limiting the columns can significantly increase API response time since only the requested data will be processed. columns=uuid,number,created_at

Must be any combination of:

  • id
  • legacy_id
  • type
  • uuid
  • created_at
  • updated_at
  • deleted_at
  • user_updated_at
  • routes_show_path
  • routes_edit_path
  • external_record_id
  • context_menu_name
  • name
  • caller_id
  • email
  • full_name
  • contact_field_type
  • expires_in
  • country
  • state_province
  • zip_postal_code
  • time_zone
  • sub_id
  • offer_id
  • schedule_id
  • status
  • human_status
  • css_status
  • has_next_action
  • opt_out
  • revenue
  • payout
  • offer_converted
  • buyer_converted
  • traffic_source_id
  • buyer_id
  • lead_import_id
  • remote_ip
  • attempted_call_id
  • connected_call_id
  • scheduled_callback_id
  • call_buyer_conversion_id
  • call_offer_conversion_id
  • sms_number_id
  • dial_number_id
  • dial_tier
  • last_action_at
  • first_action_at
  • first_queued_at
  • schedule_ended_at
  • next_action_at
  • last_call_at
  • is_live
  • schedule_trigger_type
  • blocked
  • data

  • Must be a String
root
Optional

Pass root=false to return results without a root node and metadata.
For example:
GET /api/v1/calls?root=false will return [call1, call2, call3]
While:
GET /api/v1/calls will return {calls: [call1, call2, call3], metadata: {}}

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
created_at_label
Optional Blank value allowed

Dynamic Date String such as “Today” or “This Year”

  • Must be one of: Last 5 Min, Last 15 Min, Last 30 Min, Last Hour, Last 4 Hours, Last 6 Hours, Last 12 Hours, Last Day, Last 2 Days, Today, Yesterday, This Week, Last Week, This Month, Last Month, This Quarter, Last Quarter, Last 6 Months, This Year, Last Year, Lifetime, Custom Range.
next_action_at_to
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
next_action_at_from
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
offer_id
Optional

Refer to the offer api for details
schedule_id
Optional

Schedule internal id.
contact_id
Optional

Match calls that were placed by this caller.
traffic_source_id
Optional

Refer to the traffic source api for details
buyer_id
Optional

Refer to the buyer api for details
status
Optional

Match results that have this status.

  • Must be a String
status_wait
Optional

Filter for leads that are waiting before performing an action.

  • Must be a String
number
Optional

The lead’s caller number. This is the number Trackdrive will dial when making outbound calls to the lead, and 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
has_next_action
Optional

Filter for leads that have more actions to perform.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
buyer_converted
Optional

Select leads that have converted.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
offer_converted
Optional

Select leads where a traffic source converted.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
either_converted
Optional

Select leads where either a buyer or traffic source converted.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
opt_out
Optional

Select leads that have opted-out.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off

GET /leads/:id

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

Get details about a lead.

Retrieve full details of one lead, including its contact info, offer, schedule, and current status.

GET /leads/:id/buyer_is_available

Authorization Required
https://[your-subdomain].trackdrive.com/api/v1/leads/:id/buyer_is_available

Check whether a lead has a buyer

Check if a lead has a potential buyer available that matches the lead’s filters.

GET /leads/:lead_token/:caller_number/by_caller_number

Authorization Required
https://[your-subdomain].trackdrive.com/api/v1/leads/:lead_token/:caller_number/by_caller_number

Get a lead by caller number

Look up a lead using an offer's or schedule's lead_token combined with the caller's phone number, instead of the lead's own id.

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_number
Optional

Find the lead by this caller number.

  • Must be a String

PUT /leads/:id

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

Update a lead by uuid.

Update a lead's data and attributes by its uuid. Depending on the parameters sent, this can also move the lead to another schedule, grant permission to run its next action, or schedule a callback.

Params

Param name Description
contact_field_type
Optional Blank value allowed

Pass an ID belonging to an Agent Script & Field Type to select that Custom Contact Field Type for this call.

  • Must be a String
caller_id
Optional Blank value allowed

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
number
Optional Blank value allowed

The lead’s caller number. This is the number Trackdrive will dial when making outbound calls to the lead, and the number where Trackdrive will send SMS.

  • Must be a String
blocked
Optional Blank value allowed

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
opt_out
Optional Blank value allowed

Select leads that have opted-out.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
email
Optional Blank value allowed

The email address for the lead. The lead’s email is required for sending emails from schedules to leads.

  • Must be a String
traffic_source_id
Optional Blank value allowed

Update the traffic source associated with this lead.
schedule_id
Optional Blank value allowed

Reassign the lead to a different Schedule. Only takes effect when the lead is already owned by a Schedule; it does not move a lead between a Schedule and an Offer.
offer_id
Optional Blank value allowed

Reassign the lead to a different Offer. Only takes effect when the lead is already owned by an Offer; it does not move a lead between an Offer and a Schedule.
expires_in
Optional Blank value allowed

For how many minutes should the lead stay in our database before it is automatically deleted? Leave this blank to set an infinite expiry. The default is to never delete leads.

  • Must be a decimal number.
next_action_at
Optional Blank value allowed

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-09-29 04:40:15 +0000
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-09-29 04:40:15 +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
schedule_start
Optional Blank value allowed

Adds the lead back into the Schedule. Remaining actions will be performed.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
schedule_stop
Optional Blank value allowed

Removes the lead from the Schedule. No further actions will be taken.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
manual_schedule_restart
Optional Blank value allowed

When true, restarts the lead’s schedule from the beginning.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
manual_opt_in
Optional Blank value allowed

When true, marks the lead as opted-in, allowing outbound actions (calls, SMS, emails) to resume.

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
manual_opt_out
Optional Blank value allowed

When true, marks the lead as opted-out, preventing outbound actions (calls, SMS, emails).

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off
place_call_in_seconds
Optional Blank value allowed

Place an outbound call to the lead this many seconds from now. Use 0 to place the call immediately.

  • Must be a decimal number.
move_to_another_schedule_id
Optional Blank value allowed

Move To Another Schedule - Assign matching leads to the selected schedule. Lead’s already on the selected schedule will restart their schedule.
apply_to
Optional Blank value allowed

Should the data you’re sending also be applied to calls associated with this lead?

  • Must be one of: calls, self.
data
Optional Blank value allowed

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

GET /leads/new

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

Build a new lead with company defaults.

Return a new, unsaved lead pre-filled with your company defaults, useful for previewing the record shape before creating one.

DELETE /leads/:id/id

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

Destory a lead by it's internal id.

Soft delete a lead by its uuid, excluding it from future lookups without permanently removing the record. The id must be the lead's uuid; its internal numeric id is not accepted here. Requires delete permission.

GET /leads/reports

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

Get statistics on leads by category.

Return aggregated lead statistics grouped by a category such as offer, schedule, or traffic source. The category parameter is required. Supports JSON or CSV output; CSV can be returned as a downloadable file. A team member also needs summary reports enabled on their lead permissions.

Supported Formats

json, csv

Params

Param name Description
category
Required

Group or pivot the report by one of these lead attributes.

  • Must be a value contained in the pick list:
    Acceptable ValueDescription
    statusStatus
    offer_idOffer
    schedule_idSchedule
    schedule_action_idSchedule Action
    buyer_converted_schedule_action_idThe schedule action where the lead converted.
    lead_import_idLead Import
    traffic_source_idTraffic Source
    outbound_calls_countOutbound Calls Count
    inbound_calls_countInbound Calls Count
    recent_call_disposition_idRecent Call Disposition
    buyer_converted_daysBuyer Converted Days
    buyer_idBuyer
    countryCountry
    call_center_idCall Center
    stateState
    sub_idSub ID
    dial_tierDial Tier
    contact_field_typeContact Field Type
    created_at_dayThe day the lead was submitted
    created_at_monthThe month the lead was submitted
    created_at_weekThe week the lead was submitted
    created_at_five_minutesThe minute the lead was submitted
    created_at_hourThe hour lead was submitted
    schedule_trigger_typeSchedule Trigger Type
    zip_postal_codeZip/Postal Code
    countryCountry
    state_provinceState/Province
    token_values_mapToken Values Map
pivot
Optional Blank value allowed

Group or pivot the report by one of these lead attributes.

  • Must be a value contained in the pick list:
    Acceptable ValueDescription
    statusStatus
    offer_idOffer
    schedule_idSchedule
    schedule_action_idSchedule Action
    buyer_converted_schedule_action_idThe schedule action where the lead converted.
    lead_import_idLead Import
    traffic_source_idTraffic Source
    outbound_calls_countOutbound Calls Count
    inbound_calls_countInbound Calls Count
    recent_call_disposition_idRecent Call Disposition
    buyer_converted_daysBuyer Converted Days
    buyer_idBuyer
    countryCountry
    call_center_idCall Center
    stateState
    sub_idSub ID
    dial_tierDial Tier
    contact_field_typeContact Field Type
    created_at_dayThe day the lead was submitted
    created_at_monthThe month the lead was submitted
    created_at_weekThe week the lead was submitted
    created_at_five_minutesThe minute the lead was submitted
    created_at_hourThe hour lead was submitted
    schedule_trigger_typeSchedule Trigger Type
    zip_postal_codeZip/Postal Code
    countryCountry
    state_provinceState/Province
    token_values_mapToken Values Map
page
Optional

Return the next page of results.

  • Must be a number.
per_page
Optional

How many results to return per page. The default is 25.

  • Must be a number.
created_at_to
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
created_at_from
Optional

Date formatted like 2016-01-01 12:25:15 -0500

  • Must be a String
fulltext
Optional

Search for any record that matches this text

  • Must be a String
time_zone
Optional

Date ranges will be parsed using this time zone.
columns
Optional 		Specify the columns you would like returned by the API for a given resource. Limiting the columns can significantly increase API response time since only the requested data will be processed. columns=uuid,number,created_at

Must be any combination of:

  • id
  • legacy_id
  • type
  • uuid
  • created_at
  • updated_at
  • deleted_at
  • user_updated_at
  • routes_show_path
  • routes_edit_path
  • external_record_id
  • context_menu_name
  • name
  • caller_id
  • email
  • full_name
  • contact_field_type
  • expires_in
  • country
  • state_province
  • zip_postal_code
  • time_zone
  • sub_id
  • offer_id
  • schedule_id
  • status
  • human_status
  • css_status
  • has_next_action
  • opt_out
  • revenue
  • payout
  • offer_converted
  • buyer_converted
  • traffic_source_id
  • buyer_id
  • lead_import_id
  • remote_ip
  • attempted_call_id
  • connected_call_id
  • scheduled_callback_id
  • call_buyer_conversion_id
  • call_offer_conversion_id
  • sms_number_id
  • dial_number_id
  • dial_tier
  • last_action_at
  • first_action_at
  • first_queued_at
  • schedule_ended_at
  • next_action_at
  • last_call_at
  • is_live
  • schedule_trigger_type
  • blocked
  • data

  • Must be a String
root
Optional

Pass root=false to return results without a root node and metadata.
For example:
GET /api/v1/calls?root=false will return [call1, call2, call3]
While:
GET /api/v1/calls will return {calls: [call1, call2, call3], metadata: {}}

  • Must be a boolean value: 1, true, yes, on, 0, false, no, off