Get Phone Number

Authorizations

Authorization

string

header

required

Retrieve your API Key from Dashboard.

Path Parameters

string

required

Response

200 - application/json

ByoPhoneNumber
TwilioPhoneNumber
VonagePhoneNumber
cozmoxPhoneNumber
TelnyxPhoneNumber

provider

enum<string>

required

This is to bring your own phone numbers from your own SIP trunks or Carriers.

Available options:

byo-phone-number

string

required

This is the unique identifier for the phone number.

orgId

string

required

This is the unique identifier for the org that this phone number belongs to.

createdAt

string<date-time>

required

This is the ISO 8601 date-time string of when the phone number was created.

updatedAt

string<date-time>

required

This is the ISO 8601 date-time string of when the phone number was last updated.

credentialId

string

required

This is the credential of your own SIP trunk or Carrier (type byo-sip-trunk) which can be used to make calls to this phone number.

You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.

fallbackDestination

NumberTransferDestination · object

This is the fallback destination an inbound call will be transferred to if:

assistantId is not set
squadId is not set
and, assistant-request message to the serverUrl fails

If this is not set and above conditions are met, the inbound call is hung up with an error message.

NumberTransferDestination
SipTransferDestination

Show child attributes

fallbackDestination.type

enum<string>

required

Available options:

number

fallbackDestination.number

string

required

This is the phone number to transfer the call to.

Required string length: 3 - 40

fallbackDestination.message

This is spoken to the customer before connecting them to the destination.

Usage:

If this is not provided and transfer tool messages is not provided, default is "Transferring the call now".
If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message for the destination assistant.

This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the contents field.

fallbackDestination.numberE164CheckEnabled

boolean

default:true

This is the flag to toggle the E164 check for the number field. This is an advanced property which should be used if you know your use case requires it.

Use cases:

false: To allow non-E164 numbers like +001234567890, 1234, or abc. This is useful for dialing out to non-E164 numbers on your SIP trunks.
true (default): To allow only E164 numbers like +14155551234. This is standard for PSTN calls.

If false, the number is still required to only contain alphanumeric characters (regex: /^\+?[a-zA-Z0-9]+$/).

@default true (E164 check is enabled)

fallbackDestination.extension

string

This is the extension to dial after transferring the call to the number.

Required string length: 1 - 10

fallbackDestination.callerId

string

This is the caller ID to use when transferring the call to the number.

Usage:

If not provided, the caller ID will be the number the call is coming from. Example, +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller.
To change this behavior, provide a callerId.
Set to '{{customer.number}}' to always use the customer's number as the caller ID.
Set to '{{phoneNumber.number}}' to always use the phone number of the assistant as the caller ID.
Set to any E164 number to always use that number as the caller ID. This needs to be a number that is owned or verified by your Transport provider like Twilio.

For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid

Maximum string length: 40

fallbackDestination.transferPlan

object

This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to blind-transfer.

@default transferPlan.mode='blind-transfer'

Show child attributes

fallbackDestination.transferPlan.mode

enum<string>

required

This configures how transfer is executed and the experience of the destination party receiving the call.

Usage:

blind-transfer: The assistant forwards the call to the destination without any message or summary.
blind-transfer-add-summary-to-sip-header: The assistant forwards the call to the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.
warm-transfer-say-message: The assistant dials the destination, delivers the message to the destination party, connects the customer, and leaves the call.
warm-transfer-say-summary: The assistant dials the destination, provides a summary of the call to the destination party, connects the customer, and leaves the call.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-message: The assistant dials the destination, waits for the operator to speak, delivers the message to the destination party, and then connects the customer.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary: The assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.
warm-transfer-twiml: The assistant dials the destination, executes the twiml instructions on the destination call leg, connects the customer, and leaves the call.
warm-transfer-experimental: The assistant puts the customer on hold, dials the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the fallbackMessage to the customer and optionally ends the call.

@default 'blind-transfer'

Available options:

blind-transfer,

blind-transfer-add-summary-to-sip-header,

warm-transfer-say-message,

warm-transfer-say-summary,

warm-transfer-twiml,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-message,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary,

warm-transfer-experimental

fallbackDestination.transferPlan.message

This is the message the assistant will deliver to the destination party before connecting the customer.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header, warm-transfer-say-message, warm-transfer-wait-for-operator-to-speak-first-and-then-say-message, or warm-transfer-experimental.

