POST /buyers

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

Create a buyer.

Creates a new buyer in your account from the submitted attributes, optionally copying settings from an existing buyer via copy_id and copy_another_buyer. After saving, Trackdrive computes derived fields such as tier, EPC, business hours, and cap status before returning the created record.

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
    buyerDefault response format.
    buyer_gridModern response format that returns various foreign keys for use with other API endpoints.
copy_another_buyer
Optional

Copy another buyer?

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

The id of the buyer you would like to copy.
user_buyer_id
Optional

Your external ID for this buyer.

  • Must be a String
number
Optional

The DID or SIP endpoint to call. DID must be prefixed with +{country code}. Example: to dial a number in the USA, enter +1 followed by the 10 digit DID number, in UK it would be +44 followed by the DID number. To transfer a call via SIP, begin the number with ‘sip:’.

  • Must be a String
name
Optional

The name for this buyer that will appear on menus and in logs.

  • Must be a String
timeout_seconds
Optional

Determines the time in seconds the call should ring. Must be at least 12 seconds. If the call is not answered within the ring timeout value or the default value of 120 s, it is canceled.

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

Play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. Your provider will dial the number, and when the automated system picks up, sends the DTMF tones to connect to the extension. E.g. If you want to dial the 2410 extension after the call is connected, and you want to wait for a few seconds before sending the extension, add a few leading ‘w’ characters. Each ‘w’ character waits 0.5 second before sending a digit. Each ‘W’ character waits 1 second before sending a digit.

  • Must be a String
dial_caller_name
Optional Blank value allowed

The caller name announced to this buyer when the call connects, with tokens replaced before it is sent.

  • Must be a String
delay_calling_buyer_seconds
Optional Blank value allowed

The number of seconds Trackdrive waits before dialing this buyer after a call is ready to transfer.

  • Must be a decimal number.
time_zone
Optional

Date ranges will be parsed using this time zone.
sip_username
Optional Blank value allowed

The SIP username used when dialing this buyer’s sip: endpoint.

  • Must be a String
sip_password
Optional Blank value allowed

The SIP password used when dialing this buyer’s sip: endpoint.

  • Must be a String
external_platform_id
Optional Blank value allowed

The known third-party platform this buyer’s number or SIP endpoint belongs to.

  • Must be an 8-bit integer ID or a 128-bit UUID reference to an object on Trackdrive. Example ID: 289302820, Example UUID: 924c37d5-e70f-42ad-84c2-e85eb0c1bc21
buyer_fleet_id
Optional Blank value allowed

The BuyerFleet this buyer is grouped under.
buyer_suppression_ids
Optional Blank value allowed

The list of internal suppression id’s that will be assigned to this buyer.
token_value_ids
Optional Blank value allowed

Callers will be routed to Buyers with matching tokens.
attribution_token_value_ids
Optional Blank value allowed

When this Buyer is connected to a Caller, the Call will be tagged with these tokens.
paused
Optional

Pause or unpause the buyer.

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

Enable or Disable call recordings for this Buyer.

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

Require a Trackdrive user logged into your company to have permission to download call recordings for calls transferred to this buyer.

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

After answering the call the Buyer must Press 1 before being connected to the Caller.
Trackdrive will use the “Press 1 To Accept” call routing from the current Offer.

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

Grant access to edit this Buyer, and view calls that it paid for.

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

The selected users will recieve an email invitation to collaborate on your company.

  • Must be an array of emails. EG: ["john-smith@gmail.com", "example@domain.com"]
team_offer_ids
Optional Blank value allowed

Team members can view calls made to these Offers that were paid for by their Buyer.

  • Must be a valid array of integers. Each integer ID must be a valid foreign key reference to an Offer. Refer to: /api/docs/1.0/offers
record_token_filter_list
Optional Blank value allowed

Assign filters to the object by passing an array of key:value pairs

  • Must be a valid list of filters. Example filters:
    "interest:auto", "loan_amount:>=10000", "loan_amount:<=50000", "geo:!=800", "caller_id:!=anonymous"
record_token_additional_list
Optional Blank value allowed

Assign additional tokens that will be applied to leads and calls by passing a comma separated string of key:value pairs.

  • Must be a valid list of tokens. Example tokens:
    buyer_interest:loan,another_token:value
route_by_type
Optional

Configure how calls will be routed to this Buyer. When routing by revenue the tier will be automatically calculated by taking the revenue for the current timeframe * -1.

  • Must be one of: tier, revenue, epc.
tier
Optional Blank value allowed

When routing by revenue the tier will not be used. Buyers with the lowest tier are considered first for calls (a tier may be negative if needed). For buyers with the same tier, the weight will then be used to calculate the % of calls the buyer gets within that tier.

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

The number of hours used when calculating the EPC. If there are less than Minimum Required Calls in this timeframe the Assumed EPC will be used instead.

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

The Assumed EPC will be used until the Buyer has received Minimum Required Calls calls during the EPC Timeframe.

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

The number of calls required during EPC Timeframe before the real EPC is used insead of the Assumed EPC.

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

