API documentation

GET /phone_numbers

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers

List your phone numbers

List the phone numbers rented in your account, with filters, or request the CSV format for bulk export. Administrators can pass all_companies to list numbers across every company.

Supported Formats

json, csv

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 Value Description
number Default response format.
number_grid Modern response format that returns various foreign keys for use with other API endpoints.

number
Optional

The phone number.

Must be a String

offer_id
Optional

Refer to the offer api for details

Must be a decimal number.

traffic_source_id
Optional

Refer to the traffic source api for details

Must be a decimal number.

provider_configuration_id
Optional

Refer to the provider api for details

Must be a decimal number.

ring_pool_id
Optional

Refer to the Number Pool api for details

Must be a decimal number.

last_call_at_to
Optional

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

Must be a String

last_call_at_from
Optional

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

Must be a String

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.

Must be a valid time zone. See the list of valid time zones.

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
name
number
offer_id
traffic_source_id
provider_configuration_id
description
ring_pool_id
provider_auth_key
last_call_at
token_values
country
area_code_id
optimizer_displayed_at
optimizer_tokens_changed_at
plain_number
extension
checksum
human_number

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

Example Request

curl 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/?per_page=2' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY'

Example Response 200

{
  "status": 200,
  "success": true,
  "numbers": [
    {
      "id": 10001,
      "type": "Number",
      "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
      "created_at": "2026-01-15T15:30:00.000Z",
      "updated_at": "2026-01-15T15:30:00.000Z",
      "deleted_at": null,
      "user_updated_at": "2026-01-15T15:30:00.000Z",
      "routes_show_path": "/numbers/10001",
      "routes_edit_path": "/numbers/10001/edit",
      "external_record_id": "example-inbound-webhook-ping",
      "name": "+18445550150",
      "number": "+18445550150",
      "offer_id": 10002,
      "traffic_source_id": null,
      "provider_configuration_id": 10003,
      "description": "Tracking number the API docs example ping forwards to",
      "ring_pool_id": null,
      "provider_auth_key": null,
      "last_call_at": null,
      "token_values": [],
      "country": "US",
      "area_code_id": null,
      "optimizer_displayed_at": null,
      "optimizer_tokens_changed_at": null,
      "plain_number": "+18445550150",
      "extension": null,
      "checksum": "a0d49c48545bcaaf801ee2f44f8f73cb",
      "human_number": "(844) 555-0150"
    },
    {
      "id": 10004,
      "type": "Number",
      "uuid": "a09e6bca-255b-4217-af73-cb9601c80217",
      "created_at": "2026-01-15T15:30:00.000Z",
      "updated_at": "2026-01-15T15:30:00.000Z",
      "deleted_at": null,
      "user_updated_at": "2026-01-15T15:30:00.000Z",
      "routes_show_path": "/numbers/10004",
      "routes_edit_path": "/numbers/10004/edit",
      "external_record_id": "api_docs_example",
      "name": "+13235550142",
      "number": "+13235550142",
      "offer_id": 10005,
      "traffic_source_id": null,
      "provider_configuration_id": 10003,
      "description": "API docs example number",
      "ring_pool_id": null,
      "provider_auth_key": null,
      "last_call_at": null,
      "token_values": [],
      "country": "US",
      "area_code_id": null,
      "optimizer_displayed_at": null,
      "optimizer_tokens_changed_at": null,
      "plain_number": "+13235550142",
      "extension": null,
      "checksum": "da771aa599dbc6c51522eb587e723f15",
      "human_number": "+13235550142"
    }
  ],
  "metadata": {
    "root": "numbers",
    "page": 1,
    "total_pages": 7,
    "per_page": 2,
    "total_count": 14,
    "next_cursor": 10006
  }
}

POST /phone_numbers

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers

Purchase a phone number

Purchase a new phone number using one of your existing provider configurations.

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 Value Description
number Default response format.
number_grid Modern response format that returns various foreign keys for use with other API endpoints.

