openapi: 3.0.1
info:
  title: Retell AI Agent Phone Number API
  description: REST API for building, testing, and deploying AI voice agents that make and receive phone and web calls. Configure a response engine (Retell LLM, a custom LLM, or a Conversation Flow), attach a voice, provision phone numbers, place outbound and web calls, run batch campaigns, ground agents with knowledge bases, and read back transcripts, recordings, and call analysis. All endpoints are authenticated with a Bearer API key.
  termsOfService: https://www.retellai.com/terms-of-service
  contact:
    name: Retell AI Support
    url: https://docs.retellai.com
  version: '2.0'
servers:
- url: https://api.retellai.com
security:
- api_key: []
tags:
- name: Phone Number
paths:
  /create-phone-number:
    post:
      operationId: createPhoneNumber
      tags:
      - Phone Number
      summary: Buy a phone number.
      description: Provisions (purchases) a new phone number and optionally binds inbound and outbound agents to it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePhoneNumberRequest'
      responses:
        '201':
          description: Phone number provisioned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
  /import-phone-number:
    post:
      operationId: importPhoneNumber
      tags:
      - Phone Number
      summary: Import an existing phone number.
      description: Connects a number you already own via your own SIP trunk / elastic SIP trunking for use with Retell agents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportPhoneNumberRequest'
      responses:
        '201':
          description: Phone number imported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
  /get-phone-number/{phone_number}:
    get:
      operationId: getPhoneNumber
      tags:
      - Phone Number
      summary: Retrieve a phone number.
      parameters:
      - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
  /list-phone-numbers:
    get:
      operationId: listPhoneNumbers
      tags:
      - Phone Number
      summary: List phone numbers.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PhoneNumberResponse'
  /update-phone-number/{phone_number}:
    patch:
      operationId: updatePhoneNumber
      tags:
      - Phone Number
      summary: Update a phone number.
      parameters:
      - $ref: '#/components/parameters/PhoneNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumberRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
  /delete-phone-number/{phone_number}:
    delete:
      operationId: deletePhoneNumber
      tags:
      - Phone Number
      summary: Delete (release) a phone number.
      parameters:
      - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '204':
          description: Phone number released.
components:
  schemas:
    UpdatePhoneNumberRequest:
      type: object
      properties:
        inbound_agent_id:
          type: string
        outbound_agent_id:
          type: string
        nickname:
          type: string
    ImportPhoneNumberRequest:
      type: object
      required:
      - phone_number
      properties:
        phone_number:
          type: string
        termination_uri:
          type: string
          description: SIP termination URI for outbound.
        sip_trunk_auth_username:
          type: string
        sip_trunk_auth_password:
          type: string
        inbound_agent_id:
          type: string
        outbound_agent_id:
          type: string
        nickname:
          type: string
    PhoneNumberResponse:
      type: object
      properties:
        phone_number:
          type: string
        phone_number_pretty:
          type: string
        nickname:
          type: string
        inbound_agent_id:
          type: string
        outbound_agent_id:
          type: string
        area_code:
          type: integer
        last_modification_timestamp:
          type: integer
    CreatePhoneNumberRequest:
      type: object
      properties:
        area_code:
          type: integer
        nickname:
          type: string
        inbound_agent_id:
          type: string
        outbound_agent_id:
          type: string
        number_provider:
          type: string
          enum:
          - twilio
          - telnyx
  parameters:
    PhoneNumber:
      name: phone_number
      in: path
      required: true
      description: Phone number in E.164 format.
      schema:
        type: string
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'