Synthflow Phone Numbers API

openapi: 3.2.0
info:
  title: PLATFORM Phone Numbers API
  version: 1.0.0
servers:
- url: https://api.synthflow.ai/v2
  description: Global
- url: https://api.us.synthflow.ai/v2
  description: United States
- url: https://api.eu.synthflow.ai/v2
  description: European Union
tags:
- name: phoneNumbers
paths:
  /numbers:
    get:
      operationId: get-numbers
      summary: List phone numbers
      description: Lists all phone numbers assigned to a workspace.
      tags:
      - phoneNumbers
      parameters:
      - name: workspace
        in: query
        description: Workspace ID.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Phone numbers displayed per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: Index of the first phone number to be returned.
        required: false
        schema:
          type: integer
          default: 0
      - name: is_available
        in: query
        description: 'Filters phone numbers by inbound availability.

          - `true`: only numbers not assigned to inbound agents

          - `false`: only numbers assigned to inbound agents

          '
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone-Numbers_get-numbers_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-numbersRequestBadRequestError'
  /numbers/{phone_number_slug}:
    get:
      operationId: get-phone-number
      summary: Get a phone number
      description: Retrieves detailed information about a specific phone number.
      tags:
      - phoneNumbers
      parameters:
      - name: phone_number_slug
        in: path
        description: The phone number slug (phone number without the leading +).
        required: true
        schema:
          type: string
      - name: workspace
        in: query
        description: Workspace ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone-Numbers_get-phone-number_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-phone-numberRequestBadRequestError'
    patch:
      operationId: update-phone-number
      summary: Update a phone number
      description: Updates the configuration of a phone number.
      tags:
      - phoneNumbers
      parameters:
      - name: phone_number_slug
        in: path
        description: The phone number slug (phone number without the leading +).
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone-Numbers_update-phone-number_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-phone-numberRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                friendly_name:
                  type: string
                  description: A human-readable name for the phone number.
                sip_auth_username:
                  type: string
                  description: SIP authentication username.
                sip_outbound_proxy:
                  type: string
                  description: SIP outbound proxy.
                sip_term_uri:
                  type: string
                  description: SIP termination URI / SIP domain. Required when changing the SIP domain for providers other than `five9`, `ringcx`, and `zoom`. You may also send `termination_uri` as an alias; it is mapped to `sip_term_uri`.
                termination_uri:
                  type: string
                  description: Alias for `sip_term_uri` (SIP domain). Required when setting the domain for providers other than `five9`, `ringcx`, and `zoom`.
                provider_name:
                  $ref: '#/components/schemas/NumbersPhoneNumberSlugPatchRequestBodyContentApplicationJsonSchemaProviderName'
                  description: Telephony provider. When set to a non-auto provider without a SIP domain, the request fails with 400.
                trunk_username:
                  type: string
                  description: SIP trunk username for authentication. Required when enabling `uac_enabled`.
                trunk_pwd:
                  type: string
                  description: SIP trunk password for authentication. Required when enabling `uac_enabled`.
                uac_enabled:
                  type: boolean
                  description: When true, Synthflow sends outbound SIP REGISTER traffic to your carrier or PBX. Requires `trunk_username` and `trunk_pwd` when enabling registration.
                uac_register_expires:
                  type: integer
                  description: SIP registration refresh interval in seconds. Whole numbers only, between 60 and 3600. Defaults to 300.
    delete:
      operationId: delete-phone-number
      summary: Delete a phone number
      description: Deletes a phone number from your workspace. This will detach the phone number from any agents it is linked to. For phone numbers purchased through Synthflow, this also cancels the monthly subscription.
      tags:
      - phoneNumbers
      parameters:
      - name: phone_number_slug
        in: path
        description: The phone number slug (phone number without the leading +).
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone-Numbers_delete-phone-number_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-phone-numberRequestBadRequestError'
  /custom-numbers:
    post:
      operationId: create-custom-number
      summary: Import phone number
      description: Imports a phone number into your workspace for direct SIP dialing when your telephony provider does not offer elastic SIP trunking. Set `provider_name` to select the provider. For `five9`, `ringcx`, and `zoom`, Synthflow auto-fills the SIP domain (and for Five9, the outbound TLS proxy) from the deployment region, so you only need `workspace_id`, `phone_number`, `provider_name`, and optionally `friendly_name`. Credentials are not required for those providers. For `custom` trunks, set `uac_enabled` to true when your carrier or PBX requires outbound SIP REGISTER traffic, and optionally set `uac_register_expires` (60 to 3600 seconds, default 300).
      tags:
      - phoneNumbers
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone-Numbers_create-custom-number_Response_200'
        '400':
          description: Invalid request. Returned when `termination_uri` is missing for a provider that requires it, or when UAC registration fields are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-custom-numberRequestBadRequestError'
        '403':
          description: The selected provider import is not enabled for this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-custom-numberRequestForbiddenError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: string
                  description: The workspace ID to associate the phone number with.
                phone_number:
                  type: string
                  description: The phone number to import. For most providers use E.164. Five9 and Zoom also accept non-E.164 integration or extension identifiers.
                friendly_name:
                  type: string
                  description: A human-readable name for the phone number.
                provider_name:
                  $ref: '#/components/schemas/CustomNumbersPostRequestBodyContentApplicationJsonSchemaProviderName'
                  description: Telephony provider for the imported number. Omit or use `custom` for a bring-your-own SIP trunk. Use `five9`, `ringcx`, or `zoom` for those integrations; SIP domain defaults are applied automatically for those three only.
                trunk_username:
                  type: string
                  description: Optional SIP trunk username for authentication. Required when `uac_enabled` is true. Not used for `five9`, `ringcx`, or `zoom`.
                trunk_pwd:
                  type: string
                  description: Optional SIP trunk password for authentication. Required when `uac_enabled` is true. Not used for `five9`, `ringcx`, or `zoom`.
                termination_uri:
                  type: string
                  description: SIP domain or termination URI used for outbound calls (maps to `sip_term_uri`). Required for `custom`, `twilio`, `telnyx`, `vonage`, and `ring_central`. Optional for `five9` (regional IP), `ringcx` (`sip.ringcentral.com`), and `zoom` (`sip.zoom.com`), which are filled automatically when omitted. Requests that omit it for a non-auto provider return 400.
                sip_outbound_proxy:
                  type: string
                  description: Optional outbound proxy used for outbound calls and SIP REGISTER requests. For `five9`, Synthflow sets the regional TLS proxy automatically when omitted.
                sip_auth_username:
                  type: string
                  description: Optional auth username used for SIP REGISTER requests when it differs from `trunk_username`.
                uac_enabled:
                  type: boolean
                  default: false
                  description: When true, Synthflow sends outbound SIP REGISTER traffic to your carrier or PBX so it can authenticate outbound calls. Requires `trunk_username` and `trunk_pwd`. Defaults to false.
                uac_register_expires:
                  type: integer
                  default: 300
                  description: SIP registration refresh interval in seconds. Only used when `uac_enabled` is true (or for providers that register implicitly, such as RingCentral). Whole numbers only, between 60 and 3600. Defaults to 300.
              required:
              - workspace_id
              - phone_number
