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

# Import Number

> Import a Twilio phone number for an accessible agent.

Imports a Twilio number and assigns it to an agent. The API key must belong to the supplied user, and that user must have access to the agent.

The agent must be on a paid plan and must not already have a business phone number. Only `twilio` is accepted as the source in this production version.

<Warning>
  Treat the Twilio account SID and auth token as secrets. Do not place them in client-side code, screenshots, or logs.
</Warning>


## OpenAPI

````yaml POST /import-number
openapi: 3.0.1
info:
  title: Phonely API
  description: API for Phonely services including agent management and call summaries
  version: 1.0.0
servers:
  - url: https://app.phonely.ai/api
security: []
paths:
  /import-number:
    post:
      summary: Import number
      description: Import a Twilio phone number to an agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportNumberRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportNumberResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ImportNumberRequest:
      type: object
      additionalProperties: false
      required:
        - uid
        - agentId
        - source
        - twilioAccountSid
        - twilioAuthToken
        - phoneNumber
        - countryCode
      properties:
        uid:
          type: string
          description: User ID
        agentId:
          type: string
          description: Agent ID (agent should not have a phone number assigned yet)
        source:
          type: string
          enum:
            - twilio
          description: Phone number source (currently only supports 'twilio')
        twilioAccountSid:
          type: string
          description: Twilio account SID
        twilioAuthToken:
          type: string
          description: Twilio auth token
        phoneNumber:
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          description: Phone number to import, includes country code. i.e +10123456789
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
          description: Country code of the phone number, ISO 3166-1 alpha-2 format
    ImportNumberResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Message indicating the result of the operation
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code or identifier
        message:
          type: string
          description: Detailed error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.