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 03:20:28 +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 03:20:28 +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.