Skip to content

Get a phone number

GET
/v1/numbers/{number}
curl --request GET \
--url https://api.caller9.app/v1/numbers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
--header 'Authorization: Bearer <token>'

Returns a number together with its current routing. A number is routed to exactly one of: a studio (assignments), a direct forward (forward), or a SIP trunk (trunk) — or none of them.

number
required
string format: uuid

Phone number ID (UUID), not the phone number itself.

The number and its routing.

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
assignments
required

Studio assignment (at most one entry in practice).

Array<object>
object
studio_guid
required
string
role
required
string
Allowed values: primary hotline
created_at
required
string format: date-time
forward
required

Direct forward destination, or null if the number is not forwarded.

One of:

A direct, unconditional forward destination for a number. Exactly one of sip_address / phone_number is set, matching dest_type.

object
number_guid

Present on the PUT response; omitted when embedded in GET /v1/numbers/{number}.

string
dest_type
required
string
Allowed values: sip phone
sip_address
required

Normalized SIP URI (sip:user@host).

string | null
phone_number
required

E.164 phone number.

string | null
created_at
required
string format: date-time
updated_at
required
string format: date-time
trunk
required

The SIP trunk the number is routed to, or null.

One of:
object
trunk_guid
required
string
name
required

Trunk name.

string

Example

{
"number": {
"hd_voice_outbound": 0
},
"assignments": [
{
"role": "primary"
}
],
"forward": {
"dest_type": "sip"
}
}

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

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

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.