components:
  schemas:
    Create-custom-numberRequestForbiddenError:
      type: object
      properties: {}
      title: Create-custom-numberRequestForbiddenError
    NumbersPhoneNumberSlugPatchRequestBodyContentApplicationJsonSchemaProviderName:
      type: string
      enum:
      - twilio
      - telnyx
      - vonage
      - ring_central
      - ringcx
      - custom
      - zoom
      - five9
      description: Telephony provider. When set to a non-auto provider without a SIP domain, the request fails with 400.
      title: NumbersPhoneNumberSlugPatchRequestBodyContentApplicationJsonSchemaProviderName
    Create-custom-numberRequestBadRequestError:
      type: object
      properties: {}
      title: Create-custom-numberRequestBadRequestError
    NumbersGetResponsesContentApplicationJsonSchemaResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/NumbersGetResponsesContentApplicationJsonSchemaResponsePagination'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/NumbersGetResponsesContentApplicationJsonSchemaResponsePhoneNumbersItems'
      title: NumbersGetResponsesContentApplicationJsonSchemaResponse
    Phone-Numbers_get-numbers_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/NumbersGetResponsesContentApplicationJsonSchemaResponse'
      title: Phone-Numbers_get-numbers_Response_200
    Phone-Numbers_delete-phone-number_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
      title: Phone-Numbers_delete-phone-number_Response_200
    Phone-Numbers_create-custom-number_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/CustomNumbersPostResponsesContentApplicationJsonSchemaResponse'
      title: Phone-Numbers_create-custom-number_Response_200
    Update-phone-numberRequestBadRequestError:
      type: object
      properties: {}
      title: Update-phone-numberRequestBadRequestError
    NumbersGetResponsesContentApplicationJsonSchemaResponsePhoneNumbersItems:
      type: object
      properties:
        number:
          type: string
          description: Phone number.
        sid:
          type:
          - string
          - 'null'
          description: Phone number SID. May be null for custom numbers.
        is_available:
          type: boolean
          description: Whether the number is available for inbound assignment.
      title: NumbersGetResponsesContentApplicationJsonSchemaResponsePhoneNumbersItems
    Get-numbersRequestBadRequestError:
      type: object
      properties: {}
      title: Get-numbersRequestBadRequestError
    status:
      type: string
      description: Whether the request was successful.
      title: status
    Phone-Numbers_get-phone-number_Response_200:
      type: object
      properties:
        slug:
          type: string
          description: The phone number slug (phone number without the leading +).
        address_requirement:
          type: string
          description: Address requirement for the phone number.
        phone_number:
          type: string
          description: The full phone number in E.164 format.
        friendly_name:
          type: string
          description: A human-readable name for the phone number.
        is_sms_capable:
          type: boolean
          description: Whether the phone number can send and receive SMS.
        is_voice_capable:
          type: boolean
          description: Whether the phone number can make and receive voice calls.
        iso_country:
          type: string
          description: ISO country code for the phone number.
        locality:
          type: string
          description: The locality or city associated with the phone number.
        sip_auth_username:
          type:
          - string
          - 'null'
          description: SIP authentication username, if configured.
        sip_outbound_proxy:
          type:
          - string
          - 'null'
          description: SIP outbound proxy, if configured.
        sip_term_uri:
          type: string
          description: SIP termination URI.
        uac_enabled:
          type: boolean
          description: Whether outbound SIP registration (REGISTER) is enabled for this number.
        uac_register_expires:
          type:
          - integer
          - 'null'
          description: SIP registration refresh interval in seconds when registration is enabled.
        sid:
          type: string
          description: Phone number SID from the provider.
        provider_name:
          type: string
          description: Name of the telephony provider. Common values include `twilio`, `telnyx`, `vonage`, `ring_central`, `ringcx`, `custom`, `zoom`, and `five9`.
        region:
          type: string
          description: The region associated with the phone number.
        is_available:
          type: boolean
          description: Whether the number is available for inbound assignment.
        agency_workspace_id:
          type:
          - string
          - 'null'
          description: Agency workspace ID, if applicable.
        workspace_id:
          type: string
          description: The workspace ID the phone number belongs to.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the phone number was created.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the phone number was last updated.
        assistants:
          type: array
          items:
            type: string
            format: uuid
          description: List of assistant IDs attached to this phone number.
      title: Phone-Numbers_get-phone-number_Response_200
    CustomNumbersPostResponsesContentApplicationJsonSchemaResponse:
      type: object
      properties:
        key:
          type: string
          format: uuid
          description: Unique identifier for the custom phone number.
        phone_number:
          type: string
          description: The imported phone number.
      title: CustomNumbersPostResponsesContentApplicationJsonSchemaResponse
    Delete-phone-numberRequestBadRequestError:
      type: object
      properties: {}
      title: Delete-phone-numberRequestBadRequestError
    Phone-Numbers_update-phone-number_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
      title: Phone-Numbers_update-phone-number_Response_200
    Get-phone-numberRequestBadRequestError:
      type: object
      properties: {}
      title: Get-phone-numberRequestBadRequestError
    CustomNumbersPostRequestBodyContentApplicationJsonSchemaProviderName:
      type: string
      enum:
      - twilio
      - telnyx
      - vonage
      - ring_central
      - ringcx
      - custom
      - zoom
      - five9
      description: Telephony provider for the imported number. Omit or use `custom` for a bring-your-own SIP trunk. Use `five9`, `ringcx`, or `zoom` for those integrations; SIP domain defaults are applied automatically for those three only.
      title: CustomNumbersPostRequestBodyContentApplicationJsonSchemaProviderName
    NumbersGetResponsesContentApplicationJsonSchemaResponsePagination:
      type: object
      properties:
        total_records:
          type: integer
          description: Total number of phone numbers.
        limit:
          type: integer
          description: Number of phone numbers per page.
        offset:
          type: integer
          description: Index of the first phone number returned.
      title: NumbersGetResponsesContentApplicationJsonSchemaResponsePagination
  securitySchemes:
    sec0:
      type: http
      scheme: bearer