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

# Purchase a Twilio phone number

> Purchase a phone number from Twilio and add it to the organization. Requires sufficient phone_lines credits.



## OpenAPI

````yaml post /api/v1/twilio/purchase
openapi: 3.0.0
info:
  version: 1.0.0
  title: Feather AI API
servers:
  - url: https://prod.featherhq.com
    description: Production environment
security: []
paths:
  /api/v1/twilio/purchase:
    post:
      tags:
        - Phone Numbers
      summary: Purchase a Twilio phone number
      description: >-
        Purchase a phone number from Twilio and add it to the organization.
        Requires sufficient phone_lines credits.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                  pattern: ^\+1\d{10}$
                  description: The phone number to purchase in E.164 format
                  example: '+14155551234'
                friendlyName:
                  type: string
                  description: A friendly name for the phone number
                  example: My Business Line
              required:
                - phoneNumber
      responses:
        '200':
          description: Phone number purchased successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  phoneNumber:
                    type: string
                  city:
                    type: string
                    nullable: true
                  state:
                    type: string
                    nullable: true
                  country:
                    type: string
                  ownership:
                    type: string
                    nullable: true
                    enum:
                      - FEATHER
                      - CLIENT
                  inboundAgent:
                    type: object
                    properties:
                      agentId:
                        type: string
                        nullable: true
                      agentName:
                        type: string
                        nullable: true
                  outboundAgents:
                    type: array
                    items:
                      type: object
                      properties:
                        agentId:
                          type: string
                          nullable: true
                        agentName:
                          type: string
                          nullable: true
                      required:
                        - agentId
                        - agentName
                  smsLinkedAgent:
                    type: object
                    properties:
                      agentId:
                        type: string
                        nullable: true
                      agentName:
                        type: string
                        nullable: true
                    required:
                      - agentId
                      - agentName
                  squad:
                    type: object
                    properties:
                      squadId:
                        type: string
                      squadName:
                        type: string
                    required:
                      - squadId
                      - squadName
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                  - id
                  - phoneNumber
                  - city
                  - state
                  - country
                  - ownership
                  - inboundAgent
                  - outboundAgents
                  - createdAt
                  - updatedAt
        '400':
          description: Bad request - insufficient credits or validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    default: 400
                  message:
                    type: string
                    default: Bad request
                  code:
                    type: string
                    enum:
                      - BAD_REQUEST
                    default: BAD_REQUEST
                  success:
                    type: boolean
                    enum:
                      - false
                    default: false
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    default: 500
                  message:
                    type: string
                    default: Internal server error
                  code:
                    type: string
                    enum:
                      - INTERNAL_SERVER_ERROR
                    default: INTERNAL_SERVER_ERROR
                  success:
                    type: boolean
                    enum:
                      - false
                    default: false
      security:
        - ApiKey: []
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key

````