Happyrobot Phone Numbers API

openapi: 3.2.0
info:
  title: Happyrobot Public Phone Numbers API
  description: Public API endpoints for Happyrobot
  version: 0.1.1
servers:
- url: https://platform.happyrobot.ai/api/v2
security:
- bearerAuth: []
tags:
- name: Phone Numbers
paths:
  /phone-numbers/:
    get:
      summary: List phone numbers
      tags:
      - Phone Numbers
      description: Returns all phone numbers for the authenticated organization, including Twilio, Telnyx, and SIP trunk numbers with caller ID information.
      parameters:
      - schema:
          type: string
        in: query
        name: restrict
        required: false
        description: 'Comma-separated filter values: INBOUND, OUTBOUND_WITH_CALLBACK, OUTBOUND_WITH_CALLBACK_STAGING, OUTBOUND_WITH_CALLBACK_DEVELOPMENT, ALL'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - type: object
                    properties:
                      id:
                        type: string
                      name:
                        type:
                        - string
                        - 'null'
                      number:
                        type: string
                      caller_id:
                        type: string
                        enum:
                        - us
                        - them
                      toll_free_verification:
                        type: object
                        properties:
                          status:
                            type: string
                        additionalProperties: false
                      type:
                        type: string
                        enum:
                        - twilio
                      has_sip_trunk_in_preferred_region:
                        type: boolean
                      sip_trunk_status:
                        type: string
                        enum:
                        - valid
                        - invalid
                        - none
                    required:
                    - id
                    - name
                    - number
                    - caller_id
                    - type
                    - has_sip_trunk_in_preferred_region
                    - sip_trunk_status
                    additionalProperties: false
                  - type: object
                    properties:
                      id:
                        type: string
                      name:
                        type:
                        - string
                        - 'null'
                      number:
                        type: string
                      caller_id:
                        type: string
                        enum:
                        - us
                        - them
                      toll_free_verification:
                        type: object
                        properties:
                          status:
                            type: string
                        additionalProperties: false
                      type:
                        type: string
                        enum:
                        - telnyx
                    required:
                    - id
                    - name
                    - number
                    - caller_id
                    - type
                    additionalProperties: false
                  - type: object
                    properties:
                      id:
                        type: string
                      name:
                        type:
                        - string
                        - 'null'
                      number:
                        type: string
                      caller_id:
                        type: string
                        enum:
                        - us
                        - them
                      toll_free_verification:
                        type: object
                        properties:
                          status:
                            type: string
                        additionalProperties: false
                      type:
                        type: string
                        enum:
                        - sip
                      inbound_trunk_id:
                        type:
                        - string
                        - 'null'
                      outbound_trunk_id:
                        type:
                        - string
                        - 'null'
                      org_id:
                        type: string
                      created_at:
                        type: string
                      updated_at:
                        type: string
                    required:
                    - id
                    - name
                    - number
                    - caller_id
                    - type
                    - inbound_trunk_id
                    - outbound_trunk_id
                    - org_id
                    - created_at
                    - updated_at
                    additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
    post:
      summary: Purchase a phone number
      tags:
      - Phone Numbers
      description: Purchases a new phone number from Twilio or Telnyx. For toll-free numbers (US/CA only), also submits toll-free verification. Rate limited to one purchase every 10 minutes per organization. Send force=true in the body to bypass this limit (use with caution — each number has a recurring monthly cost).
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  name:
                    type: string
                    minLength: 1
                  area_code:
                    type: string
                  number_type:
                    type: string
                    enum:
                    - regular
                    - toll_free
                  provider:
                    type: string
                    enum:
                    - twilio
                  country_code:
                    default: US
                    type: string
                    minLength: 2
                    maxLength: 2
                  phone_number_type:
                    type: string
                    enum:
                    - local
                    - toll_free
                    - national
                    - mobile
                  bundle_id:
                    type:
                    - string
                    - 'null'
                  address_sid:
                    type:
                    - string
                    - 'null'
                  business_profile_application_id:
                    description: Approved Twilio Compliance Business Profile application ID. Only used when provider is twilio; US Twilio numbers without one cannot call US destinations until a Business Profile is assigned.
                    type:
                    - string
                    - 'null'
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  force:
                    description: 'Set to true to bypass the 10-minute rate limit between phone number purchases. Use with caution: each phone number incurs a recurring monthly cost.'
                    type: boolean
                  sms_url:
                    type: string
                  sms_method:
                    default: POST
                    type: string
                    enum:
                    - POST
                    - GET
                  sms_fallback_url:
                    type: string
                  sms_fallback_method:
                    default: POST
                    type: string
                    enum:
                    - POST
                    - GET
                  business_name:
                    type: string
                  business_website:
                    type: string
                  business_address_line_1:
                    type: string
                  business_address_line_2:
                    type: string
                  business_city:
                    type: string
                  business_state:
                    type: string
                  business_postal_code:
                    type: string
                  business_country:
                    default: US
                    type: string
                  business_type:
                    type: string
                    enum:
                    - PRIVATE_PROFIT
                    - PUBLIC_PROFIT
                    - SOLE_PROPRIETOR
                    - NON_PROFIT
                    - GOVERNMENT
                  business_registration_number:
                    type: string
                  business_registration_authority:
                    type: string
                    enum:
                    - EIN
                    - CBN
                    - CRN
                    - PROVINCIAL_NUMBER
                    - VAT
                    - ACN
                    - ABN
                    - BRN
                    - SIREN
                    - SIRET
                    - NZBN
                    - USt-IdNr
                    - CIF
                    - NIF
                    - CNPJ
                    - UID
                    - NEQ
                    - OTHER
                  business_registration_country:
                    type: string
                    minLength: 2
                    maxLength: 2
                  contact_first_name:
                    type: string
                  contact_last_name:
                    type: string
                  contact_email:
                    type: string
                  contact_phone:
                    type: string
                  notification_email:
                    type: string
                  message_volume:
                    type: string
                  use_categories:
                    type: array
                    items:
                      type: string
                  workflow_summary:
                    type: string
                  production_message_sample:
                    type: string
                  opt_in_type:
                    type: string
                    enum:
                    - VERBAL
                    - WEB_FORM
                    - PAPER_FORM
                    - VIA_TEXT
                    - MOBILE_QR_CODE
                    - IMPORT
                    - IMPORT_PLEASE_REPLACE
                  opt_in_image_url:
                    type: string
                  additional_information:
                    type: string
                required:
                - name
                - number_type
                - provider
                - phone_number_type
              - type: object
                properties:
                  name:
                    type: string
                    minLength: 1
                  area_code:
                    type: string
                  number_type:
                    type: string
                    enum:
                    - regular
                    - toll_free
                  provider:
                    type: string
                    enum:
                    - telnyx
                  country_code:
                    default: US
                    type: string
                    minLength: 2
                    maxLength: 2
                  phone_number_type:
                    type: string
                    enum:
                    - local
                    - toll_free
                    - national
                    - mobile
                  bundle_id:
                    type:
                    - string
                    - 'null'
                  address_sid:
                    type:
                    - string
                    - 'null'
                  business_profile_application_id:
                    description: Approved Twilio Compliance Business Profile application ID. Only used when provider is twilio; US Twilio numbers without one cannot call US destinations until a Business Profile is assigned.
                    type:
                    - string
                    - 'null'
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  force:
                    description: 'Set to true to bypass the 10-minute rate limit between phone number purchases. Use with caution: each phone number incurs a recurring monthly cost.'
                    type: boolean
                required:
                - name
                - number_type
                - provider
                - phone_number_type
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  verification_failed:
                    type: boolean
                  setup_price:
                    type: number
                  recurring_price:
                    type: number
                required:
                - message
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
  /phone-numbers/validate-toll-free-numbers:
    post:
      summary: Validate toll-free numbers for TextAgent
      tags:
      - Phone Numbers
      description: Validates toll-free phone numbers for use with TextAgent SMS. Outbound numbers are always valid. Inbound numbers are blocked if a live inbound TextAgent already uses them.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_numbers:
                  minItems: 1
                  type: array
                  items:
                    type: string
                message_direction:
                  type: string
                  enum:
                  - inbound
                  - outbound
              required:
              - phone_numbers
              - message_direction
        required: true
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    phone_number:
                      type: string
                    is_valid:
                      type: boolean
                    reason:
                      type: string
                    conflict_info:
                      type: object
                      properties:
                        workflow:
                          type: object
                          properties:
                            name:
                              type: string
                            slug:
                              type: string
                          required:
                          - name
                          - slug
                          additionalProperties: false
                        version:
                          type: object
                          properties:
                            name:
                              type: string
                            version_number:
                              type:
                              - number
                              - 'null'
                            environment:
                              type: string
                            slug:
                              type: string
                          required:
                          - name
                          - version_number
                          - environment
                          - slug
                          additionalProperties: false
                        event:
                          type: object
                          properties:
                            name:
                              type: string
                            id:
                              type: string
                          required:
                          - name
                          - id
                          additionalProperties: false
                        status:
                          type: string
                          enum:
                          - draft
                          - locked
                          - live
                        phone_number:
                          type: string
                        channel:
                          type: string
                          enum:
                          - sms
                        message_direction:
                          type: string
                          enum:
                          - inbound
                          - outbound
                        provider:
                          type: string
                          enum:
                          - use_existing_toll_free
                      required:
                      - workflow
                      - version
                      - event
                      - status
                      - phone_number
                      - channel
                      - message_direction
                      - provider
                      additionalProperties: false
                  required:
                  - phone_number
                  - is_valid
                  additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
  /phone-numbers/tollfree-verification/{verification_sid}:
    delete:
      summary: Delete a toll-free verification
      tags:
      - Phone Numbers
      description: Deletes a toll-free verification request by its SID.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: verification_sid
        required: true
        description: Toll-free verification SID
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
  /phone-numbers/free-up-number:
    post:
      summary: Free up a phone number
      tags:
      - Phone Numbers
      description: Removes a phone number from all workflows it is assigned to. The phone number must not be used in any live version.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: phone_number_id
        required: true
        description: Phone number ID (Twilio SID or Telnyx ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
  /phone-numbers/delete-number:
    post:
      summary: Delete a phone number
      tags:
      - Phone Numbers
      description: Permanently deletes a phone number. The phone number must not be in use by any workflow.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: phone_number_id
        required: true
        description: Phone number ID (Twilio SID or Telnyx ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  details: {}
                required:
                - error
                additionalProperties: false
  /phone-numbers/usage:
    get:
      summary: Get phone number usage
      tags:
      - Phone Numbers
      description: Returns usage information for a phone number across all workflows and versions.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: phone_number_id
        required: true
        description: Phone number ID (Twilio SID or Telnyx ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    workflow:
                      type: object
                      properties:
                        name:
                          type: string
                        slug:
                          type: string
                      required:
                      - name
                      - slug
                      additionalProperties: false
                    version:
                      type: object
                      properties:
                        name:
                          type: string
                        version_number:
                          type:
                          - number
                          - 'null'
                        environment:
                          type: string
                        slug:
                          type: string
                      required:
                      - name
                      - version_number
                      - environment
                      - slug
                      additionalProperties: false
                    event:
                      type: object
                      properties:
                        name:
                          type: string
                      required:
                      - name
                      additionalProperties: false
                    status:
                      type: string
                      enum:
                      - draft
                      - locked
                      - live
                  required:
                  - workflow
                  - version
                  - event
                  - status
                  additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: integer
                  

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/happyrobot/refs/heads/main/openapi/happyrobot-phone-numbers-api-openapi.yml