Buyer Groups

The Buyer Groups in your account.

GET /buyer_groups

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

List Buyer Group records.

Lists Buyer Groups, which bundle buyers together for simultaneous or sequential dialing with shared caps and tier/weight-based prioritization. Supports CSV export (requires the export permission) and returns each group's current concurrency usage.

Supported Formats

json, csv

Params

Param name Description
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
  • concurrency_cap_limit
  • concurrency_cap_used
  • buyer_ids
  • buyers_count
  • company_id
  • name
  • maxed_out
  • weight
  • tier
  • time_zone
  • paused
  • paused_at
  • paused_by_user_id
  • unpaused_at
  • dial_buyers_type
  • attempt_daily_used
  • attempt_hourly_used
  • attempt_monthly_used
  • attempt_total_used
  • buyer_conversion_daily_used
  • buyer_conversion_hourly_used
  • buyer_conversion_monthly_used
  • buyer_conversion_total_used
  • connection_daily_used
  • connection_hourly_used
  • connection_monthly_used
  • connection_total_used
  • earned_revenue_daily_used
  • earned_revenue_hourly_used
  • earned_revenue_monthly_used
  • earned_revenue_total_used
  • revenue_daily_used
  • revenue_hourly_used
  • revenue_monthly_used
  • revenue_total_used
  • attempt_daily_limit
  • attempt_hourly_limit
  • attempt_monthly_limit
  • attempt_total_limit
  • buyer_conversion_daily_limit
  • buyer_conversion_hourly_limit
  • buyer_conversion_monthly_limit
  • buyer_conversion_total_limit
  • connection_daily_limit
  • connection_hourly_limit
  • connection_monthly_limit
  • connection_total_limit
  • earned_revenue_daily_limit
  • earned_revenue_hourly_limit
  • earned_revenue_monthly_limit
  • earned_revenue_total_limit
  • revenue_daily_limit
  • revenue_hourly_limit
  • revenue_monthly_limit
  • revenue_total_limit

  • 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
order
Optional

Sort results by this field.

  • Must be one of: name, maxed_out, weight, tier, cap_reset_at, time_zone, created_at, updated_at, paused, paused_at, paused_by_user_id, unpaused_at, user_updated_at, dial_buyers_type, call_limits.in_progress_count, call_limits.in_progress_used, call_limits.revenue_hourly_used, call_limits.revenue_daily_used, call_limits.revenue_monthly_used, call_limits.revenue_total_used, call_limits.earned_revenue_hourly_used, call_limits.earned_revenue_daily_used, call_limits.earned_revenue_monthly_used, call_limits.earned_revenue_total_used, call_limits.buyer_conversion_hourly_used, call_limits.buyer_conversion_daily_used, call_limits.buyer_conversion_monthly_used, call_limits.buyer_conversion_total_used, call_limits.connection_hourly_used, call_limits.connection_daily_used, call_limits.connection_monthly_used, call_limits.connection_total_used, call_limits.attempt_hourly_used, call_limits.attempt_daily_used, call_limits.attempt_monthly_used, call_limits.attempt_total_used.
order_dir
Optional

Sort results in ascending or descending order.

  • Must be one of: desc, asc.

GET /buyer_groups/:id

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

Get an individual Buyer Group by id

Gets a Buyer Group's details by id, including its concurrency, cap usage, and dial_buyers_type configuration.

POST /buyer_groups

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

Create Buyer Group.

Creates a Buyer Group, optionally attaching buyers via buyer_ids, setting tier and weight for simultaneous-dial prioritization, configuring attempt/connection/conversion/revenue caps, and optionally auto-generating a team that can manage the group and view its calls; team_users_emails receive an email invitation.

Params

Param name Description
name
Required

The name of the buyer group.

  • Must be a String
paused
Optional

Pause or unpause.

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

Send true to reset the total caps on this buyer group.

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

Configure the dial buyer behaviour.
sequentially will dial one buyer a time.
simultaneously will dial all buyers in the group at the same time.

  • Must be one of: sequentially, simultaneously.
buyer_ids
Optional Blank value allowed

The list of buyer ids that will be dialed.
Example: [100123, 100124, 1000125] Obtain internal buyer IDs by making a request to /api/v1/buyers?columns=name,id,user_buyer_id

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

Append buyers to this record.
For example pass: [100123,100124] in order to append 100123, and 100124 to the list of buyers in the record.
<strong>This is useful when making parallel PUT requests with different add_buyer_ids or remove_buyer_ids values. These add/remove assignments are thread safe.</strong>

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

Remove buyers from the record.
For example pass: [100123] in order to delete 100123 from the list of buyers in the record.

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

Append buyers to the record using the buyer field user_buyer_id
For example pass: ["loan-22-en", "loan-23-fr"]

  • Must be an array of strings. EG: ["abc123", "xzy023"]
remove_user_buyer_ids
Optional Blank value allowed

