OpenAPI Specification
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 Notifications 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: Notification settings operations
name: Notifications
paths:
/notification_channels:
get:
description: List notification channels.
operationId: ListNotificationChannels
parameters:
- $ref: '#/components/parameters/PageConsolidated'
- $ref: '#/components/parameters/notifications_FilterConsolidated'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NotificationChannel'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Returns a list of notification channels.
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: List notification channels
tags:
- Notifications
x-latency-category: responsive
post:
description: Create a notification channel.
operationId: CreateNotificationChannels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannel'
description: Add a Notification Channel
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationChannel'
type: object
description: A Notification Channel response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Create a notification channel
tags:
- Notifications
x-latency-category: responsive
/notification_channels/{id}:
delete:
description: Delete a notification channel.
operationId: DeleteNotificationChannel
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationChannel'
type: object
description: A Notification Channel response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Delete a notification channel
tags:
- Notifications
x-latency-category: responsive
get:
description: Get a notification channel.
operationId: GetNotificationChannel
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationChannel'
type: object
description: A Notification Channel response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'404':
$ref: '#/components/responses/notifications_NotFoundResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Get a notification channel
tags:
- Notifications
x-latency-category: responsive
patch:
description: Update a notification channel.
operationId: UpdateNotificationChannel
parameters:
- $ref: '#/components/parameters/notifications_Id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannel'
description: Update notification channel object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationChannel'
type: object
description: A Notification Channel response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Update a notification channel
tags:
- Notifications
x-latency-category: responsive
/notification_event_conditions:
get:
description: Returns a list of your notifications events conditions.
operationId: FindNotificationsEventsConditions
parameters:
- $ref: '#/components/parameters/PageConsolidated'
- $ref: '#/components/parameters/notifications_FilterConsolidated'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NotificationEventCondition'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Returns a list of notification event conditions available.
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: List all Notifications Events Conditions
tags:
- Notifications
x-latency-category: responsive
/notification_events:
get:
description: Returns a list of your notifications events.
operationId: FindNotificationsEvents
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NotificationEvent'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Returns a list of notification events available.
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: List all Notifications Events
tags:
- Notifications
x-latency-category: responsive
/notification_profiles:
get:
description: Returns a list of your notifications profiles.
operationId: FindNotificationsProfiles
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NotificationProfile'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Returns a list of notification profiles.
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: List all Notifications Profiles
tags:
- Notifications
x-latency-category: responsive
post:
description: Create a notification profile.
operationId: CreateNotificationProfile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationProfile'
description: Add a Notification Profile
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationProfile'
type: object
description: A Notification Profile response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Create a notification profile
tags:
- Notifications
x-latency-category: responsive
/notification_profiles/{id}:
delete:
description: Delete a notification profile.
operationId: DeleteNotificationProfile
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationProfile'
type: object
description: A Notification Profile response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Delete a notification profile
tags:
- Notifications
x-latency-category: responsive
get:
description: Get a notification profile.
operationId: GetNotificationProfile
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationProfile'
type: object
description: A Notification Profile response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'404':
$ref: '#/components/responses/notifications_NotFoundResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Get a notification profile
tags:
- Notifications
x-latency-category: responsive
patch:
description: Update a notification profile.
operationId: UpdateNotificationProfile
parameters:
- $ref: '#/components/parameters/notifications_Id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationProfile'
description: Update notification profile object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationProfile'
type: object
description: A Notification Profile response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Update a notification profile
tags:
- Notifications
x-latency-category: responsive
/notification_settings:
get:
description: List notification settings.
operationId: ListNotificationSettings
parameters:
- $ref: '#/components/parameters/PageConsolidated'
- $ref: '#/components/parameters/notifications_FilterConsolidated'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NotificationSetting'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Returns a list of notification settings.
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: List notification settings
tags:
- Notifications
x-latency-category: responsive
post:
description: Add a notification setting.
operationId: CreateNotificationSetting
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationSetting'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationSetting'
type: object
description: A Notification Setting response
'201':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationSetting'
type: object
description: A Notification Setting response - async
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Add a Notification Setting
tags:
- Notifications
x-latency-category: responsive
/notification_settings/{id}:
delete:
description: Delete a notification setting.
operationId: DeleteNotificationSetting
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationSetting'
type: object
description: A Notification Setting response
'201':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationSetting'
type: object
description: A Notification Setting response - async
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Delete a notification setting
tags:
- Notifications
x-latency-category: responsive
get:
description: Get a notification setting.
operationId: GetNotificationSetting
parameters:
- $ref: '#/components/parameters/notifications_Id'
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NotificationSetting'
type: object
description: A Notification Setting response
'400':
$ref: '#/components/responses/notifications_BadRequestResponse'
'404':
$ref: '#/components/responses/notifications_NotFoundResponse'
'422':
$ref: '#/components/responses/notifications_UnprocessableEntity'
'500':
$ref: '#/components/responses/notifications_GenericErrorResponse'
summary: Get a notification setting
tags:
- Notifications
x-latency-category: responsive
components:
schemas:
notifications_Error:
properties:
code:
type: string
x-format: int64
detail:
type: string
meta:
additionalProperties: true
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
format: json-pointer
type: string
type: object
title:
type: string
required:
- code
- title
type: object
NotificationEvent:
description: An object representing the available notifications.
properties:
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2019-10-15T10:07:15.527Z'
format: date-time
type: string
enabled:
example: true
type: boolean
id:
description: A UUID.
example: d5c395cd-9864-4609-b5e2-3f9fd4ce201a
readOnly: true
type: string
name:
description: A human readable name.
example: Emergency Number Dialed
type: string
notification_category:
example: Calls
type: string
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2019-10-15T10:07:15.527Z'
format: date-time
type: string
type: object
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
type: object
notifications_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/notifications_Error'
type: array
type: object
NotificationChannel:
description: A Notification Channel
properties:
channel_destination:
description: The destination associated with the channel type.
example: '+13125550000'
type: string
channel_type_id:
description: A Channel Type ID
enum:
- sms
- voice
- email
- webhook
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
id:
description: A UUID.
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
readOnly: true
type: string
notification_profile_id:
description: A UUID reference to the associated Notification Profile.
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
type: object
NotificationEventCondition:
properties:
allow_multiple_channels:
description: Dictates whether a notification channel id needs to be provided when creating a notficiation setting.
example: false
type: boolean
associated_record_type:
enum:
- account
- phone_number
example: phone_number
type: string
asynchronous:
description: Dictates whether a notification setting will take effect immediately.
example: true
type: boolean
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2019-10-15T10:07:15.527Z'
format: date-time
type: string
description:
example: When emergency number dialed from phone number X
type: string
enabled:
example: true
type: boolean
id:
description: A UUID.
example: 70c7c5cb-dce2-4124-accb-870d39dbe852
readOnly: true
type: string
name:
example: from phone number
type: string
notification_event_id:
example: d5c395cd-9864-4609-b5e2-3f9fd4ce201a
type: string
parameters:
items:
properties:
data_type:
example: string
type: string
name:
example: phone_number
type: string
optional:
example: false
type: boolean
type: object
type: array
supported_channels:
description: Dictates the supported notification channel types that can be emitted.
example:
- webhook
- sms
- email
- voice
items:
type: string
type: array
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2019-10-15T10:07:15.527Z'
format: date-time
type: string
type: object
NotificationProfile:
description: A Collection of Notification Channels
properties:
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
id:
description: A UUID.
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
readOnly: true
type: string
name:
description: A human readable name.
type: string
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
type: object
NotificationSetting:
properties:
associated_record_type:
example: phone_number
readOnly: true
type: string
associated_record_type_value:
example: '+13125550000'
readOnly: true
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
id:
description: A UUID.
example: 8eb5b5f9-5893-423c-9f15-b487713d44d4
readOnly: true
type: string
notification_channel_id:
description: A UUID reference to the associated Notification Channel.
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
notification_event_condition_id:
description: A UUID reference to the associated Notification Event Condition.
example: 70c7c5cb-dce2-4124-accb-870d39dbe852
type: string
notification_profile_id:
description: A UUID reference to the associated Notification Profile.
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
parameters:
items:
properties:
name:
example: phone_number
type: string
value:
example: '+13125550000'
type: string
type: object
type: array
status:
description: Most preferences apply immediately; however, other may needs to propagate.
enum:
- enabled
- enable-received
- enable-pending
- enable-submtited
- delete-received
- delete-pending
- delete-submitted
- deleted
example: enable-received
readOnly: true
type: string
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
example: '2019-10-15T10:07:15.527Z'
format: date-time
readOnly: true
type: string
type: object
responses:
notifications_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/notifications_Errors'
description: Unexpected error
notifications_BadRequestResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/notifications_Errors'
description: Bad request, the request was unacceptable, often due to missing a required parameter.
notifications_UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/notifications_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
notifications_NotFoundResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/notifications_Errors'
description: The requested resource doesn't exist.
parameters:
notifications_FilterConsolidated:
description: 'Consolidated filter parameter (deepObject style). Originally: filter[associated_record_type][eq], filter[channel_type_id][eq], filter[notification_profile_id][eq], filter[notification_channel][eq], filter[notification_event_condition_id][eq], filter[status][eq]'
explode: true
in: query
name: filter
required: false
schema:
properties:
associated_record_type:
properties:
eq:
description: Filter by the associated record type
enum:
- account
- phone_number
example: phone_number
type: string
type: object
channel_type_id:
properties:
eq:
description: Filter by the id of a channel type
enum:
- webhook
- sms
- email
- voice
example: webhook
type: string
type: object
notification_channel:
properties:
eq:
description: Filter by the id of a notification channel
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
type: object
notification_event_condition_id:
properties:
eq:
description: Filter by the id of a notification channel
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
type: object
notification_profile_id:
properties:
eq:
description: Filter by the id of a notification profile
example: 12455643-3cf1-4683-ad23-1cd32f7d5e0a
type: string
type: object
status:
properties:
eq:
description: The status of a notification setting
enum:
- enabled
- enable-received
- enable-pending
- enable-submtited
- delete-received
- delete-pending
- delete-submitted
- deleted
example: enable-received
type: string
type: object
type: object
style: deepObject
notifications_Id:
description: The id of the resource.
in: path
name: id
required: true
schema:
format: uuid
type: string
PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: The page number to load
minimum: 1
type: integer
size:
default: 20
description: The size of the page
maximum: 250
minimum: 1
type: integer
type: object
style: deepObject
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http