Add a phone number
const url = 'https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/numbers';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"number":"+15551234567","name":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization ID (UUID). Must be the organization that owns the API key.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The phone number, in E.164 format (e.g. +15551234567). Stored as given; the format is not validated.
Example
+15551234567Display name. Defaults to the number itself.
Responses
Section titled “Responses”The created number.
object
A phone number (DID) owned by an organization.
object
Number ID.
The phone number, E.164 (e.g. +15551234567).
Display name.
1 if outbound calls from this number offer HD-voice codecs. Managed by Caller 9 support.
Always null for numbers returned by the API.
Example
{ "number": { "hd_voice_outbound": 0 }}The request was invalid.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Missing, invalid, expired or revoked API key.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}The key isn’t allowed to do this (e.g. a read-only key making a change).
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Not found, or belongs to another organization.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Blocked by the organization’s plan.
object
Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.
Example
{ "error": "plan_limit"}Too many requests for this API key. Retry after Retry-After seconds.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Headers
Section titled “Headers”Seconds until the rate-limit window resets.