Purchase a phone number

curl --request POST \ --url https://api.callingbox.io/v1/numbers/purchase \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "phone_number": "+14155551234" } '

{ "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "e164": "+15551234567", "friendly_name": "<string>", "country_code": "US", "number_type": "local", "status": "active", "monthly_cost_cents": 100, "purchased_at": "2023-11-07T05:31:56Z", "inbound_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "outbound_agent_ids": [ "3c90c3cc-0d44-4b50-8888-8dd25736052a" ] }

Authorizations

Authorization

string

header

default:sk_live_your_api_key

required

API key starting with sk_

Body

application/json

phone_number

string

required

Phone number to purchase in E.164 format

Example:

"+14155551234"

Response

Number purchased successfully

string<uuid>

Unique phone number identifier.

e164

string

Phone number in E.164 format.

Example:

"+15551234567"

friendly_name

string | null

Optional display label.

country_code

string

ISO country code.

Example:

"US"

number_type

string

Number type: local or toll_free.

Example:

"local"

status

string

Number status.

Example:

"active"

monthly_cost_cents

integer

Monthly cost in cents.

Example:

100

purchased_at

string<date-time>

When the number was purchased.

inbound_agent_id

string<uuid> | null

The inbound agent (if any) that answers calls to this number. At most one per number.

outbound_agent_ids

string<uuid>[]

Outbound agents that may use this number as a caller ID.