Skip to content

Add a phone number

POST
/v1/organizations/{org}/numbers
curl --request POST \
--url https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "number": "+15551234567", "name": "example" }'

Adds a phone number record to the organization. The number is not routed anywhere until it is assigned to a studio, forwarded, or routed to a SIP trunk. Not available on the Demo plan; the Basic plan allows one number (409 plan_limit with limit: numbers). Requires a full-access key.

org
required
string format: uuid

Organization ID (UUID). Must be the organization that owns the API key.

Media typeapplication/json
object
number
required

The phone number, in E.164 format (e.g. +15551234567). Stored as given; the format is not validated.

string
<= 20 characters

Example

+15551234567
name

Display name. Defaults to the number itself.

string
<= 255 characters

The created number.

Media typeapplication/json
object
number
required

A phone number (DID) owned by an organization.

object
guid
required

Number ID.

string
number
required

The phone number, E.164 (e.g. +15551234567).

string
organization_guid
required
string
name
required

Display name.

string
hd_voice_outbound
required

1 if outbound calls from this number offer HD-voice codecs. Managed by Caller 9 support.

integer
Allowed values: 0 1
created_at
required
string format: date-time
updated_at
required
string format: date-time
deleted_at
required

Always null for numbers returned by the API.

string | null format: date-time

Example

{
"number": {
"hd_voice_outbound": 0
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Blocked by the organization’s plan.

Media typeapplication/json
object
error
required
string
Allowed value: plan_limit
limit
required

Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.

string
message
required
string

Example

{
"error": "plan_limit"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.