> ## Documentation Index
> Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create phone number

> Creates a new SIP phone number in your organization. The phone number can be linked
to an agent for inbound call handling.

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


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/sip-phone-numbers
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - ApiKey: []
  - OAuth: []
tags:
  - name: ActivityLogs
  - name: Agents
  - name: AgentTestCases
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: Copilot
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/sip-phone-numbers:
    post:
      tags:
        - SipPhoneNumbers
      summary: Create phone number
      description: >-
        Creates a new SIP phone number in your organization. The phone number
        can be linked

        to an agent for inbound call handling.
      requestBody:
        description: Phone number configuration
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SipPhoneNumberRequestDto'
              description: >-
                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.
          text/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SipPhoneNumberRequestDto'
              description: >-
                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.
          application/*+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SipPhoneNumberRequestDto'
              description: >-
                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.
      responses:
        '201':
          description: Phone number created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipPhoneNumberResponseDto'
        '400':
          description: Invalid configuration or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: >-
            Phone number with same number and credential combination already
            exists in organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error occurred during phone number creation
components:
  schemas:
    SipPhoneNumberRequestDto:
      required:
        - credentialsId
        - phoneNumber
      type: object
      properties:
        phoneNumber:
          maxLength: 255
          minLength: 1
          type: string
          description: >-
            Phone number to configure for outbound calling or inbound routing.
            The format depends on your SIP provider's requirements.
        credentialsId:
          type: string
          description: >-
            SIP credentials to use for this phone number. References the trunk
            configuration that handles authentication and routing for calls
            using this number.
          format: uuid
        displayName:
          maxLength: 255
          type: string
          description: >-
            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.
          default: null
          nullable: true
        description:
          maxLength: 255
          type: string
          description: >-
            Human-readable description of this phone number. Useful for
            documenting the number's purpose.
          default: null
          nullable: true
        registration:
          type: boolean
          description: >-
            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.
          default: false
      additionalProperties: false
      description: >-
        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.
    SipPhoneNumberResponseDto:
      required:
        - createdTime
        - credentialsId
        - id
        - lastUpdateTime
        - orgId
        - phoneNumber
        - registrationStatus
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this phone number configuration. Use this ID
            when referencing the number in agent configurations or API calls.
          format: uuid
        orgId:
          minLength: 1
          type: string
          description: >-
            Organization that owns this phone number. Used for access control
            and resource isolation.
        phoneNumber:
          minLength: 1
          type: string
          description: Phone number configured for outbound calling or inbound routing.
        credentialsId:
          type: string
          description: >-
            SIP credentials used by this phone number. References the trunk
            configuration that handles authentication and routing for calls.
          format: uuid
        description:
          type: string
          description: >-
            Human-readable description of this phone number. Helps document the
            number's purpose or usage.
          nullable: true
        displayName:
          type: string
          description: >-
            Display name shown in caller ID when making outbound calls with this
            number. Helps recipients identify the caller.
          nullable: true
        registration:
          type: boolean
          description: >-
            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:
          type: string
          description: >-
            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.
          format: uuid
          nullable: true
        incomingCallsAgentId:
          type: string
          description: >-
            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.
          nullable: true
        createdTime:
          type: string
          description: >-
            Timestamp when this phone number configuration was originally
            created.
          format: date-time
        lastUpdateTime:
          type: string
          description: >-
            Timestamp when this phone number configuration was last modified.
            Updates when settings like DisplayName, Registration, or
            IncomingCallsAgentId change.
          format: date-time
        registrationStatus:
          allOf:
            - $ref: '#/components/schemas/SIPRegistrationStatusDTO'
          description: >-
            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.
      additionalProperties: false
      description: >-
        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.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    SIPRegistrationStatusDTO:
      type: object
      properties:
        state:
          allOf:
            - $ref: '#/components/schemas/RegistartionState'
          description: The current registration state.
        errorDescription:
          type: string
          description: Human-readable error description for failed registrations.
          nullable: true
        sipResponseMessage:
          type: string
          description: Full SIP response message for failed registrations.
          nullable: true
        lastUpdated:
          type: string
          description: When the status was last updated.
          format: date-time
        expiresAt:
          type: string
          description: >-
            When the registration expires. Null for failed or disabled
            registrations.
          format: date-time
          nullable: true
      additionalProperties: false
    RegistartionState:
      enum:
        - Disabled
        - InProgress
        - Succeeded
        - InProgressWithAuth
        - Initialized
        - Unknown
        - Failed
      type: string
      description: Represents the state of a SIP registration.
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authentication (Bearer {key})
      scheme: Bearer
    OAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.dasha.ai/connect/authorize
          scopes:
            platform_api: Platform API

````