The Weight of this buyer will be divided by the Total Weight of all buyers at this same Tier to get the % of calls this buyer will get within this Tier.

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

Ping this buyer before calling the lead back, used with off-hook webhook conversions.

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

When true, Trackdrive waits for this buyer’s webhook conversion ping to respond before pinging the next buyer, instead of pinging all webhook buyers at once.

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

The order this buyer is pinged in relative to other webhook buyers on the same offer. Lower numbers are pinged first.

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

Replace this buyer’s number with dynamic_number, with its tokens replaced, when dialing this buyer.

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

The token-replaced number or SIP address dialed instead of number when use_dynamic_number is true.

  • Must be a String
use_with_key_press_flows
Optional Blank value allowed

Apply a key press flow group to calls transferred to this buyer.

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

The key press flow group applied when use_with_key_press_flows is true.
record_voicemail_sound_playlist_id
Optional Blank value allowed

The sound playlist played to a caller when this buyer leaves them a voicemail.
display_caller_id_type
Optional

Select which Caller ID will be sent to this Buyer.

  • Must be one of: display_caller_id, display_fake_caller_id, display_trackdrive_number_id.
display_trackdrive_number_id
Optional Blank value allowed

The Trackdrive number to display when display_caller_id_type=display_trackdrive_number_id
concurrency_cap_limit
Optional Blank value allowed

Choose the number of concurrent calls that can be forwarded to this buyer simultaneously.

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

Convert When Downstream Converts

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

Attempt caps limit the number of times a buyer can be attempted in a given interval.

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

Monthly Attempt Cap

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

Daily Attempt Cap

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

Hourly Attempt Cap

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

Connection caps limit the number of times a buyer can be connected in a given interval.

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

Monthly Connection Cap

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

Daily Connection Cap

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

Hourly Connection Cap

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

Conversion caps limit the number of times a buyer can convert in a given interval.

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

Monthly Conversion Cap

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

Daily Conversion Cap

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

Hourly Conversion Cap

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

Revenue caps limit the dollar amount that can be paid by a buyer in a given interval.

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

Monthly $ Revenue Cap

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

Daily $ Revenue Cap

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

Hourly $ Revenue Cap

  • Must be a decimal number.
business_hours_schedule
Optional

Day is an integer representing the day of the week, 0..6, with Sunday == 0. [

{
  attempt_hourly_limit: 10,
  connection_hourly_limit: 10,
  buyer_conversion_hourly_limit: 10,
  revenue_hourly_limit: 10,
  schedule: [
    {
      day: 0,
      times: ["11:00..13:09", "14:00..15:09"]
    },
    {
      day: 1,
      times: ["11:10..18:39", "19:10..23:39"]
    }
  ]
}

]

  • Must be an array of any type
buyer_conversions_schedule
Optional

Day is an integer representing the day of the week, 0..6, with Sunday == 0. [

{
  buyer_conversions_attributes: [
    {
      name: '10$ conversion at 1 minute, deduped every 2 hours',
      duration: 60,
      revenue: 10,
      duplicate_timeframe: 7200
    }
  ],
  schedule: [{"day":0,"times":["00:00..23:59"]},{"day":1,"times":["00:00..23:59"]},{"day":2,"times":["00:00..23:59"]},{"day":3,"times":["00:00..23:59"]},{"day":4,"times":["00:00..23:59"]},{"day":5,"times":["00:00..23:59"]},{"day":6,"times":["00:00..23:59"]}]
}

]

  • Must be an array of any type
current_conversion_revenue_max
Optional

The maximum valid revenue for the current time frame.

  • Must be a decimal number.
current_conversion_revenue_min
Optional

The minimum valid revenue for the current time frame.

  • Must be a decimal number.
current_conversion_revenue_increment
Optional

Bids must be increased/decreased by this amount for the current time frame.

  • Must be a decimal number.
current_conversion_revenue
Optional

The number of dollars paid per call in increments of $0.01 for the current time frame.

  • Must be a decimal number.
current_conversion_duration
Optional

The number of seconds for a call to payout. If this is set to 0 the call will convert when this buyer is dialed for the current time frame.

  • Must be a decimal number.
current_conversion_duplicate_timeframe
Optional

The period of time that must elapse before a buyer will pay for the same caller to be transferred.

  • Must be a decimal number.
current_conversion_name
Optional

This name that will appear in call logs.

  • Must be a String
ping_timeout_seconds
Optional Blank value allowed

How many seconds Trackdrive waits for this buyer’s ping to respond. Reading returns the largest timeout across the buyer’s ping settings; writing applies the value to all of them. Call routing waits for every ping to resolve, so the slowest buyer sets the caller’s hold time.

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

Conversion will only occur if the caller matches these filters.

  • Must be a valid list of filters. Example filters:
    "interest:auto", "loan_amount:>=10000", "loan_amount:<=50000", "geo:!=800", "caller_id:!=anonymous"
current_conversion_attribution_token_values
Optional Blank value allowed

If the call converts, these tokens will be applied to the call.

  • Must be a valid list of tokens. Example tokens:
    buyer_interest:loan,another_token:value