Telnyx External Connections API

openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens External Connections API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: External Connections operations
  name: External Connections
paths:
  /external_connections:
    get:
      description: This endpoint returns a list of your External Connections inside the 'data' attribute of the response. External Connections are used by Telnyx customers to seamless configure SIP trunking integrations with Telnyx Partners, through External Voice Integrations in Mission Control Portal.
      operationId: ListExternalConnections
      parameters:
      - $ref: '#/components/parameters/FilterConnectionsConsolidated'
      - $ref: '#/components/parameters/external-voice-integrations_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/GetAllExternalConnectionResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
      summary: List all External Connections
      tags:
      - External Connections
      x-endpoint-cost: medium
      x-latency-category: responsive
    post:
      description: Creates a new External Connection based on the parameters sent in the request. The external_sip_connection and outbound voice profile id are required. Once created, you can assign phone numbers to your application using the `/phone_numbers` endpoint.
      operationId: CreateExternalConnection
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalConnectionRequest'
        description: Parameters that can be set when creating a External Connection
        required: true
      responses:
        '201':
          $ref: '#/components/responses/ExternalConnectionResponse'
        '422':
          description: Bad request
      summary: Creates an External Connection
      tags:
      - External Connections
      x-endpoint-cost: medium
      x-latency-category: responsive
  /external_connections/log_messages:
    get:
      description: Retrieve a list of log messages for all external connections associated with your account.
      operationId: ListExternalConnectionLogMessages
      parameters:
      - $ref: '#/components/parameters/FilterLogMessagesConsolidated'
      - $ref: '#/components/parameters/external-voice-integrations_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/ListLogMessagesResponse'
        '401':
          description: Unauthorized
        '422':
          description: Bad request
      summary: List all log messages
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/log_messages/{id}:
    delete:
      description: Dismiss a log message for an external connection associated with your account.
      operationId: DeleteExternalConnectionLogMessage
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  success:
                    description: Describes wether or not the operation was successful
                    type: boolean
                title: Dismiss request was successful
                type: object
          description: Successful response
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
      summary: Dismiss a log message
      tags:
      - External Connections
      x-latency-category: responsive
    get:
      description: Retrieve a log message for an external connection associated with your account.
      operationId: GetExternalConnectionLogMessage
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          $ref: '#/components/responses/GetLogMessageResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
      summary: Retrieve a log message
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}:
    delete:
      description: Permanently deletes an External Connection. Deletion may be prevented if the application is in use by phone numbers, is active, or if it is an Operator Connect connection. To remove an Operator Connect integration please contact Telnyx support.
      operationId: DeleteExternalConnection
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          $ref: '#/components/responses/ExternalConnectionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Deletes an External Connection
      tags:
      - External Connections
      x-latency-category: responsive
    get:
      description: Return the details of an existing External Connection inside the 'data' attribute of the response.
      operationId: GetExternalConnection
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          $ref: '#/components/responses/ExternalConnectionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Retrieve an External Connection
      tags:
      - External Connections
      x-latency-category: responsive
    patch:
      description: Updates settings of an existing External Connection based on the parameters of the request.
      operationId: UpdateExternalConnection
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExternalConnectionRequest'
        description: Parameters to be updated for the External Connection
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ExternalConnectionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Resource not found
        '422':
          description: Bad request
      summary: Update an External Connection
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/civic_addresses:
    get:
      description: Returns the civic addresses and locations from Microsoft Teams.
      operationId: ListCivicAddresses
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/FilterCivicAddressesConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/GetAllCivicAddressesResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Unexpected Error
        '502':
          description: Bad Gateway
      summary: List all civic addresses and locations
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/civic_addresses/{address_id}:
    get:
      description: Return the details of an existing Civic Address with its Locations inside the 'data' attribute of the response.
      operationId: GetExternalConnectionCivicAddress
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/address_id'
      responses:
        '200':
          $ref: '#/components/responses/GetCivicAddressResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Unexpected Error
        '502':
          description: Bad Gateway
      summary: Retrieve a Civic Address
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/locations/{location_id}:
    patch:
      operationId: updateLocation
      parameters:
      - description: The ID of the external connection
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: The ID of the location to update
        in: path
        name: location_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                static_emergency_address_id:
                  description: A new static emergency address ID to update the location with
                  format: uuid
                  type: string
              required:
              - static_emergency_address_id
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
          description: Location successfully updated with no associated orders to process
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
          description: Location update accepted; associated orders being processed
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Location or external connection not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity - Location already has an accepted emergency address
      summary: Update a location's static emergency address
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/phone_numbers:
    get:
      description: Returns a list of all active phone numbers associated with the given external connection.
      operationId: ListExternalConnectionPhoneNumbers
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/FilterPhoneNumbersConsolidated'
      - $ref: '#/components/parameters/external-voice-integrations_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/ListExternalConnectionPhoneNumbersResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Bad request
      summary: List all phone numbers
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/phone_numbers/{phone_number_id}:
    get:
      description: Return the details of a phone number associated with the given external connection.
      operationId: GetExternalConnectionPhoneNumber
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/phone_number_id'
      responses:
        '200':
          $ref: '#/components/responses/GetExternalConnectionPhoneNumberResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      summary: Retrieve a phone number
      tags:
      - External Connections
      x-latency-category: responsive
    patch:
      description: Asynchronously update settings of the phone number associated with the given external connection.
      operationId: UpdateExternalConnectionPhoneNumber
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/phone_number_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExternalConnectionPhoneNumberRequest'
        description: Values that can be set when updating a phone number
        required: true
      responses:
        '200':
          $ref: '#/components/responses/GetExternalConnectionPhoneNumberResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Bad request
      summary: Update a phone number
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/releases:
    get:
      description: Returns a list of your Releases for the given external connection. These are automatically created when you change the `connection_id` of a phone number that is currently on Microsoft Teams.
      operationId: ListExternalConnectionReleases
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/FilterReleasesConsolidated'
      - $ref: '#/components/parameters/external-voice-integrations_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/ListReleasesResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Bad request
      summary: List all Releases
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/releases/{release_id}:
    get:
      description: Return the details of a Release request and its phone numbers.
      operationId: GetExternalConnectionRelease
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/release_id'
      responses:
        '200':
          $ref: '#/components/responses/GetReleaseResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      summary: Retrieve a Release request
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/uploads:
    get:
      description: Returns a list of your Upload requests for the given external connection.
      operationId: ListExternalConnectionUploads
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/FilterUploadsConsolidated'
      - $ref: '#/components/parameters/external-voice-integrations_PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/ListUploadsResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '422':
          description: Bad request
      summary: List all Upload requests
      tags:
      - External Connections
      x-latency-category: responsive
    post:
      description: Creates a new Upload request to Microsoft teams with the included phone numbers. Only one of civic_address_id or location_id must be provided, not both. The maximum allowed phone numbers for the numbers_ids array is 1000.
      operationId: CreateExternalConnectionUpload
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalConnectionUploadRequest'
        description: Parameters that can be set when creating an Upload request.
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  success:
                    description: Describes wether or not the operation was successful
                    type: boolean
                  ticket_id:
                    description: Ticket id of the upload request
                    format: uuid
                    type: string
                title: Create Upload request Response
                type: object
          description: Successful response
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '413':
          description: Payload too large. The maximum allowed phone numbers for the numbers_ids array is 1000.
        '422':
          description: Unprocessable Entity
        '504':
          description: Gateway Timeout
      summary: Creates an Upload request
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/uploads/refresh:
    post:
      description: Forces a recheck of the status of all pending Upload requests for the given external connection in the background.
      operationId: RefreshExternalConnectionUploads
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  success:
                    description: Describes wether or not the operation was successful
                    type: boolean
                title: Create Upload request Response
                type: object
          description: Successful response
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '409':
          description: Status refresh is still in progress, please wait before calling again
      summary: Refresh the status of all Upload requests
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/uploads/status:
    get:
      description: Returns the count of all pending upload requests for the given external connection.
      operationId: GetExternalConnectionUploadsStatus
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      responses:
        '200':
          $ref: '#/components/responses/GetUploadsStatusResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      summary: Get the count of pending upload requests
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/uploads/{ticket_id}:
    get:
      description: Return the details of an Upload request and its phone numbers.
      operationId: GetExternalConnectionUpload
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/ticket_id'
      responses:
        '200':
          $ref: '#/components/responses/GetUploadResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      summary: Retrieve an Upload request
      tags:
      - External Connections
      x-latency-category: responsive
  /external_connections/{id}/uploads/{ticket_id}/retry:
    post:
      description: If there were any errors during the upload process, this endpoint will retry the upload request. In some cases this will reattempt the existing upload request, in other cases it may create a new upload request. Please check the ticket_id in the response to determine if a new upload request was created.
      operationId: RetryUpload
      parameters:
      - $ref: '#/components/parameters/external-voice-integrations_id'
      - $ref: '#/components/parameters/ticket_id'
      responses:
        '202':
          $ref: '#/components/responses/GetUploadResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '409':
          description: Order is still in progress, please wait before retrying
        '422':
          description: Unprocessable Entity
      summary: Retry an Upload request
      tags:
      - External Connections
      x-latency-category: responsive
  /operator_connect/actions/refresh:
    post:
      description: This endpoint will make an asynchronous request to refresh the Operator Connect integration with Microsoft Teams for the current user. This will create new external connections on the user's account if needed, and/or report the integration results as [log messages](https://developers.telnyx.com/api-reference/external-connections/list-all-log-messages#list-all-log-messages).
      operationId: OperatorConnectRefresh
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: A message describing the result of the operation
                    example: Operator connect refresh already in progress
                    type: string
                  success:
                    description: Describes wether or not the operation was successful
                    example: true
                    type: boolean
                title: Operator Connect Refresh Response
                type: object
          description: Successful response
        '202':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: A message describing the result of the operation
                    example: Operator connect refresh started
                    type: string
                  success:
                    description: Describes wether or not the operation was successful
                    example: true
                    type: boolean
                title: Operator Connect Refresh Response
                type: object
          description: Successful response
        '401':
          description: Unauthorized
      summary: Refresh Operator Connect integration
      tags:
      - External Connections
      x-latency-category: responsive
