External Connections

External Connection Operations

List External Connections

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.

SecuritybearerAuth
Request
query Parameters
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

filter[connection_name][contains]
string
Default: null

If present, connections with connection_name containing the given value will be returned. Matching is not case-sensitive. Requires at least three characters.

sort
string
Default: "created_at"

Specifies the sort order for results. By default sorting direction is ascending. To have the results sorted in descending order add the - prefix.

That is:

  • connection_name: sorts the result by the connection_name field in ascending order.

  • -connection_name: sorts the result by the connection_name field in descending order.

If not given, results are sorted by created_at in descending order.
Enum: "created_at" "connection_name" "active"
Example: sort=connection_name
external_sip_connection
string

Filter by external_sip_connection type

Enum: "zoom" "operator_connect"
Responses
200

Successful response with details about multiple External connections.

Response Schema: application/json
Array of objects (External Connection)
object (Cursor Pagination Meta)
401

Unauthorized

422

Bad request

get/external_connections
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "1293384261075731499",
      • "record_type": "external_connection",
      • "external_sip_connection": "zoom",
      • "connection_name": "My Connection",
      • "active": true,
      • "credential_active": true,
      • "numbers_count": 1,
      • "inbound": {
        • "channel_limit": 10,
        • "shaken_stir_enabled": true
        },
      • "outbound": {
        • "channel_limit": 10,
        • "outbound_voice_profile_id": 1293384261075731500
        },
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
List External Connection Log Messages
Returns a list of log messages that are associated with any external connection the user owns.


SecuritybearerAuth 
Request 
query Parameters
page[number]
integer  >= 1 
 Default:  1
The page number to load


 
page[size]
integer  [ 1 .. 250 ] 
 Default:  20
The size of the page


 
filter[external_connection_id]
string
Filter for a specific external connection ID


 
filter[telephone_number][eq]
string
Filter for messages associated with a specific telephone number


 
filter[telephone_number][contains]
string
Filter for messages associated with a telephone number that contains a specific string


 
Responses 
200
Successful response with details about log messages on external connections.


Response Schema: application/json
Array of objects (External Connection Log Message) 
 
object (Cursor Pagination Meta) 
 
401
Unauthorized


422
Bad request