forward_type
Optional Blank value allowed

Forward Type - Should the number forward to an Offer or a Buyer

Must be a value contained in the pick list:

Acceptable Value Description
offer_id Forward to Offer
buyer_id Forward to Buyer

buyer_id
Optional Blank value allowed

The buyer calls forward to when forward_type is buyer_id. Required with that forward type. If the buyer does not answer, the exception handling of your account’s direct forward offer applies.

Must be a valid foreign key reference to an Buyer. Refer to: /api/docs/1.0/buyers

provider_configuration_id
Required

Refer to the provider api for details

Must be a valid foreign key reference to an Provider. Refer to: /api/docs/1.0/provider_configurations

offer_id
Required

Refer to the offer api for details

Must be a valid foreign key reference to an Offer. Refer to: /api/docs/1.0/offers

toll_free
Required

Purchase a toll-free or local number? true for toll-free, false for local number.

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

country
Required

The country where the number will be purchased.

Must be one of: AU, CA, GB, US.

requested_number
Optional Blank value allowed

The phone number you wish to purchase from /api/v1/phone_numbers/search

Must be a String

traffic_source_id
Optional Blank value allowed

Refer to the traffic source api for details

Must be a valid foreign key reference to an Traffic Source. Refer to: /api/docs/1.0/traffic_sources

ring_pool_id
Optional Blank value allowed

Refer to the Number Pool api for details

Must be a valid foreign key reference to an Number Pool. Refer to: /api/docs/1.0/ring_pools

traffic_source_override_lead_traffic_source
Optional Blank value allowed

Force Calls to Credit This Traffic Source and Extra Tokens, even if Lead Traffic Source or Data is Different

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

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

Example Request

curl -X POST 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider_configuration_id": 10003,
  "offer_id": 10002,
  "toll_free": false,
  "country": "US",
  "requested_number": "+14154151864"
}'

Example Response 200

{
  "status": 200,
  "success": true,
  "errors": {},
  "number": {
    "id": 10006,
    "type": "Number",
    "uuid": "b2b930c0-49a2-4b23-9c94-6d1e2a2f9d61",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": "2026-01-15T15:30:00.000Z",
    "routes_show_path": "/numbers/10006",
    "routes_edit_path": "/numbers/10006/edit",
    "external_record_id": null,
    "name": "+14154151864",
    "number": "+14154151864",
    "offer_id": 10002,
    "traffic_source_id": null,
    "provider_configuration_id": 10003,
    "description": null,
    "ring_pool_id": null,
    "provider_auth_key": null,
    "last_call_at": null,
    "token_values": [],
    "country": "US",
    "area_code_id": null,
    "optimizer_displayed_at": null,
    "optimizer_tokens_changed_at": null,
    "plain_number": "+14154151864",
    "extension": null,
    "checksum": "3f9c1a9d6e2b4c9f8a1d7e5b0c3a2f6d",
    "human_number": "(415) 415-1864"
  },
  "metadata": {
    "root": "number"
  }
}

GET /phone_numbers/:id

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/:id

Show the details of phone number

Get the full configuration details of a single phone number. The id can be either the internal Trackdrive id or the full phone number prefixed with '+'.

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 Value Description
number Default response format.
number_grid Modern response format that returns various foreign keys for use with other API endpoints.

id
Optional

This can be either the internal trackdrive id or the full phone number beginning with ‘+’
For example:
To find a number using trackdrive’s internal id pass id=185923
To find a number using the phone number pass id=+18005002562"

Must be a String

Example Request

curl 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/10001' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY'

Example Response 200