components:
  schemas:
    UpdateExternalConnectionPhoneNumberRequest:
      properties:
        location_id:
          description: Identifies the location to assign the phone number to.
          format: uuid
          type: string
      title: Update External Connection Phone Number Request
      type: object
    external-voice-integrations_OutboundVoiceProfileId:
      description: Identifies the associated outbound voice profile.
      example: '1293384261075731499'
      title: Outbound Voice Profile ID
      type: string
      x-format: int64
    CreateExternalConnectionUploadRequest:
      example:
        location_id: 67ea7693-9cd5-4a68-8c76-abb3aa5bf5d2
        number_ids:
        - '3920457616934164700'
        - '3920457616934164701'
        - '3920457616934164702'
        - '3920457616934164703'
        usage: first_party_app_assignment
      properties:
        additional_usages:
          items:
            description: Additional use cases of the upload request. If not provided, all supported usages will be used.
            enum:
            - calling_user_assignment
            - first_party_app_assignment
            type: string
          type: array
        civic_address_id:
          description: Identifies the civic address to assign all phone numbers to.
          format: uuid
          type: string
        location_id:
          description: Identifies the location to assign all phone numbers to.
          format: uuid
          type: string
        number_ids:
          items:
            description: Phone number ID from the Telnyx API.
            type: string
          minItems: 1
          type: array
        usage:
          description: 'The use case of the upload request. NOTE: `calling_user_assignment` is not supported for toll free numbers.'
          enum:
          - calling_user_assignment
          - first_party_app_assignment
          type: string
      required:
      - number_ids
      title: Create Upload Request
      type: object
    CreateExternalConnectionRequest:
      example:
        active: false
        external_sip_connection: zoom
        outbound:
          outbound_voice_profile_id: '1911630617284445511'
      properties:
        active:
          $ref: '#/components/schemas/ConnectionActive'
        external_sip_connection:
          $ref: '#/components/schemas/ExternalSipConnectionZoomOnly'
        inbound:
          properties:
            channel_limit:
              default: null
              description: When set, this will limit the number of concurrent inbound calls to phone numbers associated with this connection.
              example: 10
              type: integer
            outbound_voice_profile_id:
              description: The ID of the outbound voice profile to use for inbound calls.
              example: 12345678-1234-1234-1234-123456789012
              type: string
          required:
          - outbound_voice_profile_id
          type: object
        outbound:
          properties:
            channel_limit:
              default: null
              description: When set, this will limit the number of concurrent outbound calls to phone numbers associated with this connection.
              example: 10
              type: integer
            outbound_voice_profile_id:
              $ref: '#/components/schemas/external-voice-integrations_OutboundVoiceProfileId'
          type: object
        tags:
          description: Tags associated with the connection.
          example:
          - tag1
          - tag2
          items:
            type: string
          type: array
        webhook_event_failover_url:
          default: ''
          description: The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.
          example: https://failover.example.com
          format: uri
          type:
          - string
          - 'null'
        webhook_event_url:
          description: The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.
          example: https://example.com
          format: uri
          type: string
        webhook_timeout_secs:
          default: null
          description: Specifies how many seconds to wait before timing out a webhook.
          example: 25
          maximum: 30
          minimum: 0
          type:
          - integer
          - 'null'
      required:
      - external_sip_connection
      - outbound
      title: Create External Connection Request
      type: object
    ExternalConnectionPhoneNumber:
      properties:
        acquired_capabilities:
          items:
            description: The capabilities that are available for this phone number on Microsoft Teams.
            enum:
            - FirstPartyAppAssignment
            - InboundCalling
            - Office365
            - OutboundCalling
            - UserAssignment
            type: string
          type: array
        civic_address_id:
          description: Identifies the civic address assigned to the phone number.
          format: uuid
          type: string
        displayed_country_code:
          description: The iso country code that will be displayed to the user when they receive a call from this phone number.
          type: string
        location_id:
          description: Identifies the location assigned to the phone number.
          format: uuid
          type: string
        number_id:
          description: Phone number ID from the Telnyx API.
          type: string
        telephone_number:
          description: Phone number in E164 format.
          type: string
        ticket_id:
          $ref: '#/components/schemas/UUID'
      title: Phone number details with relation to an external connection
      type: object
    CredentialActive:
      default: false
      description: If the credential associated with this service is active.
      example: true
      title: Credential Active
      type: boolean
    TnUploadEntry:
      properties:
        civic_address_id:
          description: Identifies the civic address assigned to the phone number entry.
          format: uuid
          type: string
        error_code:
          description: A code returned by Microsoft Teams if there is an error with the phone number entry upload.
          enum:
          - internal_error
          - unable_to_retrieve_default_location
          - unknown_country_code
          - unable_to_retrieve_location
          - unable_to_retrieve_partner_info
          - unable_to_match_geography_entry
          example: internal_error
          type: string
        error_message:
          description: A message returned by Microsoft Teams if there is an error with the upload process.
          type: string
        internal_status:
          default: pending_assignment
          description: Represents the status of the phone number entry upload on Telnyx.
          enum:
          - pending_assignment
          - in_progress
          - all_internal_jobs_completed
          - release_requested
          - release_completed
          - error
          example: error
          type: string
        location_id:
          description: Identifies the location assigned to the phone number entry.
          format: uuid
          type: string
        number_id:
          $ref: '#/components/schemas/UUID'
        phone_number:
          description: Phone number in E164 format.
          type: string
        status:
          default: pending_upload
          description: Represents the status of the phone number entry upload on Microsoft Teams.
          enum:
          - pending_upload
          - pending
          - in_progress
          - success
          - error
          example: error
          type: string
      title: TnUploadEntry
      type: object
    ExternalSipConnectionZoomOnly:
      default: zoom
      description: The service that will be consuming this connection.
      enum:
      - zoom
      example: zoom
      title: External SIP Connection
      type: string
    ExternalConnection:
      example:
        active: false
        created_at: '2022-06-29T19:23:59Z'
        credential_active: false
        external_sip_connection: zoom
        id: '1930241863466354012'
        outbound:
          outbound_voice_profile_id: '1911630617284445511'
        record_type: external_connection
        updated_at: '2022-06-29T19:39:47Z'
      properties:
        active:
          $ref: '#/components/schemas/ConnectionActive'
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
          type: string
        credential_active:
          $ref: '#/components/schemas/CredentialActive'
        external_sip_connection:
          $ref: '#/components/schemas/ExternalSipConnection'
        id:
          $ref: '#/components/schemas/external-voice-integrations_IntId'
        inbound:
          properties:
            channel_limit:
              default: null
              description: When set, this will limit the number of concurrent inbound calls to phone numbers associated with this connection.
              example: 10
              type: integer
          type: object
        outbound:
          properties:
            channel_limit:
              default: null
              description: When set, this will limit the number of concurrent outbound calls to phone numbers associated with this connection.
              example: 10
              type: integer
            outbound_voice_profile_id:
              $ref: '#/components/schemas/external-voice-integrations_OutboundVoiceProfileId'
          type: object
        record_type:
          description: Identifies the type of the resource.
          example: external_connection
          type: string
        tags:
          description: Tags associated with the connection.
          example:
          - tag1
          - tag2
          items:

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-external-connections-api-openapi.yml