fallbackDestination.transferPlan.timeout

number

default:60

This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary

@default 60

Required range: 1 <= x <= 600

fallbackDestination.transferPlan.sipVerb

object

This specifies the SIP verb to use while transferring the call.

'refer': Uses SIP REFER to transfer the call (default)
'bye': Ends current call with SIP BYE
'dial': Uses SIP DIAL to transfer the call

fallbackDestination.transferPlan.holdAudioUrl

string

This is the URL to an audio file played while the customer is on hold during transfer.

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the customer.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.
If not provided, the default hold audio will be used.

fallbackDestination.transferPlan.transferCompleteAudioUrl

string

This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like 'beep' to notify that the transfer is complete.

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the destination party.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.

fallbackDestination.transferPlan.twiml

string

This is the TwiML instructions to execute on the destination call leg before connecting the customer.

Usage:

Used only when mode is warm-transfer-twiml.
Supports only Play, Say, Gather, Hangup and Pause verbs.
Maximum length is 4096 characters.

Example:

<Say voice="alice" language="en-US">Hello, transferring a customer to you.</Say>
<Pause length="2"/>
<Say>They called about billing questions.</Say>

Maximum string length: 4096

fallbackDestination.transferPlan.summaryPlan

object

This is the plan for generating a summary of the call to present to the destination party.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header or warm-transfer-say-summary or warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary or warm-transfer-experimental.

Show child attributes

fallbackDestination.transferPlan.summaryPlan.messages

object[]

These are the messages used to generate the summary.

@default: [ { "role": "system", "content": "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences. DO NOT return anything except the summary." }, { "role": "user", "content": "Here is the transcript:\n\n{{transcript}}\n\n. Here is the ended reason of the call:\n\n{{endedReason}}\n\n" } ]

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: The transcript of the call from call.artifact.transcript
{{systemPrompt}}: The system prompt of the call from assistant.model.messages[type=system].content
{{endedReason}}: The ended reason of the call from call.endedReason

fallbackDestination.transferPlan.summaryPlan.enabled

boolean

This determines whether a summary is generated and stored in call.analysis.summary. Defaults to true.

Usage:

If you want to disable the summary, set this to false.

@default true

fallbackDestination.transferPlan.summaryPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty.

Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

fallbackDestination.transferPlan.sipHeadersInReferToEnabled

boolean

This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params.

@default false

fallbackDestination.transferPlan.fallbackPlan

object

This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human).

Usage:

Used only when mode is warm-transfer-experimental.
If not provided when using warm-transfer-experimental, a default message will be used.

Show child attributes

fallbackDestination.transferPlan.fallbackPlan.message

required

This is the message the assistant will deliver to the customer if the transfer fails.

fallbackDestination.transferPlan.fallbackPlan.endCallEnabled

boolean

default:true

This controls what happens after delivering the failure message to the customer.

true: End the call after delivering the failure message (default)
false: Keep the assistant on the call to continue handling the customer's request

@default true

fallbackDestination.description

string

This is the description of the destination, used by the AI to choose when and how to transfer the call.

hooks

PhoneNumberHookCallRinging · object[]

This is the hooks that will be used for incoming calls to this phone number.

Show child attributes

hooks.on

enum<string>

required

This is the event to trigger the hook on

Available options:

call.ringing

Maximum string length: 1000

hooks.do

(TransferPhoneNumberHookAction · object | SayPhoneNumberHookAction · object)[]

required

This is the set of actions to perform when the hook triggers

TransferPhoneNumberHookAction
SayPhoneNumberHookAction

Show child attributes

hooks.do.type

enum<string>

required

This is the type of action - must be "transfer"

Available options:

transfer

hooks.do.destination

NumberTransferDestination · object

This is the destination details for the transfer - can be a phone number or SIP URI

NumberTransferDestination
SipTransferDestination

Show child attributes

hooks.do.destination.type

enum<string>

required

Available options:

number

hooks.do.destination.number

string

required

This is the phone number to transfer the call to.

Required string length: 3 - 40

hooks.do.destination.message

This is spoken to the customer before connecting them to the destination.

Usage:

If this is not provided and transfer tool messages is not provided, default is "Transferring the call now".
If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message for the destination assistant.

