AgentPhone Numbers API

openapi: 3.2.0
info:
  title: SMS Numbers API
  description: A simple API to provision phone numbers and receive SMS
  version: 0.1.0
tags:
- name: Numbers
paths:
  /v1/numbers:
    post:
      tags:
      - Numbers
      summary: Create Number
      description: 'Provision a new phone number from the account''s configured SMS provider

        (or an iMessage line with type=imessage). Optional externalId tags the

        number with your own identifier; see PATCH /v1/numbers/{id}.'
      operationId: create_number_v1_numbers_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNumberRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Numbers
      summary: List Numbers
      description: 'List the active phone numbers for this account.


        Released (deleted) numbers are excluded so the count reflects the numbers

        the account actually holds. Fetch a single number via GET /{number_id}

        (which returns it regardless of status). Pass externalId to find the

        number you tagged with your own identifier.'
      operationId: list_numbers_v1_numbers_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: externalId
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Only the number tagged with this externalId
          title: Externalid
        description: Only the number tagged with this externalId
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/available:
    get:
      tags:
      - Numbers
      summary: List Available Numbers
      description: 'Search purchasable phone numbers before buying one.


        Pick a number here, then buy it by passing the same `phoneNumber` to

        `POST /v1/numbers`. Searching with no criteria returns a page of whatever

        is currently in stock.


        **Results are not reserved.** This is live inventory, so a number can be

        bought by someone else between your search and your purchase. When that

        happens the purchase returns `409` with fresh alternatives in this same

        shape; pick another and retry rather than treating it as fatal.


        Criteria support varies by account, and there is no single rule that

        holds everywhere:


        - `areaCode` is the most broadly supported filter.

        - `city`, `state` and `zip` work on some accounts and not others.

        Where they aren''t supported they are ignored rather than rejected, so

        check what comes back instead of assuming the filter applied.

        - `state` on its own is honored on some accounts and rejected with `400`

        on others. Pair it with `city` for consistent behavior.


        Returns `404` when number search isn''t available on your account at all,

        and `422` when it isn''t configured yet. If you need location search and

        aren''t getting it, contact support.


        Giving a Canadian area code searches Canada even though `country`

        defaults to `US`.


        `country=UK` (or `GB`) returns United Kingdom mobile numbers on accounts

        where they''re available. UK numbers are SMS-only and have no area codes,

        so location filters are rejected for UK searches.


        If `widened` is true, your exact criteria were out of stock and these are

        nearby alternatives instead.'
      operationId: list_available_numbers_v1_numbers_available_get
      security:
      - HTTPBearer: []
      parameters:
      - name: areaCode
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 3-digit area code, e.g. "415". The most broadly supported filter.
          title: Areacode
        description: 3-digit area code, e.g. "415". The most broadly supported filter.
      - name: city
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: City name. Pair with state. Support varies by account.
          title: City
        description: City name. Pair with state. Support varies by account.
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 2-letter state code, e.g. "CA". Pair with city for consistent results; standalone support varies by account.
          title: State
        description: 2-letter state code, e.g. "CA". Pair with city for consistent results; standalone support varies by account.
      - name: zip
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 5-digit ZIP. Support varies by account.
          title: Zip
        description: 5-digit ZIP. Support varies by account.
      - name: country
        in: query
        required: false
        schema:
          type: string
          description: '"US", "CA", or "UK" ("GB" is accepted as an alias). United Kingdom availability varies by account.'
          default: US
          title: Country
        description: '"US", "CA", or "UK" ("GB" is accepted as an alias). United Kingdom availability varies by account.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 30
          minimum: 1
          description: Max results, 1-30.
          default: 10
          title: Limit
        description: Max results, 1-30.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableNumberListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/lookup:
    get:
      tags:
      - Numbers
      summary: Lookup Numbers
      description: 'Look up line-type intelligence for phone numbers.


        Answers "should my agent text this number" before spending a message:

        mobile (`lineType: "mobile"`) vs landline vs VoIP, country, and whether

        the handset supports RCS. Up to 25 comma-separated numbers per request.

        Billed at $0.009 per number looked up.'
      operationId: lookup_numbers_v1_numbers_lookup_get
      security:
      - HTTPBearer: []
      parameters:
      - name: phoneNumbers
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated E.164 numbers, up to 25
          title: Phonenumbers
        description: Comma-separated E.164 numbers, up to 25
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberLookupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/{number_id}:
    get:
      tags:
      - Numbers
      summary: Get Number
      description: 'Get a single phone number owned by this account.


        Returns the number regardless of status (including released) so detail

        pages still load for numbers that are no longer active. `ext:`

        in place of the id looks the number up by the tag you set.'
      operationId: get_number_v1_numbers__number_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Numbers
      summary: Update Number
      description: 'Update a number. Only the fields you send are changed.


        externalId: your own identifier for the number. Send a string to set it,

        null to clear it, or omit it to leave it unchanged. Must be unique within

        your account (409 otherwise). Works on any number type. The tag is echoed

        on every number response and webhook payload and usable for lookup as

        GET /v1/numbers/ext: or GET /v1/numbers?externalId=.


        expiresAt: hard end date for the number (ISO 8601). After it passes the

        number is released automatically and a number.released webhook is sent.

        Send a datetime to set or move it (at least 5 minutes out), null to

        clear it, or omit it to leave it unchanged.


        Fields this endpoint does not support are rejected with 422, never

        silently ignored.'
      operationId: update_number_v1_numbers__number_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNumberRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Numbers
      summary: Delete Number
      description: 'Release (delete) a phone number.


        This will:

        1. Release the number from its upstream provider when supported

        2. Mark the number as "released" in the database

        3. Keep all messages and conversation history (for audit purposes)


        WARNING: This action is irreversible! The number cannot be recovered.'
      operationId: delete_number_v1_numbers__number_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/{number_id}/messages:
    get:
      tags:
      - Numbers
      summary: Get Messages
      description: 'Get messages for a specific phone number.


        Supports cursor-based pagination via before/after timestamps.'
      operationId: get_messages_v1_numbers__number_id__messages_get
      security:
      - HTTPBearer: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          default: 50
          title: Limit
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Before
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: After
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AvailableNumber:
      properties:
        phoneNumber:
          type: string
          title: Phonenumber
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        rateCenter:
          anyOf:
          - type: string
          - type: 'null'
          title: Ratecenter
        areaCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Areacode
      type: object
      required:
      - phoneNumber
      title: AvailableNumber
      description: 'One purchasable number from GET /v1/numbers/available.


        Geography is best-effort: `city`, `state` and `rateCenter` are null when

        the inventory source doesn''t return per-number detail. Only `phoneNumber`

        is guaranteed, and it is the field to pass back to POST /v1/numbers.'
    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
    NumberLookupResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/NumberLookupEntry'
          type: array
          title: Data
      type: object
      required:
      - data
      title: NumberLookupResponse
    MessageListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/MessageResponse'
          type: array
          title: Data
        hasMore:
          type: boolean
          title: Hasmore
      type: object
      required:
      - data
      - hasMore
      title: MessageListResponse
    PhoneNumberListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PhoneNumberResponse'
          type: array
          title: Data
        hasMore:
          type: boolean
          title: Hasmore
        total:
          type: integer
          title: Total
      type: object
      required:
      - data
      - hasMore
      - total
      title: PhoneNumberListResponse
    MessageResponse:
      properties:
        id:
          type: string
          title: Id
        from_:
          type: string
          title: 'From '
        to:
          type: string
          title: To
        body:
          type: string
          title: Body
        direction:
          type: string
          title: Direction
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        failureReason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failurereason
        receivedAt:
          type: string
          format: date-time
          title: Receivedat
      type: object
      required:
      - id
      - from_
      - to
      - body
      - direction
      - receivedAt
      title: MessageResponse
    NumberLookupEntry:
      properties:
        phoneNumber:
          type: string
          title: Phonenumber
        lineType:
          anyOf:
          - type: string
          - type: 'null'
          title: Linetype
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
        rcsEnabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Rcsenabled
      type: object
      required:
      - phoneNumber
      title: NumberLookupEntry
    UpdateNumberRequest:
      properties:
        externalId:
          anyOf:
          - type: string
          - type: 'null'
          title: Externalid
        expiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expiresat
      additionalProperties: false
      type: object
      title: UpdateNumberRequest
      description: 'PATCH /v1/numbers/{id}. Only the fields you send are changed.

        externalId is your own identifier for the number, unique within your

        account, usable in place of our id as `ext:<externalId>` and echoed on

        every number response and webhook. expiresAt is a hard end date after

        which the number is released automatically. For both, a value sets it,

        null clears it, omitting it leaves it unchanged. Fields this endpoint

        does not support are rejected with 422 rather than ignored.'
    PhoneNumberResponse:
      properties:
        id:
          type: string
          title: Id
        phoneNumber:
          type: string
          title: Phonenumber
        country:
          type: string
          title: Country
        status:
          type: string
          title: Status
        type:
          type: string
          title: Type
          default: sms
        agentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Agentid
        outboundSms:
          type: string
          enum:
          - enabled
          - activating
          - registration_required
          title: Outboundsms
          default: enabled
        inboundCallsEnabled:
          type: boolean
          title: Inboundcallsenabled
          default: true
        readReceiptsEnabled:
          type: boolean
          title: Readreceiptsenabled
          default: true
        whatsappEnabled:
          type: boolean
          title: Whatsappenabled
          default: false
        dailyNewContacts:
          anyOf:
          - $ref: '#/components/schemas/DailyNewContactsUsage'
          - type: 'null'
        externalId:
          anyOf:
          - type: string
          - type: 'null'
          title: Externalid
        expiresAt:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiresat
        createdAt:
          type: string
          format: date-time
          title: Createdat
        purchasedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Purchasedat
      type: object
      required:
      - id
      - phoneNumber
      - country
      - status
      - createdAt
      title: PhoneNumberResponse
    CreateNumberRequest:
      properties:
        country:
          type: string
          title: Country
          default: US
        areaCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Areacode
        agentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Agentid
        externalId:
          anyOf:
          - type: string
          - type: 'null'
          title: Externalid
        type:
          anyOf:
          - type: string
            enum:
            - sms
            - imessage
          - type: 'null'
          title: Type
        imessageType:
          anyOf:
          - type: string
            enum:
            - inbound
            - outbound
          - type: 'null'
          title: Imessagetype
        expiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expiresat
      type: object
      title: CreateNumberRequest
    DailyNewContactsUsage:
      properties:
        used:
          type: integer
          title: Used
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
      type: object
      required:
      - used
      title: DailyNewContactsUsage
    AvailableNumberListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AvailableNumber'
          type: array
          title: Data
        widened:
          type: boolean
          title: Widened
          default: false
      type: object
      required:
      - data
      title: AvailableNumberListResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer