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 Detail Records 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: Detail Records operations
name: Detail Records
paths:
/detail_records:
get:
description: Search for any detail record across the Telnyx Platform
operationId: SearchDetailRecords
parameters:
- description: 'Filter records on a given record attribute and value. <br/>Example: filter[status]=delivered. <br/>Required: filter[record_type] must be specified.'
examples:
filter[cld][contains]=456:
summary: Searches for records which have the property `cld` containing the pattern `456`
value:
cld:
contains: '456'
record_type: messaging
filter[cld][ends_with]=789:
summary: Searches for records which have the property `cld` ending with the suffix `789`
value:
cld:
ends_with: '789'
record_type: messaging
filter[cld][starts_with]=123:
summary: Searches for records which have the property `cld` starting with the prefix `123`
value:
cld:
starts_with: '123'
record_type: messaging
filter[created_at][gte]=2021-06-22:
summary: Searches for records with `created_at` starting at `2021-06-22`
value:
created_at:
gte: '2021-06-22'
record_type: messaging
filter[created_at][lt]=2021-06-23:
summary: Searches for records with `created_at` ending at `2021-06-22`
value:
created_at:
lt: '2021-06-23'
record_type: messaging
filter[date_range]=last_month:
summary: Searches for records with timestamp starting at `00:00:00` on the first day of the month
value:
date_range: last_month
record_type: messaging
filter[date_range]=today:
summary: Searches for records with timestamp starting at `00:00:00` of the current day
value:
date_range: today
record_type: messaging
filter[date_range]=yesterday:
summary: Searches for records with timestamp starting at `00:00:00` of yesterday
value:
date_range: yesterday
record_type: messaging
filter[direction]=inbound:
summary: Searches for records which have the property `direction` equal to `inbound`
value:
direction: inbound
record_type: messaging
filter[record_type]=messaging:
summary: Searches for messaging detail records
value:
record_type: messaging
filter[record_type]=verify:
summary: Searches for verify detail records
value:
record_type: verify
explode: true
in: query
name: filter
required: false
schema:
additionalProperties: true
properties:
date_range:
description: 'Filter by the given user-friendly date range. You can specify one of the following enum values, or a dynamic one using this format: last_N_days.'
enum:
- yesterday
- today
- tomorrow
- last_week
- this_week
- next_week
- last_month
- this_month
- next_month
type: string
record_type:
description: Filter by the given record type.
enum:
- ai-voice-assistant
- amd
- call-control
- conference
- conference-participant
- embedding
- fax
- inference
- inference-speech-to-text
- media_storage
- media-streaming
- messaging
- noise-suppression
- recording
- sip-trunking
- siprec-client
- stt
- tts
- verify
- webrtc
- wireless
type: string
required:
- record_type
type: object
style: deepObject
- description: 'Specifies the sort order for results. <br/>Example: sort=-created_at'
examples:
sort=-created_at:
summary: Sorts search results using the `created_at` date-time in descending order
value:
- -created_at
sort=created_at:
summary: Sorts search results using the `created_at` date-time in ascending order
value:
- created_at
in: query
name: sort
schema:
items:
type: string
type: array
- description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
examples:
page[number]=1&page[size]=20:
summary: Default pagination with first page and 20 items per page
value:
number: 1
size: 20
page[number]=1&page[size]=50:
summary: First page with maximum 50 items per page
value:
number: 1
size: 50
page[number]=2&page[size]=20:
summary: Second page with 20 items per page
value:
number: 2
size: 20
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number
format: int32
minimum: 1
type: integer
size:
default: 20
description: Page size
format: int32
maximum: 50
minimum: 1
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DetailRecordsSearchResponse'
description: Successful
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/detail-records_ErrorResponse'
description: Bad Request
security:
- bearerAuth: []
summary: Search detail records
tags:
- Detail Records
x-latency-category: interactive
components:
schemas:
VerifyDetailRecord:
properties:
created_at:
example: '2021-07-08T00:00:41.000000+00:00'
format: date-time
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing costs
example: USD
type: string
delivery_status:
example: pending
type: string
destination_phone_number:
description: E.164 formatted phone number
example: '+13124515883'
type: string
id:
description: Unique ID of the verification
example: 0add777f-1549-46f7-84e9-ad7350f6aa97
format: uuid
type: string
rate:
description: Currency amount per billing unit used to calculate the Telnyx billing costs
example: '0.002'
type: string
rate_measured_in:
description: Billing unit used to calculate the Telnyx billing costs
example: number of occurrences
type: string
record_type:
default: verification_detail_record
example: verification_detail_record
type: string
updated_at:
example: '2021-07-08T00:00:41.000000+00:00'
format: date-time
type: string
verification_status:
example: pending
type: string
verify_channel_id:
example: 5b7a8365-91f3-420a-befc-498d1efd6c20
format: uuid
type: string
verify_channel_type:
description: 'Depending on the type of verification, the `verify_channel_id`
points to one of the following channel ids;
---
verify_channel_type | verify_channel_id
------------------- | -----------------
sms, psd2 | messaging_id
call, flashcall | call_control_id
---
'
enum:
- sms
- psd2
- call
- flashcall
type: string
verify_profile_id:
example: 49000176-1ab2-8bc1-352e-4009f6c37f82
format: uuid
type: string
verify_usage_fee:
description: Currency amount for Verify Usage Fee
example: '0.002'
type: string
required:
- record_type
type: object
ConferenceParticipantDetailRecord:
properties:
billed_sec:
description: Duration of the conference call for billing purposes
example: 120
type: integer
call_leg_id:
description: Telnyx UUID that identifies the conference call leg
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
call_sec:
description: Duration of the conference call in seconds
example: 100
type: integer
call_session_id:
description: Telnyx UUID that identifies with conference call session
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
conference_id:
description: Conference id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
cost:
description: Currency amount for Telnyx billing cost
example: '0.004'
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing cost
example: USD
type: string
destination_number:
description: Number called by the participant to join the conference
example: '+18005550199'
type: string
id:
description: Participant id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
is_telnyx_billable:
description: Indicates whether Telnyx billing charges might be applicable
example: true
type: boolean
joined_at:
description: Participant join time
example: '2020-07-01T00:00:00-06:00'
format: date-time
type: string
left_at:
description: Participant leave time
example: '2020-07-01T00:00:00-06:00'
format: date-time
type: string
originating_number:
description: Participant origin number used in the conference call
example: '+18005550199'
type: string
rate:
description: Currency amount per billing unit used to calculate the Telnyx billing cost
example: '0.002'
type: string
rate_measured_in:
description: Billing unit used to calculate the Telnyx billing cost
example: minutes
type: string
record_type:
default: conference_participant_detail_record
example: conference_participant_detail_record
type: string
user_id:
description: User id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
required:
- record_type
type: object
detail-records_ErrorResponse:
properties:
errors:
items:
$ref: '#/components/schemas/detail-records_Error'
type: array
type: object
DetailRecord:
description: An object following one of the schemas published in https://developers.telnyx.com/docs/api/v2/detail-records
discriminator:
propertyName: record_type
oneOf:
- $ref: '#/components/schemas/MessageDetailRecord'
title: Message
- $ref: '#/components/schemas/ConferenceDetailRecord'
title: Conference
- $ref: '#/components/schemas/ConferenceParticipantDetailRecord'
title: Conference Participant
- $ref: '#/components/schemas/AmdDetailRecord'
title: AMD
- $ref: '#/components/schemas/VerifyDetailRecord'
title: Verify 2FA
- $ref: '#/components/schemas/SimCardUsageDetailRecord'
title: Sim Card Usage
- $ref: '#/components/schemas/MediaStorageDetailRecord'
title: Media Storage
required:
- record_type
type: object
AmdDetailRecord:
properties:
billing_group_id:
description: Billing Group id
example: 01977831-abdd-4894-84f3-244385621424
type: string
billing_group_name:
description: Name of the Billing Group specified in billing_group_id
example: Billing group name
type: string
call_leg_id:
description: Telnyx UUID that identifies the related call leg
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
call_session_id:
description: Telnyx UUID that identifies the related call session
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
connection_id:
description: Connection id
example: '1684947189014463919'
type: string
connection_name:
description: Connection name
example: Name of the connection with id specified in connection_id field
type: string
cost:
description: Currency amount for Telnyx billing cost
example: '0.004'
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing cost
example: USD
type: string
feature:
description: Feature name
enum:
- PREMIUM
type: string
id:
description: Feature invocation id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
invoked_at:
description: Feature invocation time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
is_telnyx_billable:
description: Indicates whether Telnyx billing charges might be applicable
example: true
type: boolean
rate:
description: Currency amount per billing unit used to calculate the Telnyx billing cost
example: '0.002'
type: string
rate_measured_in:
description: Billing unit used to calculate the Telnyx billing cost
example: invocations
type: string
record_type:
default: amd_detail_record
example: amd_detail_record
type: string
tags:
description: User-provided tags
example: tag1,tag2
type: string
required:
- record_type
type: object
MediaStorageDetailRecord:
properties:
action_type:
description: Type of action performed against the Media Storage API
example: upload
type: string
asset_id:
description: Asset id
example: a46f4764-4ce4-4391-804c-02f00bc4ff9b
type: string
cost:
description: Currency amount for Telnyx billing cost
example: '0.004'
type: string
created_at:
description: Event creation time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing cost
example: USD
type: string
id:
description: Unique identifier for the Media Storage Event
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
link_channel_id:
description: Link channel id
example: 2065f482-64b9-4680-a3a9-c6d3142efdf7
type: string
link_channel_type:
description: Link channel type
example: message
type: string
org_id:
description: Organization owner id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
rate:
description: Currency amount per billing unit used to calculate the Telnyx billing cost
example: '0.0001'
type: string
rate_measured_in:
description: Billing unit used to calculate the Telnyx billing cost
example: events
type: string
record_type:
default: media_storage
example: media_storage
type: string
status:
description: Request status
example: failed
type: string
user_id:
description: User id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
webhook_id:
description: Webhook id
example: b46f4764-4ce4-4391-804c-02f00bc4ff9b
type: string
required:
- record_type
type: object
detail-records_Error:
properties:
code:
example: '10011'
type: string
detail:
example: No matching record type was found matching given record type wirelessxx
type: string
title:
example: Bad Request
type: string
type: object
ConferenceDetailRecord:
properties:
call_leg_id:
description: Telnyx UUID that identifies the conference call leg
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
call_sec:
description: Duration of the conference call in seconds
example: 100
type: integer
call_session_id:
description: Telnyx UUID that identifies with conference call session
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
connection_id:
description: Connection id
example: '1583941447772537867'
type: string
ended_at:
description: Conference end time
example: '2020-07-01T00:00:00-06:00'
format: date-time
type: string
expires_at:
description: Conference expiry time
example: '2020-07-01T00:00:00-06:00'
format: date-time
type: string
id:
description: Conference id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
is_telnyx_billable:
description: Indicates whether Telnyx billing charges might be applicable
example: false
type: boolean
name:
description: Conference name
example: My Conference
type: string
participant_call_sec:
description: Sum of the conference call duration for all participants in seconds
example: 100
type: integer
participant_count:
description: Number of participants that joined the conference call
example: 5
type: integer
record_type:
default: conference_detail_record
example: conference_detail_record
type: string
region:
description: Region where the conference is hosted
example: ch1
type: string
started_at:
description: Conference start time
example: '2020-07-01T00:00:00-06:00'
format: date-time
type: string
user_id:
description: User id
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
required:
- record_type
type: object
MessageDetailRecord:
properties:
carrier:
description: Country-specific carrier used to send or receive the message
example: T-Mobile USA
type: string
carrier_fee:
description: Fee charged by certain carriers in order to deliver certain message types. Telnyx passes this fee on to the customer according to our pricing table
example: '0.003'
type: string
cld:
description: The recipient of the message (to parameter in the Messaging API)
example: '+1555123456'
type: string
cli:
description: The sender of the message (from parameter in the Messaging API). For Alphanumeric ID messages, this is the sender ID value
example: '+1555123456'
type: string
completed_at:
description: Message completion time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
cost:
description: Amount, in the user currency, for the Telnyx billing cost
example: '0.003'
type: string
country_code:
description: Two-letter representation of the country of the cld property using the ISO 3166-1 alpha-2 format
example: US
type: string
created_at:
description: Message creation time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing cost
example: USD
type: string
delivery_status:
description: Final webhook delivery status
example: 'success: webhook succeeded'
type: string
delivery_status_failover_url:
description: Failover customer-provided URL which Telnyx posts delivery status webhooks to
example: https://api.example.com/sms/telnyx/inbound
type: string
delivery_status_webhook_url:
description: Primary customer-provided URL which Telnyx posts delivery status webhooks to
example: https://api.example.com/sms/telnyx/inbound
type: string
direction:
description: Logical direction of the message from the Telnyx customer's perspective. It's inbound when the Telnyx customer receives the message, or outbound otherwise
enum:
- inbound
- outbound
example: outbound
type: string
errors:
description: Telnyx API error codes returned by the Telnyx gateway
items:
example: '40001'
type: string
type: array
fteu:
description: Indicates whether this is a Free-To-End-User (FTEU) short code message
example: false
type: boolean
mcc:
description: Mobile country code. Only available for certain products, such as Global Outbound-Only from Alphanumeric Sender ID
example: '204'
type: string
message_type:
description: 'Describes the Messaging service used to send the message. Available services are: Short Message Service (SMS), Multimedia Messaging Service (MMS), and Rich Communication Services (RCS)'
enum:
- SMS
- MMS
- RCS
example: SMS
type: string
mnc:
description: Mobile network code. Only available for certain products, such as Global Outbound-Only from Alphanumeric Sender ID
example: '01'
type: string
on_net:
description: Indicates whether both sender and recipient numbers are Telnyx-managed
example: true
type: boolean
parts:
description: Number of message parts. The message is broken down in multiple parts when its length surpasses the limit of 160 characters
example: 2
type: integer
profile_id:
description: Unique identifier of the Messaging Profile used to send or receive the message
example: 30ef55db-c4a2-4c4a-9804-a68077973d07
type: string
profile_name:
description: Name of the Messaging Profile used to send or receive the message
example: My Messaging Profile
type: string
rate:
description: Currency amount per billing unit used to calculate the Telnyx billing cost
example: '0.003'
type: string
record_type:
default: message_detail_record
description: Identifies the record schema
example: message_detail_record
type: string
sent_at:
description: Time when the message was sent
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
source_country_code:
description: Two-letter representation of the country of the cli property using the ISO 3166-1 alpha-2 format
example: US
type: string
status:
description: Final status of the message after the delivery attempt
enum:
- gw_timeout
- delivered
- dlr_unconfirmed
- dlr_timeout
- received
- gw_reject
- failed
example: delivered
type: string
tags:
description: Comma-separated tags assigned to the Telnyx number associated with the message
example: tag1,tag2,tag3
type: string
updated_at:
description: Message updated time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
user_id:
description: Identifier of the Telnyx account who owns the message
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
uuid:
description: Unique identifier of the message
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
type: string
required:
- record_type
type: object
detail-records_PaginationMeta:
properties:
page_number:
example: 2
format: int32
type: integer
page_size:
example: 25
format: int32
type: integer
total_pages:
example: 3
format: int32
type: integer
total_results:
example: 55
format: int32
type: integer
type: object
DetailRecordsSearchResponse:
properties:
data:
items:
$ref: '#/components/schemas/DetailRecord'
type: array
meta:
$ref: '#/components/schemas/detail-records_PaginationMeta'
type: object
SimCardUsageDetailRecord:
properties:
closed_at:
description: Event close time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
created_at:
description: Event creation time
example: '2020-07-01T00:00:00Z'
format: date-time
type: string
currency:
description: Telnyx account currency used to describe monetary values, including billing cost
example: USD
type: string
data_cost:
description: Data cost
example: 0.029283
type: number
data_rate:
description: Currency amount per billing unit used to calculate the Telnyx billing cost
example: '0.06000'
type: string
data_unit:
description: Unit of wireless link consumption
example: MB
type: string
downlink_data:
description: Number of megabytes downloaded
example: 0.124
type: number
id:
description: Unique identifier for this SIM Card Usage
example: 3ca7bd3d-7d82-4e07-9df4-009123068320
format: uuid
type: string
imsi:
description: International Mobile Subscriber Identity
example: '311210393720093'
type: string
ip_address:
description: Ip address that generated the event
example: 100.64.1.2
type: string
mcc:
description: Mobile country code
example: '204'
type: string
mnc:
description: Mobile network code
example: '69'
type: string
phone_number:
description: Telephone number associated to SIM card
example: '+15188490209'
type: string
record_type:
default: sim_card_usage
example: sim_card_usage
type: string
sim_card_id:
description: Unique identifier for SIM card
example: 7aa66686-b39f-456d-8edc-5b6cffb1432a
type: string
sim_card_tags:
description: User-provided tags
example: mytag
type: string
sim_group_id:
description: Unique identifier for SIM group
example: 6c07e2e9-cbc0-49ba-ac0d-c59b59646bb1
type: string
sim_group_name:
description: Sim group name for sim card
example: SIMBillingInfo test - otheraccount
type: string
uplink_data:
description: Number of megabytes uploaded
example: 0.7653
type: number
required:
- record_type
type: object
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