API documentation

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"
  }
}