{
  "status": 200,
  "success": true,
  "errors": {},
  "number": {
    "id": 10002,
    "type": "Number",
    "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": "2026-01-15T15:30:00.000Z",
    "routes_show_path": "/numbers/10002",
    "routes_edit_path": "/numbers/10002/edit",
    "external_record_id": "example-inbound-webhook-ping",
    "name": "+18445550150",
    "number": "+18445550150",
    "offer_id": 10003,
    "traffic_source_id": null,
    "provider_configuration_id": 10004,
    "description": "Tracking number the API docs example ping forwards to",
    "ring_pool_id": null,
    "provider_auth_key": null,
    "last_call_at": null,
    "token_values": [],
    "country": "US",
    "area_code_id": null,
    "optimizer_displayed_at": null,
    "optimizer_tokens_changed_at": null,
    "plain_number": "+18445550150",
    "extension": null,
    "checksum": "a0d49c48545bcaaf801ee2f44f8f73cb",
    "human_number": "(844) 555-0150"
  },
  "metadata": {
    "root": "number"
  }
}

PUT /phone_numbers/:id

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/:id

Update a phone number's source or pool

Update a phone number's assigned traffic source, offer, buyer, or number pool, and other routing settings. Trackdrive Clean Phone Numbers (TDPN) cannot be edited through this endpoint.

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 Value Description
number Default response format.
number_grid Modern response format that returns various foreign keys for use with other API endpoints.

id
Optional

Must be a String

description
Optional Blank value allowed

A note that identifies the number in your account.

Must be a String

forward_type
Optional Blank value allowed

Forward Type - Should the number forward to an Offer or a Buyer

Must be a value contained in the pick list:

Acceptable Value Description
offer_id Forward to Offer
buyer_id Forward to Buyer

buyer_id
Optional Blank value allowed

The buyer calls forward to when forward_type is buyer_id. Required with that forward type. If the buyer does not answer, the exception handling of your account’s direct forward offer applies.

Must be a valid foreign key reference to an Buyer. Refer to: /api/docs/1.0/buyers

offer_id
Optional Blank value allowed

Refer to the offer api for details

Must be a valid foreign key reference to an Offer. Refer to: /api/docs/1.0/offers

traffic_source_id
Optional Blank value allowed

Refer to the traffic source api for details

Must be a valid foreign key reference to an Traffic Source. Refer to: /api/docs/1.0/traffic_sources

ring_pool_id
Optional Blank value allowed

Refer to the Number Pool api for details

Must be a valid foreign key reference to an Number Pool. Refer to: /api/docs/1.0/ring_pools

traffic_source_override_lead_traffic_source
Optional Blank value allowed

Force Calls to Credit This Traffic Source and Extra Tokens, even if Lead Traffic Source or Data is Different

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

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

paused
Optional

Pause or unpause.

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

use_with_key_press_flows
Optional Blank value allowed

Apply a key press flow group to calls on this number.

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.

Must be a valid foreign key reference to an Key Press Flow Group. Refer to: /api/docs/1.0/key_press_flow_groups

lead_match_sort_order
Optional Blank value allowed

Which leads to search first when matching an inbound caller to an existing lead.

Must be a value contained in the pick list:

Acceptable Value	Description
schedule_leads_first	[Default] Search for a matching schedule lead before considering offer leads.
offer_leads_first	Search for a matching offer lead before considering schedule leads.

delete_prevention
Optional Blank value allowed

When true, the number cannot be deleted until deletion prevention is turned off.

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

Example Request

curl -X PUT 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/10001' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "paused": true
}'

Example Response 200

{
  "status": 200,
  "success": true,
  "errors": {},
  "number": {
    "id": 10002,
    "type": "Number",
    "uuid": "a6af7847-1b1e-4760-ac0d-e1813a6d3a09",
    "created_at": "2026-01-15T14:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": null,
    "user_updated_at": "2026-01-15T15:30:00.000Z",
    "routes_show_path": "/numbers/10002",
    "routes_edit_path": "/numbers/10002/edit",
    "external_record_id": "example-inbound-webhook-ping",
    "name": "+18445550150",
    "number": "+18445550150",
    "offer_id": 10003,
    "traffic_source_id": null,
    "provider_configuration_id": 10004,
    "description": "Tracking number the API docs example ping forwards to",
    "ring_pool_id": null,
    "provider_auth_key": null,
    "last_call_at": null,
    "token_values": [],
    "country": "US",
    "area_code_id": null,
    "optimizer_displayed_at": null,
    "optimizer_tokens_changed_at": null,
    "plain_number": "+18445550150",
    "extension": null,
    "checksum": "a0d49c48545bcaaf801ee2f44f8f73cb",
    "human_number": "(844) 555-0150"
  },
  "metadata": {
    "root": "number"
  }
}

