POST /api/v1/leads/create_or_update
Create a new lead if no active lead exists on the offer, or update the existing active lead.

Examples

# Create or update a lead by offer scope:
curl -H "Content-Type: application/json" -X POST -d '{"caller_id":"+18004506787","data":{"loan_amount":"501"}}' "https://trackdrive.com/api/v1/leads/create_or_update?lead_token=yourtoken"

Params

Param name
Description
Validations
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.

Validations:

  • 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.

Validations:

  • 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.

Validations:

  • 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.

Validations:

  • 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

Validations:

  • Must be a valid time: 2026-03-18 19:39:33 +0000
schedule_callback_in_seconds
Optional

Schedule a callback with the submitted lead in X seconds. Must be a valid integer EG: 3600

Validations:

  • 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)

Validations:

  • 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?

Validations:

  • Must be one of: calls.
assign_trackdrive_number
Optional

Assign a dialing number and return it in the API response as trackdrive_number_plain

Validations:

  • 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

Validations:

  • 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.

Validations:

  • Must be a decimal number.
restart_schedule
Optional

Restart the schedule for the lead from the beginning.

Validations:

  • 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.

Validations:

  • 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.

Validations:

  • Must be a valid time: 2026-03-18 19:39:33 +0000
hours_to_expire
Optional

Expire the lead after this many hours. The lead will exit schedule and perform end of schedule actions.

Validations:

  • 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.

Validations:

  • 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}}”

Validations:

  • Must be a Hash