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

# Import Phone Number

> Import Phone Number from provider configuration (Twilio, Exotel, or SIP trunk)



## OpenAPI

````yaml /api-reference/openapi.json post /v1/convai/phone-numbers
openapi: 3.1.0
info:
  title: Threetone API Documentation
  description: >-
    This is the documentation for the Threetone API. You can use this API to use
    our service programmatically with API keys sent in the x-api-key header. You
    can create and manage API keys in the dashboard at
    https://threetone.in/app/developers/api-keys.
  version: '1.0'
servers:
  - url: https://api.threetone.in
    description: Production
security: []
paths:
  /v1/convai/phone-numbers:
    post:
      tags:
        - Agents Platform
      summary: Import Phone Number
      description: >-
        Import Phone Number from provider configuration (Twilio, Exotel, or SIP
        trunk)
      operationId: create_phone_number_route
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Your API key for programmatic access. Send it in the x-api-key
              header; you can create and manage keys from the Developers page.
            title: X-Api-Key
          description: >-
            Your API key for programmatic access. Send it in the x-api-key
            header; you can create and manage keys from the Developers page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/CreateTwilioPhoneNumberRequest'
                - $ref: '#/components/schemas/CreateExotelPhoneNumberRequest'
                - $ref: '#/components/schemas/CreateSIPTrunkPhoneNumberRequestV2'
              description: Create Phone Request Information
              title: Phone Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePhoneNumberResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateTwilioPhoneNumberRequest:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Phone number
        label:
          type: string
          title: Label
          description: Label for the phone number
        provider:
          type: string
          const: twilio
          title: Provider
          default: twilio
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent ID to assign the phone number to
        sid:
          type: string
          title: Sid
          description: Twilio Account SID
        token:
          type: string
          title: Token
          description: Twilio Auth Token
        region_config:
          anyOf:
            - $ref: '#/components/schemas/RegionConfigRequest'
            - type: 'null'
          description: Twilio Additional Region Configuration
      type: object
      required:
        - phone_number
        - label
        - sid
        - token
      title: CreateTwilioPhoneNumberRequest
    CreateExotelPhoneNumberRequest:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Phone number
        label:
          type: string
          title: Label
          description: Label for the phone number
        provider:
          type: string
          const: exotel
          title: Provider
          default: exotel
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent ID to assign the phone number to
        account_sid:
          type: string
          title: Account Sid
          description: Exotel Account SID
        api_key:
          type: string
          title: Api Key
          description: Exotel API Key
        api_token:
          type: string
          title: Api Token
          description: Exotel API Token
        api_subdomain:
          $ref: '#/components/schemas/ExotelApiSubdomain'
          description: Exotel region-specific API host
        app_id:
          type: string
          title: App Id
          description: Exotel applet identifier used in Calls/connect
        applet_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Applet Url
          description: >-
            Optional full applet URL override. Defaults to Exotel start_voice
            URL derived from account SID and app ID.
      type: object
      required:
        - phone_number
        - label
        - account_sid
        - api_key
        - api_token
        - api_subdomain
        - app_id
      title: CreateExotelPhoneNumberRequest
      example:
        account_sid: your-account-sid
        api_key: your-api-key
        api_subdomain: api.in.exotel.com
        api_token: '********'
        app_id: '12345'
        label: Exotel Outbound
        phone_number: '+919999999999'
        provider: exotel
    CreateSIPTrunkPhoneNumberRequestV2:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Phone number
        label:
          type: string
          title: Label
          description: Label for the phone number
        provider:
          type: string
          const: sip_trunk
          title: Provider
          default: sip_trunk
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent ID to assign the phone number to
        inbound_trunk_config:
          anyOf:
            - $ref: '#/components/schemas/InboundSIPTrunkConfigRequestModel'
            - type: 'null'
        outbound_trunk_config:
          anyOf:
            - $ref: '#/components/schemas/OutboundSIPTrunkConfigRequestModel'
            - type: 'null'
      type: object
      required:
        - phone_number
        - label
      title: CreateSIPTrunkPhoneNumberRequestV2
    CreatePhoneNumberResponseModel:
      properties:
        phone_number_id:
          type: string
          title: Phone Number Id
          description: Phone entity ID
      type: object
      required:
        - phone_number_id
      title: CreatePhoneNumberResponseModel
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RegionConfigRequest:
      properties:
        region_id:
          $ref: '#/components/schemas/TwilioRegionId'
          description: Region ID
        token:
          type: string
          title: Token
          description: Auth Token for this region
        edge_location:
          $ref: '#/components/schemas/TwilioEdgeLocation'
          description: Edge location for this region
      type: object
      required:
        - region_id
        - token
        - edge_location
      title: RegionConfigRequest
    ExotelApiSubdomain:
      type: string
      enum:
        - api.in.exotel.com
        - api.exotel.com
      title: ExotelApiSubdomain
    InboundSIPTrunkConfigRequestModel:
      properties:
        allowed_addresses:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Addresses
          description: >-
            List of IP addresses that are allowed to use the trunk. Each item in
            the list can be an individual IP address or a Classless Inter-Domain
            Routing notation representing a CIDR block.
        allowed_numbers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Numbers
          description: List of phone numbers that are allowed to use the trunk.
        media_encryption:
          $ref: '#/components/schemas/SIPMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
          default: allowed
        credentials:
          anyOf:
            - $ref: '#/components/schemas/SIPTrunkCredentialsRequestModel'
            - type: 'null'
          description: Optional digest authentication credentials (username/password).
        remote_domains:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Remote Domains
          description: Domains of remote SIP servers used to validate TLS certificates.
        attributes_to_headers:
          additionalProperties:
            type: string
          type: object
          title: Attributes To Headers
          description: >-
            Map of dynamic variable name to header name for
            attributes_to_headers
      type: object
      title: InboundSIPTrunkConfigRequestModel
    OutboundSIPTrunkConfigRequestModel:
      properties:
        address:
          type: string
          title: Address
          description: Hostname or IP the SIP INVITE is sent to.
        transport:
          $ref: '#/components/schemas/SIPTrunkTransportEnum'
          description: Protocol to use for SIP transport (signalling layer).
          default: auto
        media_encryption:
          $ref: '#/components/schemas/SIPMediaEncryptionEnum'
          description: Whether or not to encrypt media (data layer).
          default: allowed
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: >-
            SIP X-* headers for INVITE request. These headers are sent as-is and
            may help identify this call.
        attributes_to_headers:
          additionalProperties:
            type: string
          type: object
          title: Attributes To Headers
          description: >-
            Map of dynamic variable name to header name for
            attributes_to_headers
        credentials:
          anyOf:
            - $ref: '#/components/schemas/SIPTrunkCredentialsRequestModel'
            - type: 'null'
          description: >-
            Optional digest authentication credentials (username/password). If
            not provided, ACL authentication is assumed.
        enabled_codecs:
          items:
            $ref: '#/components/schemas/MediaCodec'
          type: array
          title: Enabled Codecs
          description: >-
            Media codecs that should be offered in the SDP for outbound calls.
            If empty, all supported codecs are offered.
      type: object
      required:
        - address
      title: OutboundSIPTrunkConfigRequestModel
    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
    TwilioRegionId:
      type: string
      enum:
        - us1
        - ie1
        - au1
      title: TwilioRegionId
      description: Valid Twilio region IDs.
    TwilioEdgeLocation:
      type: string
      enum:
        - ashburn
        - dublin
        - frankfurt
        - sao-paulo
        - singapore
        - sydney
        - tokyo
        - umatilla
        - roaming
      title: TwilioEdgeLocation
      description: Valid Twilio edge locations.
    SIPMediaEncryptionEnum:
      type: string
      enum:
        - disabled
        - allowed
        - required
      title: SIPMediaEncryptionEnum
    SIPTrunkCredentialsRequestModel:
      properties:
        username:
          type: string
          title: Username
          description: SIP trunk username
        password:
          anyOf:
            - type: string
            - type: 'null'
          title: Password
          description: SIP trunk password - if not specified, then remain unchanged
      type: object
      required:
        - username
      title: SIPTrunkCredentialsRequestModel
    SIPTrunkTransportEnum:
      type: string
      enum:
        - auto
        - udp
        - tcp
        - tls
      title: SIPTrunkTransportEnum
    MediaCodec:
      type: string
      enum:
        - G722/8000
        - PCMU/8000
        - PCMA/8000
      title: MediaCodec

````