DELETE /phone_numbers/:id

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/:id

Unrent a phone number.

Release (unrent) a phone number from your account, stopping any further billing for it. This fails if the number is still in use somewhere that prevents deletion.

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 Value Description
number Default response format.
number_grid Modern response format that returns various foreign keys for use with other API endpoints.

id
Optional

Must be a String

Example Request

curl -X DELETE 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/10001' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY'

Example Response 200

{
  "status": 200,
  "success": true,
  "errors": {},
  "number": {
    "id": 10001,
    "type": "Number",
    "uuid": "a0d49c48-1b1e-4760-ac0d-da771aa599db",
    "created_at": "2026-01-15T15:30:00.000Z",
    "updated_at": "2026-01-15T15:30:00.000Z",
    "deleted_at": "2026-09-23 17:52:49 UTC",
    "user_updated_at": "2026-01-15T15:30:00.000Z",
    "routes_show_path": "/numbers/10001",
    "routes_edit_path": "/numbers/10001/edit",
    "external_record_id": "example-record-1",
    "name": "+13235550142",
    "number": "+13235550142",
    "offer_id": 10002,
    "traffic_source_id": null,
    "provider_configuration_id": 10003,
    "description": "API docs example number",
    "ring_pool_id": null,
    "provider_auth_key": null,
    "last_call_at": null,
    "token_values": [],
    "country": "US",
    "area_code_id": null,
    "optimizer_displayed_at": null,
    "optimizer_tokens_changed_at": null,
    "plain_number": "+13235550142",
    "extension": null,
    "checksum": "2bc98663bb1e98feb2e7124e8ce479a7",
    "human_number": "(323) 555-0142"
  },
  "metadata": {
    "root": "number"
  }
}

GET /phone_numbers/search

Authorization Required

https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/search

Search available phone numbers for purchase

Returns a list of available phone numbers for sale. Can be used with POST /api/v1/phone_numbers?requested_number= to purchase a number.

Params

Param name	Description
country Optional	Two-letter country code (default: US) Must be a String
toll_free Optional	Whether to search toll-free numbers Must be one of: `true`, `false`.
prefix Optional	Restrict by area code (NPA). Example: 415, 209, 719 Must be a String
query Optional	Full or partial phone number to match Must be a String

Example Request

curl 'https://[your-subdomain].trackdrive.com/api/v1/phone_numbers/search?prefix=415&toll_free=false' \
  -H 'Authorization: Basic BASE64_ENCODED_PUBLIC_KEY_AND_PRIVATE_KEY'

Example Response 200

{
  "status": 200,
  "success": true,
  "phone_number_search_results": [
    {
      "id": "+14154151864",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14154151864",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14154471210",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14154471210",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14155297950",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14155297950",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14155868810",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14155868810",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14156952675",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14156952675",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14156978735",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14156978735",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14158677640",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14158677640",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14158817332",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14158817332",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14159259977",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14159259977",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    },
    {
      "id": "+14159415711",
      "type": "PhoneNumberSearchResult",
      "phone_number": "+14159415711",
      "country": "US",
      "toll_free": false,
      "prefix": "415"
    }
  ],
  "metadata": {
    "root": "phone_number_search_results",
    "page": 1,
    "total_pages": 0,
    "per_page": 25,
    "total_count": 10,
    "next_cursor": 0.0
  }
}