get/external_connections/log_messages
Request samples 
Response samples 
application/json
{
  • "log_messages": [
    • {
      • "code": "string",
      • "title": "string",
      • "detail": "string",
      • "source": {
        • "pointer": "/attribute"
        },
      • "meta": {
        • "telephone_number": "+12345678",
        • "external_connection_id": "1293384261075731499",
        • "ticket_id": "542c3bca-d247-42bc-8fe7-e01d16ecd76"
        }
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
Get an External Connection Log Message
Returns a single log message that is associated with an external connection the user owns.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection log message to retrieve.


 
Responses 
200
Successful response with details about a log message on external connections.


Response Schema: application/json
Array of objects (External Connection Log Message)   = 1 items 
 
object (Cursor Pagination Meta) 
 
401
Unauthorized


404
Resource not found


422
Bad request


get/external_connections/log_messages/{id}
Request samples 
Response samples 
application/json
{
  • "log_messages": [
    • {
      • "code": "string",
      • "title": "string",
      • "detail": "string",
      • "source": {
        • "pointer": "/attribute"
        },
      • "meta": {
        • "telephone_number": "+12345678",
        • "external_connection_id": "1293384261075731499",
        • "ticket_id": "542c3bca-d247-42bc-8fe7-e01d16ecd76"
        }
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
Dismiss an External Connection Log Message
Dismisses a log message that is associated with an external connection the user owns.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection log message to dismiss.


 
Responses 
200
Successful Response


Response Schema: application/json
success
boolean
Whether the log message was successfully dismissed.


 
401
Unauthorized


404
Resource not found


422
Bad request


delete/external_connections/log_messages/{id}
Request samples 
Response samples 
application/json
{
  • "success": true
}
Retrieve an External connection
Retrieves the details of an existing External connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
External Connection ID


 
Responses 
200
Successful response with details about an External connection.


Response Schema: application/json
object (External Connection) 
 
id
string <int64> 
The unique identifier for the External connection.


 
record_type
string
Identifies the type of the resource.


 
external_sip_connection
string
The service which is consuming this connection


 Enum: "zoom" "operator_connect"  
connection_name
string
The name of the connection.


 
active
boolean
Whether the connection is active. If false, the connection will not be used.


 
credential_active
boolean
 Default:  false
If the credential associated with this service is active.


 
numbers_count
integer
The number of numbers associated with this connection, only included if the query parameter "include[number_counts]=true" is present.


 
object
Inbound settings for the connection.


 
object
Outbound settings for the connection.


 
created_at
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
string
ISO 8601 formatted date indicating when the resource was last updated.


 
401
Unauthorized


404
Resource not found


422
Bad request


get/external_connections/{id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "external_connection",
    • "external_sip_connection": "zoom",
    • "connection_name": "My Connection",
    • "active": true,
    • "credential_active": true,
    • "numbers_count": 1,
    • "inbound": {
      • "channel_limit": 10,
      • "shaken_stir_enabled": true
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": 1293384261075731500
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Update an External connection
Updates the specified External connection by setting the values of the parameters passed. Any parameters not provided will be left unchanged.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
External Connection ID


 
Request Body schema: application/json
active
boolean
Defaults to true


 
object
Inbound settings for the connection. If not provided, the existing settings will be left unchanged.


 
object
Outbound settings for the connection. If not provided, the existing settings will be left unchanged.


 
Responses 
200
Successful response with details about an External connection.


Response Schema: application/json
object (External Connection) 
 
id
string <int64> 
The unique identifier for the External connection.


 
record_type
string
Identifies the type of the resource.


 
external_sip_connection
string
The service which is consuming this connection


 Enum: "zoom" "operator_connect"  
connection_name
string
The name of the connection.


 
active
boolean
Whether the connection is active. If false, the connection will not be used.


 
credential_active
boolean
 Default:  false
If the credential associated with this service is active.


 
numbers_count
integer
The number of numbers associated with this connection, only included if the query parameter "include[number_counts]=true" is present.


 
object
Inbound settings for the connection.


 
object
Outbound settings for the connection.


 
created_at
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
string
ISO 8601 formatted date indicating when the resource was last updated.


 
401
Unauthorized


404
Resource not found


422
Bad request


patch/external_connections/{id}
Request samples 
application/json
{
  • "active": true,
  • "inbound": {
    • "channel_limit": 0,
    • "shaken_stir_enabled": true
    },
  • "outbound": {
    • "channel_limit": 0,
    • "outbound_voice_profile_id": "string"
    }
}
Response samples 
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "external_connection",
    • "external_sip_connection": "zoom",
    • "connection_name": "My Connection",
    • "active": true,
    • "credential_active": true,
    • "numbers_count": 1,
    • "inbound": {
      • "channel_limit": 10,
      • "shaken_stir_enabled": true
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": 1293384261075731500
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Delete an External connection
Deletes the specified External connection object.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
External Connection ID


 
Responses 
200
Successful response with details about an External connection.


Response Schema: application/json
object (External Connection) 
 
id
string <int64> 
The unique identifier for the External connection.


 
record_type
string
Identifies the type of the resource.


 
external_sip_connection
string
The service which is consuming this connection


 Enum: "zoom" "operator_connect"  
connection_name
string
The name of the connection.


 
active
boolean
Whether the connection is active. If false, the connection will not be used.


 
credential_active
boolean
 Default:  false
If the credential associated with this service is active.


 
numbers_count
integer
The number of numbers associated with this connection, only included if the query parameter "include[number_counts]=true" is present.


 
object
Inbound settings for the connection.


 
object
Outbound settings for the connection.


 
created_at
string
ISO 8601 formatted date indicating when the resource was created.


 
updated_at
string
ISO 8601 formatted date indicating when the resource was last updated.


 
401
Unauthorized


404
Resource not found


405
Method not allowed


422
Bad request


delete/external_connections/{id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "external_connection",
    • "external_sip_connection": "zoom",
    • "connection_name": "My Connection",
    • "active": true,
    • "credential_active": true,
    • "numbers_count": 1,
    • "inbound": {
      • "channel_limit": 10,
      • "shaken_stir_enabled": true
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": 1293384261075731500
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
List External Connection Civic Addresses
Returns all civic addresses associated with the external connection on Microsoft Teams.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve civic addresses for.


 
Responses 
200
Successful response with Civic Addresses associated with the External connection.


Response Schema: application/json
Array of objects (External Connection Civic Address) 
 
 Array 
id
string <uuid> 
The unique identifier of the Civic Address.


 
record_type
string
Identifies the type of the resource.


 
country
string
The country of the Civic Address.


 
house_number
string
The house number of the Civic Address.


 
house_number_suffix
string
The house number suffix of the Civic Address.


 
street_name
string
The street name of the Civic Address.


 
street_suffix
string
The street suffix of the Civic Address.


 
state_or_province
string
The state or province of the Civic Address.


 
county_or_district
string
The county or district of the Civic Address.


 
city_or_town
string
The city or town of the Civic Address.


 
city_or_town_alias
string
The city or town alias of the Civic Address.


 
postal_or_zip_code
string
The postal or zip code of the Civic Address.


 
description
string
A description of the Civic Address.


 
company_name
string
The company name of the Civic Address.


 
default_location_id
string <uuid> 
The default location ID of the Civic Address.


 
Array of objects (External Connection Civic Address Location) 
The locations associated with the Civic Address.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/civic_addresses
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "record_type": "civic_address",
      • "country": "US",
      • "house_number": "123",
      • "house_number_suffix": "A",
      • "street_name": "Main St",
      • "street_suffix": "NW",
      • "state_or_province": "NM",
      • "county_or_district": "Bernalillo",
      • "city_or_town": "Albuquerque",
      • "city_or_town_alias": "Albuquerque",
      • "postal_or_zip_code": "87101",
      • "description": "My Home",
      • "company_name": "My Company",
      • "default_location_id": "b337e51f-abcd-e123-7d28-28106ecc5a30",
      • "locations": [
        • {
          • "id": "123e4567-e89b-12d3-a456-426614174000",
          • "additional_info": "Suite 100",
          • "description": "Conference Room",
          • "is_default": true
          }
        ]
      }
    ]
}
Get External Connection Civic Address
Returns a specific civic addresses associated with the external connection on Microsoft Teams.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve civic addresses for.


 
civic_address_id
required
string
The ID of the civic address to retrieve.


 
Responses 
200
Successful response with one Civic Addresses associated with the External connection.


Response Schema: application/json
object (External Connection Civic Address) 
 
id
string <uuid> 
The unique identifier of the Civic Address.


 
record_type
string
Identifies the type of the resource.


 
country
string
The country of the Civic Address.


 
house_number
string
The house number of the Civic Address.


 
house_number_suffix
string
The house number suffix of the Civic Address.


 
street_name
string
The street name of the Civic Address.


 
street_suffix
string
The street suffix of the Civic Address.


 
state_or_province
string
The state or province of the Civic Address.


 
county_or_district
string
The county or district of the Civic Address.


 
city_or_town
string
The city or town of the Civic Address.


 
city_or_town_alias
string
The city or town alias of the Civic Address.


 
postal_or_zip_code
string
The postal or zip code of the Civic Address.


 
description
string
A description of the Civic Address.


 
company_name
string
The company name of the Civic Address.


 
default_location_id
string <uuid> 
The default location ID of the Civic Address.


 
Array of objects (External Connection Civic Address Location) 
The locations associated with the Civic Address.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/civic_addresses/{civic_address_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "record_type": "civic_address",
    • "country": "US",
    • "house_number": "123",
    • "house_number_suffix": "A",
    • "street_name": "Main St",
    • "street_suffix": "NW",
    • "state_or_province": "NM",
    • "county_or_district": "Bernalillo",
    • "city_or_town": "Albuquerque",
    • "city_or_town_alias": "Albuquerque",
    • "postal_or_zip_code": "87101",
    • "description": "My Home",
    • "company_name": "My Company",
    • "default_location_id": "b337e51f-abcd-e123-7d28-28106ecc5a30",
    • "locations": [
      • {
        • "id": "123e4567-e89b-12d3-a456-426614174000",
        • "additional_info": "Suite 100",
        • "description": "Conference Room",
        • "is_default": true
        }
      ]
    }
}
Create an External Connection Upload
Creates a new upload request to Microsoft Teams with the included phone numbers.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to create an upload request for.


 
Request Body schema: application/json
number_ids
required
Array of strings <int64>   [ 1 .. 1000 ] items 
The list of number IDs to associate with the external connection. The number IDs must be in the same account as the external connection.


 
usage
string
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"  
additional_usages
Array of strings or null
Additional use cases of the upload request, if missing will default to all available for the numbers given. NOTE: calling_user_assignment is not supported for toll free numbers.


 Enum: "calling_user_assignment" "first_party_app_assignment"  
location_id
string <uuid> 
The ID of the location to assign the phone numbers to. Either location_id or civic_address_id is required.


 
civic_address_id
string <uuid> 
The ID of the civic address to assign the phone numbers to. Either location_id or civic_address_id is required.


 
Responses 
202
Successfully created an upload request.


Response Schema: application/json
success
boolean
 
ticket_id
string <uuid> 
The ID of the now pending upload request.


 
401
Unauthorized


404
Resource not found


422
Bad request


post/external_connections/{id}/uploads
Request samples 
application/json
{
  • "number_ids": [
    • "12345678912345",
    • "12345678912346"
    ],
  • "usage": "calling_user_assignment",
  • "additional_usages": [
    • "first_party_app_assignment"
    ],
  • "location_id": "123e4567-e89b-12d3-a456-426614174000"
}
Response samples 
application/json
{
  • "success": true,
  • "ticket_id": "123e4567-e89b-12d3-a456-426614174000"
}
List External Connection Uploads
Returns a list of upload requests for the specified external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve upload requests for.


 
query Parameters
page[number]
integer  >= 1 
 Default:  1
The page number to load


 
page[size]
integer  [ 1 .. 250 ] 
 Default:  20
The size of the page


 
filter[status][eq]
string
Filter by upload request status.


 Enum: "pending_upload" "pending" "in_progress" "partial_success" "success" "error"  
filter[civic_address_id][eq]
string
Filter by civic address ID.


 
filter[location_id][eq]
string
Filter by location ID.


 
filter[phone_number][eq]
string
Filters records to those with a specified number.


 
 Example:  filter[phone_number][eq]=+12441239999
filter[phone_number][contains]
string
Filter by a partial number, requires 3 to 15 digits.


 
 Example:  filter[phone_number][contains]=+123
Responses 
200
Successful response with details about multiple Number upload requests.


Response Schema: application/json
Array of objects (Details about a Number upload request.) 
 
object (Cursor Pagination Meta) 
 
401
Unauthorized


404
Resource not found


422
Bad request


get/external_connections/{id}/uploads
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "ticket_id": "123e4567-e89b-12d3-a456-426614174000",
      • "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
      • "location_id": "123e4567-e89b-12d3-a456-426614174000",
      • "civic_address_id": "123e4567-e89b-12d3-a456-426614174000",
      • "status": "pending_upload",
      • "available_usages": [
        • "calling_user_assignment"
        ],
      • "created_at": "2019-08-24T14:15:22Z",
      • "error_code": "string",
      • "error_message": "string",
      • "tn_upload_entries": [
        • {
          • "phone_number": "string",
          • "number_id": "string",
          • "status": "pending_upload",
          • "error_code": "string",
          • "error_message": "string",
          • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
          • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
          • "internal_status": "pending_assignment"
          }
        ]
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
Get External Connection Uploads Pending Count
Get a count of upload requests which are in a pending state for a given external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve upload requests for.


 
Responses 
200
Succesfully retrieved the count of pending upload requests for the external connection.


Response Schema: application/json
object
 
pending_numbers_count
integer
The amount of phone numbers which are in a pending state for the external connection.


 
pending_orders_count
integer
The count of upload requests which are in a pending state for the external connection.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/uploads/status
Request samples 
Response samples 
application/json
{
  • "data": {
    • "pending_numbers_count": 0,
    • "pending_orders_count": 0
    }
}
Refresh External Connection Uploads
Force a refresh of the state for all upload requests which are in a pending state for a given external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve upload requests for.


 
Responses 
200
Succesfully initiated a refresh of the external connection uploads.


Response Schema: application/json
success
boolean
Whether the refresh was successfully initiated.


 
401
Unauthorized


404
Resource not found


409
A refresh is already in progress for the external connection.


post/external_connections/{id}/uploads/refresh
Request samples 
Response samples 
application/json
{
  • "success": true
}
Get an External Connection Number Upload Request
Returns a single number upload request that is associated with an external connection the user owns.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection number upload request to retrieve.


 
ticket_id
required
string
The ID of the ticket associated with the number upload request to retrieve.


 
Responses 
200
Successful response with details about a single Number upload request.


Response Schema: application/json
object (Details about a Number upload request.) 
 
ticket_id
string <uuid> 
The ID of the upload request.


 
tenant_id
string <uuid> 
The ID Microsoft has associated with the external connection.


 
location_id
string <uuid> 
The ID of the location the upload request is associated with.


 
civic_address_id
string <uuid> 
The ID of the civic address the upload request is associated with.


 
status
string
The status of the upload request.


 Enum: "pending_upload" "pending" "in_progress" "partial_success" "success" "error"  
available_usages
Array of strings
The available use cases for the upload request.


Items Enum: "calling_user_assignment" "first_party_app_assignment"  
created_at
string <date-time> 
The iso8601 date and time the upload request was created.


 
error_code
string
The error code associated with the upload request, if any.


 
error_message
string
The error message associated with the upload request, if any.


 
Array of objects
The list of phone numbers associated with the upload request.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/uploads/{ticket_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "ticket_id": "123e4567-e89b-12d3-a456-426614174000",
    • "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    • "location_id": "123e4567-e89b-12d3-a456-426614174000",
    • "civic_address_id": "123e4567-e89b-12d3-a456-426614174000",
    • "status": "pending_upload",
    • "available_usages": [
      • "calling_user_assignment"
      ],
    • "created_at": "2019-08-24T14:15:22Z",
    • "error_code": "string",
    • "error_message": "string",
    • "tn_upload_entries": [
      • {
        • "phone_number": "string",
        • "number_id": "string",
        • "status": "pending_upload",
        • "error_code": "string",
        • "error_message": "string",
        • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
        • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
        • "internal_status": "pending_assignment"
        }
      ]
    }
}
Retry an External Connection Upload Request
Retry a failed upload request for a given external connection. Depending how/why the upload request failed, this may or may not result in a new upload request with a different ticket_id being created.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retry an upload request for.


 
ticket_id
required
string
The ID of the upload request to retry.


 
Responses 
200
Successful response with details about a single Number upload request.


Response Schema: application/json
object (Details about a Number upload request.) 
 
ticket_id
string <uuid> 
The ID of the upload request.


 
tenant_id
string <uuid> 
The ID Microsoft has associated with the external connection.


 
location_id
string <uuid> 
The ID of the location the upload request is associated with.


 
civic_address_id
string <uuid> 
The ID of the civic address the upload request is associated with.


 
status
string
The status of the upload request.


 Enum: "pending_upload" "pending" "in_progress" "partial_success" "success" "error"  
available_usages
Array of strings
The available use cases for the upload request.


Items Enum: "calling_user_assignment" "first_party_app_assignment"  
created_at
string <date-time> 
The iso8601 date and time the upload request was created.


 
error_code
string
The error code associated with the upload request, if any.


 
error_message
string
The error message associated with the upload request, if any.


 
Array of objects
The list of phone numbers associated with the upload request.


 
401
Unauthorized


404
Resource not found


409
Conflict.


422
Bad request


post/external_connections/{id}/uploads/{ticket_id}/retry
Request samples 
Response samples 
application/json
{
  • "data": {
    • "ticket_id": "123e4567-e89b-12d3-a456-426614174000",
    • "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    • "location_id": "123e4567-e89b-12d3-a456-426614174000",
    • "civic_address_id": "123e4567-e89b-12d3-a456-426614174000",
    • "status": "pending_upload",
    • "available_usages": [
      • "calling_user_assignment"
      ],
    • "created_at": "2019-08-24T14:15:22Z",
    • "error_code": "string",
    • "error_message": "string",
    • "tn_upload_entries": [
      • {
        • "phone_number": "string",
        • "number_id": "string",
        • "status": "pending_upload",
        • "error_code": "string",
        • "error_message": "string",
        • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
        • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
        • "internal_status": "pending_assignment"
        }
      ]
    }
}
List External Connection Phone Numbers
Return a list of active phone numbers associated with an external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve phone numbers for.


 
query Parameters
page[number]
integer  >= 1 
 Default:  1
The page number to load


 
page[size]
integer  [ 1 .. 250 ] 
 Default:  20
The size of the page


 
filter[phone_number][eq]
string
Filters records to those with a specified number.


 
 Example:  filter[phone_number][eq]=+12441239999
filter[phone_number][contains]
string
Filter by a partial number, requires 3 to 15 digits.


 
 Example:  filter[phone_number][contains]=+123
filter[location_id][eq]
string
Filter by location ID.


 
Responses 
200
List active phone numbers on an external connection response.


Response Schema: application/json
Array of objects (External Connection Phone Number details) 
 
object (Cursor Pagination Meta) 
 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/phone_numbers
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "record_type": "string",
      • "ticket_id": "string",
      • "telephone_number": "string",
      • "number_id": "string",
      • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
      • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
      • "displayed_country_code": "string",
      • "acquired_capabilities": [
        • "string"
        ]
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
Get an External Connection Phone Number
Get details for a single phone number associated with an external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve phone numbers for.


 
phone_number_id
required
string
The ID of the phone number to retrieve.


 
Responses 
200
Get active phone number on an external connection response.


Response Schema: application/json
object (External Connection Phone Number details) 
 
record_type
string
Identifies the type of the resource.


 
ticket_id
string
The ID of the upload request this number is associated with.


 
telephone_number
string
The phone number.


 
number_id
string
The ID of the phone number on the Telnyx API.


 
civic_address_id
string <uuid> 
The ID of the civic address associated with the phone number on Microsoft Teams.


 
location_id
string <uuid> 
The ID of the location associated with the phone number on Microsoft Teams.


 
displayed_country_code
string
The iso country code of the phone number.


 
acquired_capabilities
Array of strings
The capabilities that are available to the number on Microsoft Teams.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/phone_numbers/{phone_number_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "record_type": "string",
    • "ticket_id": "string",
    • "telephone_number": "string",
    • "number_id": "string",
    • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
    • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    • "displayed_country_code": "string",
    • "acquired_capabilities": [
      • "string"
      ]
    }
}
Update an External Connection Phone Number
Update a phone number associated with an external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve phone numbers for.


 
phone_number_id
required
string
The ID of the phone number to retrieve.


 
Request Body schema: application/json
location_id
string <uuid> 
The ID of the new location to associate the number with via Microsoft Teams.


 
Responses 
200
Get active phone number on an external connection response.


Response Schema: application/json
object (External Connection Phone Number details) 
 
record_type
string
Identifies the type of the resource.


 
ticket_id
string
The ID of the upload request this number is associated with.


 
telephone_number
string
The phone number.


 
number_id
string
The ID of the phone number on the Telnyx API.


 
civic_address_id
string <uuid> 
The ID of the civic address associated with the phone number on Microsoft Teams.


 
location_id
string <uuid> 
The ID of the location associated with the phone number on Microsoft Teams.


 
displayed_country_code
string
The iso country code of the phone number.


 
acquired_capabilities
Array of strings
The capabilities that are available to the number on Microsoft Teams.


 
401
Unauthorized


404
Resource not found


patch/external_connections/{id}/phone_numbers/{phone_number_id}
Request samples 
application/json
{
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795"
}
Response samples 
application/json
{
  • "data": {
    • "record_type": "string",
    • "ticket_id": "string",
    • "telephone_number": "string",
    • "number_id": "string",
    • "civic_address_id": "9e5bc035-bfd1-4509-a9fc-0341e88b9762",
    • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    • "displayed_country_code": "string",
    • "acquired_capabilities": [
      • "string"
      ]
    }
}
List External Connection Releases
Returns a list of number release requests for the specified external connection.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection to retrieve release requests for.


 
query Parameters
page[number]
integer  >= 1 
 Default:  1
The page number to load


 
page[size]
integer  [ 1 .. 250 ] 
 Default:  20
The size of the page


 
filter[status][eq]
string
Filter by upload request status.


 Enum: "pending_upload" "pending" "in_progress" "complete" "failed" "expired"  
filter[phone_number][eq]
string
Filters records to those with a specified number.


 
 Example:  filter[phone_number][eq]=+12441239999
filter[phone_number][contains]
string
Filter by a partial number, requires 3 to 15 digits.


 
 Example:  filter[phone_number][contains]=+123
Responses 
200
Successful response with details about multiple Number release requests.


Response Schema: application/json
Array of objects (Details about a Number Release request.) 
 
object (Cursor Pagination Meta) 
 
401
Unauthorized


404
Resource not found


422
Bad request


get/external_connections/{id}/releases
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "ticket_id": "123e4567-e89b-12d3-a456-426614174000",
      • "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
      • "status": "pending_upload",
      • "created_at": "2019-08-24T14:15:22Z",
      • "error_message": "string",
      • "phone_numbers": [
        • {
          • "phone_number": "string",
          • "number_id": "string",
          • "status": "pending_upload",
          • "error_code": "string",
          • "error_message": "string"
          }
        ]
      }
    ],
  • "meta": {
    • "cursors": {
      • "after": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
      • "before": "v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
      },
    • "total_items": 50,
    • "next": "/v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=",
    • "previous": "/v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI="
    }
}
Get an External Connection Number Release Request
Returns a single number release request that is associated with an external connection the user owns.


SecuritybearerAuth 
Request 
path Parameters
id
required
string
The ID of the external connection number release request to retrieve.


 
ticket_id
required
string
The ID of the ticket associated with the number upload request to retrieve.


 
Responses 
200
Successful response with details about a Number release request.


Response Schema: application/json
object (Details about a Number Release request.) 
 
ticket_id
string <uuid> 
The ID of the release request.


 
tenant_id
string <uuid> 
The ID Microsoft has associated with the external connection.


 
status
string
The status of the release request.


 Enum: "pending_upload" "pending" "in_progress" "complete" "failed" "expired" "unknown"  
created_at
string <date-time> 
The iso8601 date and time the release request was created.


 
error_message
string
The error message associated with the release request, if any.


 
Array of objects
The list of phone numbers associated with the release request.


 
401
Unauthorized


404
Resource not found


get/external_connections/{id}/releases/{ticket_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "ticket_id": "123e4567-e89b-12d3-a456-426614174000",
    • "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
    • "status": "pending_upload",
    • "created_at": "2019-08-24T14:15:22Z",
    • "error_message": "string",
    • "phone_numbers": [
      • {
        • "phone_number": "string",
        • "number_id": "string",
        • "status": "pending_upload",
        • "error_code": "string",
        • "error_message": "string"
        }
      ]
    }
}