Remove buyers from the record using buyer field user_buyer_id
For example pass: ["loan-23-fr"]

  • Must be an array of strings. EG: ["abc123", "xzy023"]
tier
Optional

When dial_buyers_type is set to simultaneously, the buyer group will become prioritized by tier and weight.
Buyers and Buyer Groups with the lowest tier are considered first for calls (a tier may be negative if needed).
For buyers/buyer groups with the same tier, the weight will then be used to calculate the % of calls the buyer/buyer group gets within that tier.

  • Must be a decimal number.
weight
Optional

When dial_buyers_type is set to simultaneously, the buyer group will become prioritized by tier and weight.
The Weight of this buyer group will be divided by the Total Weight of all buyers/buyer groups at this same Tier to get the % of calls this buyer/buyer group will get within this Tier.

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

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

The maximum number of simultaneous calls this buyer group can receive.

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

Your own identifier for this buyer group, used to correlate it with a record in an external system.

  • Must be a String
generate_team
Optional

Grant access to manage this buyer group, it’s buyers, and to view calls that it’s 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 the buyers in this group.

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

The selected teams will be granted access to the buyers in this group.

  • Must be an array of decimal values. EG: [0, 1, 2, 3]
grant_team_offer_id
Optional Blank value allowed

Give this Buyer Group’s teams access to this Offer.
revoke_team_offer_id
Optional Blank value allowed

Remove access to this Offer for this Buyer Group’s teams.
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.

PUT /buyer_groups/:id

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

Update an individual Buyer Group

Updates a Buyer Group's settings, caps, tier, weight, or pause state, and its buyer membership via add_buyer_ids/remove_buyer_ids or add_user_buyer_ids/remove_user_buyer_ids. Pass reset_total_caps as true to reset the group's accumulated total caps.

Params

Param name Description
paused
Optional

Pause or unpause.

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

The name of the buyer group.

  • Must be a String
reset_total_caps
Optional

Send true to reset the total caps on this buyer group.

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

Configure the dial buyer behaviour.
sequentially will dial one buyer a time.
simultaneously will dial all buyers in the group at the same time.

  • Must be one of: sequentially, simultaneously.
add_buyer_ids
Optional Blank value allowed

Append buyers to this record.
For example pass: [100123,100124] in order to append 100123, and 100124 to the list of buyers in the record.
<strong>This is useful when making parallel PUT requests with different add_buyer_ids or remove_buyer_ids values. These add/remove assignments are thread safe.</strong>

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

Remove buyers from the record.
For example pass: [100123] in order to delete 100123 from the list of buyers in the record.

  • Must be a valid array of integers. Each integer ID must be a valid foreign key reference to an Buyer. Refer to: /api/docs/1.0/buyers
add_user_buyer_ids
Optional

Append buyers to the record using the buyer field user_buyer_id
For example pass: ["loan-22-en", "loan-23-fr"]

  • Must be an array of strings. EG: ["abc123", "xzy023"]
remove_user_buyer_ids
Optional

Remove buyers from the record using buyer field user_buyer_id
For example pass: ["loan-23-fr"]

  • Must be an array of strings. EG: ["abc123", "xzy023"]
buyer_ids
Optional Blank value allowed

The list of buyer ids that will be dialed.
Example: [100123, 100124, 1000125] Obtain internal buyer IDs by making a request to /api/v1/buyers?columns=name,id,user_buyer_id

  • Must be a valid array of integers. Each integer ID must be a valid foreign key reference to an Buyer. Refer to: /api/docs/1.0/buyers
tier
Optional

When dial_buyers_type is set to simultaneously, the buyer group will become prioritized by tier and weight.
Buyers and Buyer Groups with the lowest tier are considered first for calls (a tier may be negative if needed).
For buyers/buyer groups with the same tier, the weight will then be used to calculate the % of calls the buyer/buyer group gets within that tier.

  • Must be a decimal number.
weight
Optional

When dial_buyers_type is set to simultaneously, the buyer group will become prioritized by tier and weight.
The Weight of this buyer group will be divided by the Total Weight of all buyers/buyer groups at this same Tier to get the % of calls this buyer/buyer group will get within this Tier.

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

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

The maximum number of simultaneous calls this buyer group can receive.

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

Your own identifier for this buyer group, used to correlate it with a record in an external system.

  • Must be a String
generate_team
Optional

Grant access to manage this buyer group, it’s buyers, and to view calls that it’s 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 the buyers in this group.

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

The selected teams will be granted access to the buyers in this group.

  • Must be an array of decimal values. EG: [0, 1, 2, 3]
grant_team_offer_id
Optional Blank value allowed

Give this Buyer Group’s teams access to this Offer.
revoke_team_offer_id
Optional Blank value allowed

Remove access to this Offer for this Buyer Group’s teams.
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.

DELETE /buyer_groups/:id

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

Destroy an individual Buyer Group.

Deletes a Buyer Group by id.