Skip to main content
PATCH
/
phone-number
/
{id}
Update Phone Number
curl --request PATCH \
  --url https://api.cozmox.ai/phone-number/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fallbackDestination": {
    "type": "number",
    "number": "<string>",
    "message": "<string>",
    "numberE164CheckEnabled": true,
    "extension": "<string>",
    "callerId": "<string>",
    "transferPlan": {
      "mode": "blind-transfer",
      "message": "<string>",
      "timeout": 60,
      "sipVerb": "refer",
      "holdAudioUrl": "<string>",
      "transferCompleteAudioUrl": "<string>",
      "twiml": "<string>",
      "summaryPlan": {
        "messages": [
          {}
        ],
        "enabled": true,
        "timeoutSeconds": 30.5
      },
      "sipHeadersInReferToEnabled": true,
      "fallbackPlan": {
        "message": "<string>",
        "endCallEnabled": true
      }
    },
    "description": "<string>"
  },
  "hooks": [
    {
      "on": "call.ringing",
      "do": [
        {
          "type": "transfer",
          "destination": {
            "type": "number",
            "number": "<string>",
            "message": "<string>",
            "numberE164CheckEnabled": true,
            "extension": "<string>",
            "callerId": "<string>",
            "transferPlan": {
              "mode": "blind-transfer",
              "message": "<string>",
              "timeout": 60,
              "sipVerb": "refer",
              "holdAudioUrl": "<string>",
              "transferCompleteAudioUrl": "<string>",
              "twiml": "<string>",
              "summaryPlan": {
                "messages": [
                  {}
                ],
                "enabled": true,
                "timeoutSeconds": 30.5
              },
              "sipHeadersInReferToEnabled": true,
              "fallbackPlan": {
                "message": "<string>",
                "endCallEnabled": true
              }
            },
            "description": "<string>"
          }
        }
      ]
    }
  ],
  "numberE164CheckEnabled": true,
  "name": "<string>",
  "assistantId": "<string>",
  "workflowId": "<string>",
  "squadId": "<string>",
  "server": {
    "timeoutSeconds": 20,
    "url": "<string>",
    "headers": {},
    "backoffPlan": {
      "type": "fixed",
      "maxRetries": 0,
      "baseDelaySeconds": 1
    }
  },
  "number": "<string>",
  "credentialId": "<string>"
}
'
{
  "provider": "byo-phone-number",
  "id": "<string>",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "credentialId": "<string>",
  "fallbackDestination": {
    "type": "number",
    "number": "<string>",
    "message": "<string>",
    "numberE164CheckEnabled": true,
    "extension": "<string>",
    "callerId": "<string>",
    "transferPlan": {
      "mode": "blind-transfer",
      "message": "<string>",
      "timeout": 60,
      "sipVerb": "refer",
      "holdAudioUrl": "<string>",
      "transferCompleteAudioUrl": "<string>",
      "twiml": "<string>",
      "summaryPlan": {
        "messages": [
          {}
        ],
        "enabled": true,
        "timeoutSeconds": 30.5
      },
      "sipHeadersInReferToEnabled": true,
      "fallbackPlan": {
        "message": "<string>",
        "endCallEnabled": true
      }
    },
    "description": "<string>"
  },
  "hooks": [
    {
      "on": "call.ringing",
      "do": [
        {
          "type": "transfer",
          "destination": {
            "type": "number",
            "number": "<string>",
            "message": "<string>",
            "numberE164CheckEnabled": true,
            "extension": "<string>",
            "callerId": "<string>",
            "transferPlan": {
              "mode": "blind-transfer",
              "message": "<string>",
              "timeout": 60,
              "sipVerb": "refer",
              "holdAudioUrl": "<string>",
              "transferCompleteAudioUrl": "<string>",
              "twiml": "<string>",
              "summaryPlan": {
                "messages": [
                  {}
                ],
                "enabled": true,
                "timeoutSeconds": 30.5
              },
              "sipHeadersInReferToEnabled": true,
              "fallbackPlan": {
                "message": "<string>",
                "endCallEnabled": true
              }
            },
            "description": "<string>"
          }
        }
      ]
    }
  ],
  "numberE164CheckEnabled": true,
  "status": "active",
  "name": "<string>",
  "assistantId": "<string>",
  "workflowId": "<string>",
  "squadId": "<string>",
  "server": {
    "timeoutSeconds": 20,
    "url": "<string>",
    "headers": {},
    "backoffPlan": {
      "type": "fixed",
      "maxRetries": 0,
      "baseDelaySeconds": 1
    }
  },
  "number": "<string>"
}

Authorizations

​
Authorization
string
header
required

Retrieve your API Key from Dashboard.

Path Parameters

​
id
string
required

Body

application/json
​
fallbackDestination
NumberTransferDestination · object

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

  1. assistantId is not set
  2. squadId is not set
  3. 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.

​
hooks
PhoneNumberHookCallRinging · object[]

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

​
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)

​
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.

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.

​
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:

  1. assistant.server
  2. phoneNumber.server
  3. org.server
​
number
string

This is the number of the customer.

Required string length: 3 - 40
​
credentialId
string

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.

Response

200 - application/json
​
provider
enum<string>
required

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

Available options:
byo-phone-number
​
id
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:

  1. assistantId is not set
  2. squadId is not set
  3. 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.

​
hooks
PhoneNumberHookCallRinging · object[]

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

​
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.

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.

​
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:

  1. assistant.server
  2. phoneNumber.server
  3. org.server
​
number
string

This is the number of the customer.

Required string length: 3 - 40