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 IP 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: IP connection operations
name: IP Connections
paths:
/ip_connections:
get:
description: Returns a list of your IP connections.
operationId: ListIpConnections
parameters:
- $ref: '#/components/parameters/connections_FilterConsolidated'
- $ref: '#/components/parameters/connections_PageConsolidated'
- $ref: '#/components/parameters/connections_SortConnection'
responses:
'200':
$ref: '#/components/responses/ListIpConnectionsResponse'
'400':
$ref: '#/components/responses/connections_BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthenticatedResponse'
'403':
$ref: '#/components/responses/connections_UnauthorizedResponse'
summary: List Ip connections
tags:
- IP Connections
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
post:
description: Creates an IP connection.
operationId: CreateIpConnection
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIpConnectionRequest'
description: Parameters that can be defined during IP connection creation
required: true
responses:
'201':
$ref: '#/components/responses/IpConnectionResponse'
'401':
$ref: '#/components/responses/UnauthenticatedResponse'
'403':
$ref: '#/components/responses/connections_UnauthorizedResponse'
'422':
$ref: '#/components/responses/connections_UnprocessableEntityResponse'
summary: Create an Ip connection
tags:
- IP Connections
x-endpoint-cost: medium
x-latency-category: responsive
/ip_connections/{id}:
delete:
description: Deletes an existing IP connection.
operationId: DeleteIpConnection
parameters:
- description: Identifies the type of resource.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/IpConnectionResponse'
'400':
$ref: '#/components/responses/connections_BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthenticatedResponse'
'403':
$ref: '#/components/responses/connections_UnauthorizedResponse'
'404':
$ref: '#/components/responses/connections_NotFoundResponse'
summary: Delete an Ip connection
tags:
- IP Connections
x-latency-category: responsive
get:
description: Retrieves the details of an existing ip connection.
operationId: RetrieveIpConnection
parameters:
- description: IP Connection ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/IpConnectionResponse'
'400':
$ref: '#/components/responses/connections_BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthenticatedResponse'
'403':
$ref: '#/components/responses/connections_UnauthorizedResponse'
'404':
$ref: '#/components/responses/connections_NotFoundResponse'
summary: Retrieve an Ip connection
tags:
- IP Connections
x-latency-category: responsive
patch:
description: Updates settings of an existing IP connection.
operationId: UpdateIpConnection
parameters:
- description: Identifies the type of resource.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateIpConnectionRequest'
description: Parameters that can be updated in a IP connection
required: true
responses:
'200':
$ref: '#/components/responses/IpConnectionResponse'
'401':
$ref: '#/components/responses/UnauthenticatedResponse'
'403':
$ref: '#/components/responses/connections_UnauthorizedResponse'
'404':
$ref: '#/components/responses/connections_NotFoundResponse'
'422':
$ref: '#/components/responses/connections_UnprocessableEntityResponse'
summary: Update an Ip connection
tags:
- IP Connections
x-latency-category: responsive
components:
schemas:
InboundIp:
example:
ani_number_format: +E.164
channel_limit: 10
codecs:
- G722
default_primary_ip_id: 192.168.0.0
default_routing_method: sequential
default_secondary_ip_id: 192.168.0.0
default_tertiary_ip_id: 192.168.0.0
dnis_number_format: +e164
generate_ringback_tone: true
isup_headers_enabled: true
prack_enabled: true
shaken_stir_enabled: true
sip_compact_headers_enabled: true
sip_region: US
sip_subdomain: test
sip_subdomain_receive_settings: only_my_connections
timeout_1xx_secs: 10
timeout_2xx_secs: 20
properties:
ani_number_format:
default: E.164-national
description: This setting allows you to set the format with which the caller's number (ANI) is sent for inbound phone calls.
enum:
- +E.164
- E.164
- +E.164-national
- E.164-national
type: string
channel_limit:
default: null
description: When set, this will limit the total number of inbound calls to phone numbers associated with this connection.
example: 10
type: integer
codecs:
default:
- G722
- G711U
- G711A
- G729
- OPUS
- H.264
description: 'Defines the list of codecs that Telnyx will send for inbound calls to a specific number on your portal account, in priority order. This only works when the Connection the number is assigned to uses Media Handling mode: default. OPUS and H.264 codecs are available only when using TCP or TLS transport for SIP.'
items:
type: string
type: array
default_primary_ip_id:
description: "The default primary IP to use for the number. Only settable if the connection is\n of IP authentication type. Value must be the ID of an authorized IP set on the connection."
example: 192.168.0.0
type: string
default_routing_method:
description: Default routing method to be used when a number is associated with the connection. Must be one of the routing method types or left blank, other values are not allowed.
enum:
- sequential
- round-robin
type: string
default_secondary_ip_id:
description: "The default secondary IP to use for the number. Only settable if the connection is\n of IP authentication type. Value must be the ID of an authorized IP set on the connection."
example: 192.168.0.0
type: string
default_tertiary_ip_id:
description: "The default tertiary IP to use for the number. Only settable if the connection is\n of IP authentication type. Value must be the ID of an authorized IP set on the connection."
example: 192.168.0.0
type: string
dnis_number_format:
default: e164
enum:
- +e164
- e164
- national
- sip_username
type: string
generate_ringback_tone:
default: false
description: Generate ringback tone through 183 session progress message with early media.
type: boolean
isup_headers_enabled:
default: false
description: When set, inbound phone calls will receive ISUP parameters via SIP headers. (Only when available and only when using TCP or TLS transport.)
type: boolean
prack_enabled:
default: false
description: Enable PRACK messages as defined in RFC3262.
type: boolean
shaken_stir_enabled:
default: false
description: When enabled the SIP Connection will receive the Identity header with Shaken/Stir data in the SIP INVITE message of inbound calls, even when using UDP transport.
type: boolean
sip_compact_headers_enabled:
default: true
description: Defaults to true.
type: boolean
sip_region:
default: US
description: Selects which `sip_region` to receive inbound calls from. If null, the default region (US) will be used.
enum:
- US
- Europe
- Australia
type: string
sip_subdomain:
description: 'Specifies a subdomain that can be used to receive Inbound calls to a Connection, in the same way a phone number is used, from a SIP endpoint. Example: the subdomain "example.sip.telnyx.com" can be called from any SIP endpoint by using the SIP URI "sip:@example.sip.telnyx.com" where the user part can be any alphanumeric value. Please note TLS encrypted calls are not allowed for subdomain calls.'
type: string
sip_subdomain_receive_settings:
description: 'This option can be enabled to receive calls from: "Anyone" (any SIP endpoint in the public Internet) or "Only my connections" (any connection assigned to the same Telnyx user).'
enum:
- only_my_connections
- from_anyone
type: string
timeout_1xx_secs:
default: 3
description: Time(sec) before aborting if connection is not made.
maximum: 120
minimum: 1
type: integer
timeout_2xx_secs:
default: 90
description: 'Time(sec) before aborting if call is unanswered (min: 1, max: 600).'
type: integer
title: Inbound Ip
type: object
CreateIpConnectionRequest:
example:
active: true
anchorsite_override: Latency
android_push_credential_id: 06b09dfd-7154-4980-8b75-cebf7a9d4f8e
call_cost_in_webhooks: false
connection_name: string
default_on_hold_comfort_noise_enabled: true
dtmf_type: RFC 2833
encode_contact_header_enabled: true
encrypted_media: SRTP
inbound:
ani_number_format: +E.164
channel_limit: 10
codecs:
- G722
default_routing_method: sequential
dnis_number_format: +e164
generate_ringback_tone: true
isup_headers_enabled: true
prack_enabled: true
shaken_stir_enabled: true
sip_compact_headers_enabled: true
sip_region: US
sip_subdomain: test
sip_subdomain_receive_settings: only_my_connections
timeout_1xx_secs: 10
timeout_2xx_secs: 20
ios_push_credential_id: ec0c8e5d-439e-4620-a0c1-9d9c8d02a836
jitter_buffer:
enable_jitter_buffer: true
jitterbuffer_msec_max: 200
jitterbuffer_msec_min: 60
noise_suppression: both
noise_suppression_details:
attenuation_limit: 80
engine: deep_filter_net
onnet_t38_passthrough_enabled: false
outbound:
ani_override: string
ani_override_type: always
call_parking_enabled: true
channel_limit: 10
generate_ringback_tone: true
instant_ringback_enabled: true
ip_authentication_method: token
ip_authentication_token: string
localization: string
outbound_voice_profile_id: '1293384261075731499'
t38_reinvite_source: customer
tech_prefix: string
rtcp_settings:
capture_enabled: true
port: rtcp-mux
report_frequency_secs: 10
tags:
- tag1
- tag2
transport_protocol: UDP
webhook_api_version: '1'
webhook_event_failover_url: https://failover.example.com
webhook_event_url: https://example.com
webhook_timeout_secs: 25
properties:
active:
description: Defaults to true
example: true
type: boolean
anchorsite_override:
$ref: '#/components/schemas/AnchorsiteOverride'
android_push_credential_id:
$ref: '#/components/schemas/ConnectionAndroidPushCredentialId'
call_cost_in_webhooks:
default: false
description: Specifies if call cost webhooks should be sent for this connection.
type: boolean
connection_name:
example: string
type: string
default_on_hold_comfort_noise_enabled:
default: true
description: When enabled, Telnyx will generate comfort noise when you place the call on hold. If disabled, you will need to generate comfort noise or on hold music to avoid RTP timeout.
example: true
type: boolean
dtmf_type:
$ref: '#/components/schemas/DtmfType'
encode_contact_header_enabled:
default: false
description: Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG scenarios.
example: true
type: boolean
encrypted_media:
$ref: '#/components/schemas/EncryptedMedia'
inbound:
$ref: '#/components/schemas/CreateInboundIpRequest'
ios_push_credential_id:
$ref: '#/components/schemas/ConnectionIosPushCredentialId'
jitter_buffer:
$ref: '#/components/schemas/ConnectionJitterBuffer'
noise_suppression:
$ref: '#/components/schemas/ConnectionNoiseSuppression'
noise_suppression_details:
$ref: '#/components/schemas/ConnectionNoiseSuppressionDetails'
onnet_t38_passthrough_enabled:
default: false
description: Enable on-net T38 if you prefer the sender and receiver negotiating T38 directly if both are on the Telnyx network. If this is disabled, Telnyx will be able to use T38 on just one leg of the call depending on each leg's settings.
example: false
type: boolean
outbound:
$ref: '#/components/schemas/OutboundIp'
rtcp_settings:
$ref: '#/components/schemas/ConnectionRtcpSettings'
tags:
description: Tags associated with the connection.
example:
- tag1
- tag2
items:
type: string
type: array
transport_protocol:
default: UDP
description: One of UDP, TLS, or TCP. Applies only to connections with IP authentication or FQDN authentication.
enum:
- UDP
- TCP
- TLS
example: UDP
type: string
webhook_api_version:
default: '1'
description: Determines which webhook format will be used, Telnyx API v1 or v2.
enum:
- '1'
- '2'
example: '1'
type: string
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'
title: Create IP Connection Request
type: object
DtmfType:
default: RFC 2833
description: Sets the type of DTMF digits sent from Telnyx to this Connection. Note that DTMF digits sent to Telnyx will be accepted in all formats.
enum:
- RFC 2833
- Inband
- SIP INFO
example: Inband
title: DTMF Type
type: string
connections_PaginationMeta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
title: Pagination Meta
type: object
EncryptedMedia:
description: Enable use of SRTP for encryption. Cannot be set if the transport_portocol is TLS.
enum:
- SRTP
- null
example: SRTP
type:
- string
- 'null'
OutboundIp:
example:
ani_override: string
ani_override_type: always
call_parking_enabled: true
channel_limit: 10
generate_ringback_tone: true
instant_ringback_enabled: true
ip_authentication_method: token
ip_authentication_token: string
localization: string
outbound_voice_profile_id: '1293384261075731499'
t38_reinvite_source: customer
tech_prefix: string
properties:
ani_override:
default: ''
description: Set a phone number as the ani_override value to override caller id number on outbound calls.
type: string
ani_override_type:
default: always
description: Specifies when we apply your ani_override setting. Only applies when ani_override is not blank.
enum:
- always
- normal
- emergency
type: string
call_parking_enabled:
default: false
description: Forces all SIP calls originated on this connection to be "parked" instead of "bridged" to the destination specified on the URI. Parked calls will return ringback to the caller and will await for a Call Control command to define which action will be taken next.
type:
- boolean
- 'null'
channel_limit:
default: null
description: When set, this will limit the total number of outbound calls to phone numbers associated with this connection.
type: integer
generate_ringback_tone:
default: false
description: Generate ringback tone through 183 session progress message with early media.
type: boolean
instant_ringback_enabled:
default: true
description: When set, ringback will not wait for indication before sending ringback tone to calling party.
type: boolean
ip_authentication_method:
default: tech-prefixp-charge-info
enum:
- tech-prefixp-charge-info
- token
example: tech-prefixp-charge-info
type: string
ip_authentication_token:
default: null
type: string
localization:
default: null
description: A 2-character country code specifying the country whose national dialing rules should be used. For example, if set to `US` then any US number can be dialed without preprending +1 to the number. When left blank, Telnyx will try US and GB dialing rules, in that order, by default.
type: string
outbound_voice_profile_id:
$ref: '#/components/schemas/connections_OutboundVoiceProfileId'
t38_reinvite_source:
default: customer
description: This setting only affects connections with Fax-type Outbound Voice Profiles. The setting dictates whether or not Telnyx sends a t.38 reinvite.<br/><br/> By default, Telnyx will send the re-invite. If set to `customer`, the caller is expected to send the t.38 reinvite.
enum:
- telnyx
- customer
- disabled
- passthru
- caller-passthru
- callee-passthru
type: string
tech_prefix:
default: ''
description: Numerical chars only, exactly 4 characters.
type: string
title: Outbound Ip
type: object
IpConnection:
example:
active: true
anchorsite_override: Latency
android_push_credential_id: 06b09dfd-7154-4980-8b75-cebf7a9d4f8e
call_cost_in_webhooks: true
connection_name: string
created_at: '2018-02-02T22:25:27.521Z'
default_on_hold_comfort_noise_enabled: true
dtmf_type: RFC 2833
encode_contact_header_enabled: true
encrypted_media: SRTP
id: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
inbound:
ani_number_format: +E.164
channel_limit: 10
codecs:
- G722
default_primary_ip_id: 192.0.2.1
default_routing_method: sequential
default_secondary_ip_id: 198.51.100.1
default_tertiary_ip_id: 203.0.113.1
dnis_number_format: +e164
generate_ringback_tone: true
isup_headers_enabled: true
prack_enabled: true
shaken_stir_enabled: true
sip_compact_headers_enabled: true
sip_region: US
sip_subdomain: string
sip_subdomain_receive_settings: only_my_connections
timeout_1xx_secs: 10
timeout_2xx_secs: 10
ios_push_credential_id: ec0c8e5d-439e-4620-a0c1-9d9c8d02a836
jitter_buffer:
enable_jitter_buffer: true
jitterbuffer_msec_max: 200
jitterbuffer_msec_min: 60
noise_suppression: both
noise_suppression_details:
attenuation_limit: 80
engine: deep_filter_net
onnet_t38_passthrough_enabled: true
outbound:
ani_override: string
ani_override_type: always
call_parking_enabled: true
channel_limit: 10
generate_ringback_tone: true
instant_ringback_enabled: true
ip_authentication_method: token
ip_authentication_token: string
localization: string
outbound_voice_profile_id: '1293384261075731499'
t38_reinvite_source: customer
tech_prefix: string
record_type: ip_connection
rtcp_settings:
capture_enabled: true
port: rtcp-mux
report_frequency_secs: 10
tags:
- tag1
- tag2
transport_protocol: UDP
updated_at: '2018-02-02T22:25:27.521Z'
webhook_api_version: '1'
webhook_event_failover_url: https://failover.example.com
webhook_event_url: https://example.com
webhook_timeout_secs: 25
properties:
active:
description: Defaults to true
example: true
type: boolean
anchorsite_override:
$ref: '#/components/schemas/AnchorsiteOverride'
android_push_credential_id:
$ref: '#/components/schemas/ConnectionAndroidPushCredentialId'
call_cost_in_webhooks:
default: false
description: Specifies if call cost webhooks should be sent for this connection.
type: boolean
connection_name:
example: string
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2018-02-02T22:25:27.521Z'
type: string
default_on_hold_comfort_noise_enabled:
default: true
description: When enabled, Telnyx will generate comfort noise when you place the call on hold. If disabled, you will need to generate comfort noise or on hold music to avoid RTP timeout.
example: true
type: boolean
dtmf_type:
$ref: '#/components/schemas/DtmfType'
encode_contact_header_enabled:
default: false
description: Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG scenarios.
example: true
type: boolean
encrypted_media:
$ref: '#/components/schemas/EncryptedMedia'
id:
description: Identifies the type of resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
type: string
x-format: int64
inbound:
$ref: '#/components/schemas/InboundIp'
ios_push_credential_id:
$ref: '#/components/schemas/ConnectionIosPushCredentialId'
jitter_buffer:
$ref: '#/components/schemas/ConnectionJitterBuffer'
noise_suppression:
$ref: '#/components/schemas/ConnectionNoiseSuppression'
noise_suppression_details:
$ref: '#/components/schemas/ConnectionNoiseSuppressionDetails'
onnet_t38_passthrough_enabled:
default: false
description: Enable on-net T38 if you prefer the sender and receiver negotiating T38 directly if both are on the Telnyx network. If this is disabled, Telnyx will be able to use T38 on just one leg of the call depending on each leg's settings.
example: false
type: boolean
outbound:
$ref: '#/components/schemas/OutboundIp'
record_type:
description: Identifies the type of the resource.
example: ip_connection
type: string
rtcp_settings:
$ref: '#/components/schemas/ConnectionRtcpSettings'
tags:
description: Tags associated with the connection.
example:
- tag1
- tag2
items:
type: string
type: array
transport_protocol:
default: UDP
description: One of UDP, TLS, or TCP. Applies only to connections with IP authentication or FQDN authentication.
enum:
- UDP
- TCP
- TLS
example: UDP
type: string
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2018-02-02T22:25:27.521Z'
type: string
webhook_api_version:
default: '1'
description: Determines which webhook format will be used, Telnyx API v1 or v2.
enum:
- '1'
- '2'
example: '1'
type: string
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'
title: Ip Connection
type: object
ErrorResponse:
properties:
errors:
items:
properties:
code:
type: string
detail:
type: string
meta:
properties:
url:
format: uri
type: string
type: object
source:
properties:
pointer:
type: string
type: object
title:
type: string
type: object
type: array
type: object
ConnectionNoiseSuppression:
description: Controls when noise suppression is applied to calls. When set to 'inbound', noise suppression is applied to incoming audio. When set to 'outbound', it's applied to outgoing audio. When set to 'both', it's applied in both directions. When set to 'disabled', noise suppression is turned off.
enum:
- inbound
- outbound
- both
- disabled
example: both
type: string
ConnectionAndroidPushCredentialId:
default: null
description: The uuid of the push credential for Android
example: 06b09dfd-7154-4980-8b75-cebf7a9d4f8e
title: Android Push Credential Id
type:
- string
- 'null'
CreateInboundIpRequest:
example:
ani_number_format: +E.164
channel_limit: 10
codecs:
- G722
default_routing_method: sequential
dnis_number_format: +e164
generate_ringback_tone: true
isup_headers_enabled: true
prack_enabled: true
shaken_stir_enabled: true
sip_compact_headers_enabled: true
sip_region: US
sip_subdomain: test
sip_subdomain_receive_settings: only_my_connections
timeout_1xx_secs: 10
timeout_2xx_secs: 20
properties:
ani_number_format:
default: E.164-national
description: This setting allows you to set the format with which the caller's number (ANI) is sent for inbound phone calls.
enum:
- +E.164
- E.164
- +E.164-national
- E.164-national
type: string
channel_limit:
default: null
description: When set, this will limit the total number of inbound calls to phone numbers associated with this connection.
type: integer
codecs:
default:
- G722
- G711U
- G711A
- G729
- OPUS
- H.264
description: 'Defines the list of codecs that Telnyx will send for inbound calls to a specific number on your portal account, in priority order. This only works when the Connection the number is assigned to uses Media Handling mode: default. OPUS and H.264 codecs are available only when using TCP or TLS transport for SIP.'
items:
type: string
type: array
default_routing_method:
description: Default routing method to be used when a number is associated with the connection. Must be one of the routing method types or left blank, other values are not allowed.
enum:
- sequential
- round-robin
type: string
dnis_number_format:
default: e164
enum:
- +e164
- e164
- national
- sip_username
type: string
generate_ringback_tone:
default: false
description: Generate ringback tone through 183 session progress message with early media.
type: boolean
isup_headers_enabled:
default: false
description: When set, inbound phone calls will receive ISUP parameters via SIP headers. (Only when available and only when using TCP or TLS transport.)
type: boolean
prack_enabled:
default: false
description: Enable PRACK messages as defined in RFC3262.
type: boolean
shaken_stir_enabled:
default: false
description: When enabled the SIP Connection will receive the Identity header with Shaken/Stir data in the SIP INVITE message of inbound calls, even when using UDP transport.
type: boolean
sip_compact_headers_enabled:
default: true
description: Defaults to true.
type: boolean
sip_region:
default: US
description: Selects which `sip_region` to receive inbound
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-ip-connections-api-openapi.yml