This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the contents field.

hooks.do.destination.numberE164CheckEnabled

boolean

default:true

This is the flag to toggle the E164 check for the number field. This is an advanced property which should be used if you know your use case requires it.

Use cases:

false: To allow non-E164 numbers like +001234567890, 1234, or abc. This is useful for dialing out to non-E164 numbers on your SIP trunks.
true (default): To allow only E164 numbers like +14155551234. This is standard for PSTN calls.

If false, the number is still required to only contain alphanumeric characters (regex: /^\+?[a-zA-Z0-9]+$/).

@default true (E164 check is enabled)

hooks.do.destination.extension

string

This is the extension to dial after transferring the call to the number.

Required string length: 1 - 10

hooks.do.destination.callerId

string

This is the caller ID to use when transferring the call to the number.

Usage:

If not provided, the caller ID will be the number the call is coming from. Example, +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller.
To change this behavior, provide a callerId.
Set to '{{customer.number}}' to always use the customer's number as the caller ID.
Set to '{{phoneNumber.number}}' to always use the phone number of the assistant as the caller ID.
Set to any E164 number to always use that number as the caller ID. This needs to be a number that is owned or verified by your Transport provider like Twilio.

For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid

Maximum string length: 40

hooks.do.destination.transferPlan

object

This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to blind-transfer.

@default transferPlan.mode='blind-transfer'

Show child attributes

hooks.do.destination.transferPlan.mode

enum<string>

required

This configures how transfer is executed and the experience of the destination party receiving the call.

Usage:

blind-transfer: The assistant forwards the call to the destination without any message or summary.
blind-transfer-add-summary-to-sip-header: The assistant forwards the call to the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.
warm-transfer-say-message: The assistant dials the destination, delivers the message to the destination party, connects the customer, and leaves the call.
warm-transfer-say-summary: The assistant dials the destination, provides a summary of the call to the destination party, connects the customer, and leaves the call.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-message: The assistant dials the destination, waits for the operator to speak, delivers the message to the destination party, and then connects the customer.
warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary: The assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.
warm-transfer-twiml: The assistant dials the destination, executes the twiml instructions on the destination call leg, connects the customer, and leaves the call.
warm-transfer-experimental: The assistant puts the customer on hold, dials the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the fallbackMessage to the customer and optionally ends the call.

@default 'blind-transfer'

Available options:

blind-transfer,

blind-transfer-add-summary-to-sip-header,

warm-transfer-say-message,

warm-transfer-say-summary,

warm-transfer-twiml,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-message,

warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary,

warm-transfer-experimental

hooks.do.destination.transferPlan.message

This is the message the assistant will deliver to the destination party before connecting the customer.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header, warm-transfer-say-message, warm-transfer-wait-for-operator-to-speak-first-and-then-say-message, or warm-transfer-experimental.

hooks.do.destination.transferPlan.timeout

number

default:60

This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary

@default 60

Required range: 1 <= x <= 600

hooks.do.destination.transferPlan.sipVerb

object

This specifies the SIP verb to use while transferring the call.

'refer': Uses SIP REFER to transfer the call (default)
'bye': Ends current call with SIP BYE
'dial': Uses SIP DIAL to transfer the call

hooks.do.destination.transferPlan.holdAudioUrl

string

This is the URL to an audio file played while the customer is on hold during transfer.

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the customer.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.
If not provided, the default hold audio will be used.

hooks.do.destination.transferPlan.transferCompleteAudioUrl

string

Usage:

Used only when mode is warm-transfer-experimental.
Used when transferring calls to play hold audio for the destination party.
Must be a publicly accessible URL to an audio file.
Supported formats: MP3 and WAV.

hooks.do.destination.transferPlan.twiml

string

This is the TwiML instructions to execute on the destination call leg before connecting the customer.

Usage:

Used only when mode is warm-transfer-twiml.
Supports only Play, Say, Gather, Hangup and Pause verbs.
Maximum length is 4096 characters.

Example:

<Say voice="alice" language="en-US">Hello, transferring a customer to you.</Say>
<Pause length="2"/>
<Say>They called about billing questions.</Say>

Maximum string length: 4096

hooks.do.destination.transferPlan.summaryPlan

object

This is the plan for generating a summary of the call to present to the destination party.

Usage:

