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

# Create a new phone number

> Create and configure a new phone number in the PIA Platform. This endpoint supports two phone number types:

- Import Phone Numbers (SIP) for custom SIP trunk integration
- PIA-managed phone numbers (provided by our platform)

The phone number will be validated and configured based on the provided settings. The created phone
number can then be associated with AI agents to handle inbound and outbound calls.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/phone-numbers/
openapi: 3.1.0
info:
  title: Verbex Platform API
  description: API for managing AI agents, calls, phone numbers, and more.
  version: 1.0.0
servers: []
security: []
paths:
  /v1/phone-numbers/:
    post:
      tags:
        - Phone Numbers
      summary: Create a new phone number
      description: >-
        Create and configure a new phone number in the PIA Platform. This
        endpoint supports two phone number types:


        - Import Phone Numbers (SIP) for custom SIP trunk integration

        - PIA-managed phone numbers (provided by our platform)


        The phone number will be validated and configured based on the provided
        settings. The created phone

        number can then be associated with AI agents to handle inbound and
        outbound calls.
      operationId: create_phone_number_v1_phone_numbers__post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/CreateSIPPhoneNumberRequest'
                - $ref: '#/components/schemas/CreatePiaPhoneNumberRequest'
                - $ref: '#/components/schemas/CreateTwilioPhoneNumberRequest'
              title: Phone Number
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/GetSIPPhoneNumberResponse'
                  - $ref: '#/components/schemas/GetPiaPhoneNumberResponse'
                  - $ref: '#/components/schemas/GetTwilioPhoneNumberResponse'
                title: Response Create Phone Number V1 Phone Numbers  Post
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/app__phone_numbers__schemas__ErrorResponse
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/app__phone_numbers__schemas__ErrorResponse
          description: Internal Server Error
components:
  schemas:
    CreateSIPPhoneNumberRequest:
      properties:
        provider:
          type: string
          const: sip
          title: Provider
          description: >-
            Specifies this as a request to create an Import Phone Number (SIP
            provider) configuration
          default: sip
        phone_number:
          type: string
          title: Phone Number
          description: >-
            The phone number in E.164 format (e.g., +14155552671). Must include
            country code
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
          description: >-
            A human-readable label for this phone number to help identify its
            purpose
        sip_termination_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Termination Uri
          description: The SIP URI where calls to this number should be terminated
        sip_trunk_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Trunk Username
          description: Username for authenticating with the SIP trunk provider
        sip_trunk_password:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Trunk Password
          description: Password for authenticating with the SIP trunk provider
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent that will handle incoming calls to this number
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: >-
            ID of the AI agent that will be used when making outbound calls from
            this number
        sip_infra_region:
          type: string
          enum:
            - global
            - bd
            - bd_link3
          title: Sip Infra Region
          description: >-
            The infrastructure region for SIP routing. 'global' for worldwide
            routing, 'bd' for Bangladesh-specific routing, 'bd_link3' for
            Bangladesh Link3 IPTSP routing
          default: global
      type: object
      required:
        - phone_number
      title: CreateSIPPhoneNumberRequest
    CreatePiaPhoneNumberRequest:
      properties:
        provider:
          type: string
          const: pia
          title: Provider
          description: >-
            Specifies this as a request to create a Pia Platform managed phone
            number
          default: pia
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
          description: >-
            A human-readable label for this phone number to help identify its
            purpose
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent that will handle incoming calls to this number
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: >-
            ID of the AI agent that will be used when making outbound calls from
            this number
      type: object
      title: CreatePiaPhoneNumberRequest
    CreateTwilioPhoneNumberRequest:
      properties:
        provider:
          type: string
          const: twilio
          title: Provider
          description: >-
            Specifies this as a request to create a direct Twilio integration
            phone number
          default: twilio
        phone_number:
          type: string
          title: Phone Number
          description: >-
            The phone number in E.164 format (e.g., +14155552671). Must include
            country code
        twilio_account_sid:
          type: string
          title: Twilio Account Sid
          description: The Twilio Account SID for authenticating with Twilio's API
        twilio_auth_token:
          type: string
          title: Twilio Auth Token
          description: The Twilio Auth Token for authenticating with Twilio's API
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent that will handle incoming calls to this number
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: >-
            ID of the AI agent that will be used when making outbound calls from
            this number
      type: object
      required:
        - phone_number
        - twilio_account_sid
        - twilio_auth_token
      title: CreateTwilioPhoneNumberRequest
    GetSIPPhoneNumberResponse:
      properties:
        _id:
          type: string
          title: Id
          description: Unique identifier for this phone number record
        provider:
          type: string
          const: sip
          title: Provider
          description: Indicates this is an Import Phone Number (SIP provider)
          default: sip
        phone_number:
          type: string
          title: Phone Number
          description: >-
            The phone number in E.164 format, including country code (e.g.,
            +14155552671)
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
          description: A human-readable label for this phone number
        sip_termination_uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Termination Uri
          description: The SIP URI where calls are terminated
        sip_trunk_username:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Trunk Username
          description: Username for SIP trunk authentication
        sip_trunk_password:
          anyOf:
            - type: string
            - type: 'null'
          title: Sip Trunk Password
          description: Password for SIP trunk authentication
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent handling incoming calls
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: ID of the AI agent used for outbound calls
        sip_infra_region:
          type: string
          enum:
            - global
            - bd
            - bd_link3
          title: Sip Infra Region
          description: >-
            The infrastructure region for SIP routing: 'global' or 'bd'
            (Bangladesh)
          default: global
      type: object
      required:
        - phone_number
      title: GetSIPPhoneNumberResponse
    GetPiaPhoneNumberResponse:
      properties:
        _id:
          type: string
          title: Id
          description: Unique identifier for this phone number record
        provider:
          type: string
          const: pia
          title: Provider
          description: Indicates this is a Pia Platform managed phone number
          default: pia
        phone_number:
          type: string
          title: Phone Number
          description: The phone number in E.164 format (e.g., +14155552671)
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
          description: A human-readable label for this phone number
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent handling incoming calls
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: ID of the AI agent used for outbound calls
      type: object
      required:
        - phone_number
      title: GetPiaPhoneNumberResponse
    GetTwilioPhoneNumberResponse:
      properties:
        _id:
          type: string
          title: Id
          description: Unique identifier for this phone number record
        provider:
          type: string
          const: twilio
          title: Provider
          description: Indicates this is a direct Twilio integration phone number
          default: twilio
        phone_number:
          type: string
          title: Phone Number
          description: >-
            The phone number in E.164 format, including country code (e.g.,
            +14155552671)
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
          description: A human-readable label for this phone number
        twilio_account_sid:
          anyOf:
            - type: string
            - type: 'null'
          title: Twilio Account Sid
          description: The Twilio Account SID used for API authentication
        twilio_auth_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Twilio Auth Token
          description: The Twilio Auth Token used for API authentication
        inbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Inbound Agent Id
          description: ID of the AI agent handling incoming calls
        outbound_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Outbound Agent Id
          description: ID of the AI agent used for outbound calls
      type: object
      required:
        - phone_number
      title: GetTwilioPhoneNumberResponse
    app__phone_numbers__schemas__ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: A short error code identifying the type of error that occurred
        message:
          type: string
          title: Message
          description: >-
            A detailed human-readable message explaining the error and possible
            solutions
      type: object
      required:
        - error
        - message
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````