Skip to main content
POST
/
api
/
v1
/
sip-phone-numbers
Create phone number
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phoneNumber: '<string>',
    credentialsId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    displayName: null,
    description: null,
    registration: false
  })
};

fetch('https://blackbox.dasha.ai/api/v1/sip-phone-numbers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "orgId": "<string>",
  "phoneNumber": "<string>",
  "credentialsId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdTime": "2023-11-07T05:31:56Z",
  "lastUpdateTime": "2023-11-07T05:31:56Z",
  "registrationStatus": {
    "state": "Disabled",
    "errorDescription": "<string>",
    "sipResponseMessage": "<string>",
    "lastUpdated": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "description": "<string>",
  "displayName": "<string>",
  "registration": true,
  "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "incomingCallsAgentId": "<string>"
}

​
Phone Number Uniqueness

Phone numbers have specific uniqueness constraints:
  • Same phone number in multiple organizations: The same phone number can exist across different organizations
  • Organization-level uniqueness: Within your organization, each phone number and credential ID pair must be unique
This allows different organizations to use the same phone number with different SIP providers.

Body

Phone number configuration

Configuration for creating or updating a SIP phone number. Associates a phone number with SIP credentials and defines how the number appears in caller ID and whether it registers with the SIP provider.

​
phoneNumber
string
required

Phone number to configure for outbound calling or inbound routing. The format depends on your SIP provider's requirements.

Required string length: 1 - 255
​
credentialsId
string<uuid>
required

SIP credentials to use for this phone number. References the trunk configuration that handles authentication and routing for calls using this number.

​
displayName
string | null

Display name shown in caller ID when making outbound calls with this number. Helps recipients identify the caller before answering. Some carriers may override or restrict this value.

Maximum string length: 255
​
description
string | null

Human-readable description of this phone number. Useful for documenting the number's purpose.

Maximum string length: 255
​
registration
boolean
default:false

Whether to perform SIP registration for this phone number. Some SIP providers require registration before making calls. Enable this when your provider requires registration, disable it when using providers that don't require or support registration.

Response

Phone number created successfully

SIP phone number configuration including associated credentials, caller ID settings, inbound routing, and registration status. Contains all information needed to use this number for making and receiving calls.

​
id
string<uuid>
required

Unique identifier for this phone number configuration. Use this ID when referencing the number in agent configurations or API calls.

​
orgId
string
required

Organization that owns this phone number. Used for access control and resource isolation.

Minimum string length: 1
​
phoneNumber
string
required

Phone number configured for outbound calling or inbound routing.

Minimum string length: 1
​
credentialsId
string<uuid>
required

SIP credentials used by this phone number. References the trunk configuration that handles authentication and routing for calls.

​
createdTime
string<date-time>
required

Timestamp when this phone number configuration was originally created.

​
lastUpdateTime
string<date-time>
required

Timestamp when this phone number configuration was last modified. Updates when settings like DisplayName, Registration, or IncomingCallsAgentId change.

​
registrationStatus
object
required

Current SIP registration status for this phone number. Indicates whether the number is successfully registered with the SIP provider and able to receive inbound calls.

​
description
string | null

Human-readable description of this phone number. Helps document the number's purpose or usage.

​
displayName
string | null

Display name shown in caller ID when making outbound calls with this number. Helps recipients identify the caller.

​
registration
boolean

Whether SIP registration is performed for this phone number. Some SIP providers require registration before making calls. Indicates if registration is enabled for this configuration.

​
providerId
string<uuid> | null

Reference to the VoIP provider that manages this phone number. Present only for provider-imported phone numbers. When present, the provider handles phone number lifecycle and trunk configuration.

​
incomingCallsAgentId
string | null

Agent that handles inbound calls to this phone number. When specified, incoming calls automatically route to this agent. When not set, inbound calls to this number are not answered.