Used only when mode is blind-transfer-add-summary-to-sip-header or warm-transfer-say-summary or warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary or warm-transfer-experimental.

Show child attributes

hooks.do.destination.transferPlan.summaryPlan.messages

object[]

These are the messages used to generate the summary.

You can customize by providing any messages you want.

Here are the template variables available:

{{transcript}}: The transcript of the call from call.artifact.transcript
{{systemPrompt}}: The system prompt of the call from assistant.model.messages[type=system].content
{{endedReason}}: The ended reason of the call from call.endedReason

hooks.do.destination.transferPlan.summaryPlan.enabled

boolean

This determines whether a summary is generated and stored in call.analysis.summary. Defaults to true.

Usage:

If you want to disable the summary, set this to false.

@default true

hooks.do.destination.transferPlan.summaryPlan.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty.

Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

hooks.do.destination.transferPlan.sipHeadersInReferToEnabled

boolean

This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params.

@default false

hooks.do.destination.transferPlan.fallbackPlan

object

This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human).

Usage:

Used only when mode is warm-transfer-experimental.
If not provided when using warm-transfer-experimental, a default message will be used.

Show child attributes

hooks.do.destination.transferPlan.fallbackPlan.message

required

This is the message the assistant will deliver to the customer if the transfer fails.

hooks.do.destination.transferPlan.fallbackPlan.endCallEnabled

boolean

default:true

This controls what happens after delivering the failure message to the customer.

true: End the call after delivering the failure message (default)
false: Keep the assistant on the call to continue handling the customer's request

@default true

hooks.do.destination.description

string

This is the description of the destination, used by the AI to choose when and how to transfer the call.

numberE164CheckEnabled

boolean

default:true

This is the flag to toggle the E164 check for the number field. This is an advanced property which should be used if you know your use case requires it.

Use cases:

false: To allow non-E164 numbers like +001234567890, 1234, or abc. This is useful for dialing out to non-E164 numbers on your SIP trunks.
true (default): To allow only E164 numbers like +14155551234. This is standard for PSTN calls.

If false, the number is still required to only contain alphanumeric characters (regex: /^\+?[a-zA-Z0-9]+$/).

@default true (E164 check is enabled)

status

enum<string>

This is the status of the phone number.

Available options:

active,

activating,

blocked

name

string

This is the name of the phone number. This is just for your own reference.

Maximum string length: 40

assistantId

string

This is the assistant that will be used for incoming calls to this phone number.

If neither assistantId, squadId nor workflowId is set, assistant-request will be sent to your Server URL. Check ServerMessage and ServerMessageResponse for the shape of the message and response that is expected.

workflowId

string

This is the workflow that will be used for incoming calls to this phone number.

If neither assistantId, squadId, nor workflowId is set, assistant-request will be sent to your Server URL. Check ServerMessage and ServerMessageResponse for the shape of the message and response that is expected.

squadId

string

This is the squad that will be used for incoming calls to this phone number.

server

object

This is where cozmox will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.

The order of precedence is:

assistant.server
phoneNumber.server
org.server

Show child attributes

server.timeoutSeconds

number

This is the timeout in seconds for the request. Defaults to 20 seconds.

@default 20

Required range: 1 <= x <= 300

Example:

20

server.url

string

This is where the request will be sent.

server.headers

object

These are the headers to include in the request.

Each key-value pair represents a header name and its value.

server.backoffPlan

object

This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried).

@default undefined (the request will not be retried)

Show child attributes

server.backoffPlan.type

object

required

This is the type of backoff plan to use. Defaults to fixed.

@default fixed

Example:

"fixed"

server.backoffPlan.maxRetries

number

required

This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries).

@default 0

Required range: 0 <= x <= 10

Example:

0

server.backoffPlan.baseDelaySeconds

number

required

This is the base delay in seconds. For linear backoff, this is the delay between each retry. For exponential backoff, this is the initial delay.

Required range: 0 <= x <= 10

Example:

1

number

string

This is the number of the customer.

Required string length: 3 - 40

API Documentation

Webhooks

Voice Agent UI

STT Usage

Endpoint Examples

Assistants

Calls

Campaigns

Chats

Files

Knowledge Base

Logs

Phone Numbers

Sessions

Tools

Workflow

SDK

Outbound

Concurrency

Authorizations

Path Parameters

Response