Detail Record Search

Information about your Telnyx usage is available through the Detail Record Search API - a flexible, easy-to-use endpoint for viewing records of your usage on the Telnyx platform.

What is a detail record?

A Detail Record provides a description of a single, product-specific request made through Telnyx. For example, if you send a message through the Telnyx Messaging API, a Message Detail Record (MDR) is generated, which includes information like the status, cost, and direction (“inbound” or ”outbound”) for that message. This MDR is stored in your Telnyx account and can be retrieved as part of a report in the Mission Control Portal .

What is the detail record search API?

The Detail Record Search API is a tool for finding detail records based on multiple fields within those detail records. In the below messaging example, you can search for message detail records (MDRs) sent during a specific time span, for detail records associated with only “inbound” messages, or for detail records associated with messages sent from a particular number. Having multiple options to filter the records returned helps to troubleshoot potential issues and analyze your usage.

How to retrieve detail records

The /detail_records API endpoint has support for multiple types of detail records associated with multiple Telnyx products. You can find a list of the supported products and their corresponding filter parameter (/filter[record_type]) values at the bottom of this page.

In this example, we want to query Message Detail Records (MDRs) to see all of the messages we’ve sent or received today.

Request:

curl --location -g --request GET \
'https://api.telnyx.com/v2/detail_records?filter[record_type]=messaging&filter[date_range]=today' \
--header 'Authorization: Bearer YOUR_API_KEY'

Note: After pasting the above content, Kindly check and remove any new line added

Response (abbreviated):

{
   "data": [
       {
           "carrier_fee": "0.0",
           "created_at": "2021-08-23T22:03:37Z",
           "mcc": "",
           "fteu": false,
           "profile_name": "My Telnyx Messaging Profile",
           "updated_at": "2021-08-23T22:03:37Z",
           "rate": "0.0000",
           "on_net": false,
           "cld": "+16155700362",
           "currency": "USD",
           "id": "593ecdfa-8b7c-43bf-b832-f34103a9d8ae",
           "direction": "inbound",
           "cli": "+13126040939",
           "cost": "0.0000",
           "mnc": "",
           "message_type": "SMS",
           "record_type": "message_detail_record",
           "tags": "",
           "sent_at": "2021-08-23T22:03:37Z",
           "country_code": "US",
           "completed_at": "2021-08-23T22:03:37Z",
           "carrier": "NEW CINGULAR WIRELESS PCS, LLC - IL",
           "user_id": "a37bdd47-f301-42ec-b2ad-5a0465bfb633",
           "delivery_status_failover_url": "",
           "profile_id": "40017980-7d67-4a2f-bf9e-f3a3762c0fa3",
           "parts": 1,
           "delivery_status_webhook_url": "https://webhook.site/2fa8fe78-ad37-44ce-9f13-1b16c76fb2b1",
           "source_country_code": "US",
           "errors": [],
           "delivery_status": "",
           "status": "delivered"
       },
       ...
   ],
   "meta": {
       "total_pages": 2,
       "total_results": 30,
       "page_number": 1,
       "page_size": 20
   }
}

Note: After pasting the above content, Kindly check and remove any new line added

Next, let's narrow down the results to only show outbound messages that were sent to a particular number, in this example +13176050941.

Request:

curl --location -g --request GET \
'https://api.telnyx.com/v2/detail_records?filter[record_type]=messaging&filter[date_range]=today&filter[direction]=outbound&filter[product]=long_code&filter[cld]=+13176050941' \
--header 'Authorization: Bearer YOUR_API_KEY'

Note: After pasting the above content, Kindly check and remove any new line added

Response (abbreviated):

{
   "data": [
       {
           "carrier_fee": "0.002",
           "created_at": "2021-08-23T22:03:19Z",
           "mcc": "",
           "fteu": false,
           "profile_name": "My Telnyx Messaging Profile",
           "updated_at": "2021-08-23T22:03:20Z",
           "rate": "0.00450",
           "on_net": false,
           "cld": "+13126070938",
           "currency": "USD",
           "id": "60317b75-0a11-42b1-a1df-8327ef3b6e81",
           "direction": "outbound",
           "cli": "+16125700364",
           "cost": "0.0045",
           "mnc": "",
           "message_type": "SMS",
           "record_type": "message_detail_record",
           "tags": "",
           "sent_at": "2021-08-23T22:03:20Z",
           "country_code": "US",
           "completed_at": "2021-08-23T22:03:20Z",
           "carrier": "NEW CINGULAR WIRELESS PCS, LLC - IL",
           "user_id": "d37bdd47-f301-42ec-b2ad-5a0465bfb632",
           "delivery_status_failover_url": "",
           "profile_id": "56817980-7d67-4a2f-bf9e-f3a3762c0fa3",
           "parts": 1,
           "delivery_status_webhook_url": "https://webhook.site/2fa8fe78-ad37-44ce-9f13-1b16c76fb2b1",
           "source_country_code": "US",
           "errors": [],
           "delivery_status": "",
           "status": "delivered"
       },
       ...
   ],
   "meta": {
       "total_pages": 1,
       "total_results": 10,
       "page_number": 1,
       "page_size": 20
   }
}

Note: After pasting the above content, Kindly check and remove any new line added

While this example illustrates a messaging use-case, the same patterns can be used to view records for any of the products listed below, using any of the attributes listed in the Debugging API reference to refine your results.

What types of records can I find with the Detail Record Search API?

Product	record_type
Messaging	messaging
Conference	conference, conference-participant
Answering Machine Detection	amd
Verify API	verify
IoT SIM Cards	wireless
Media Storage	media_storage

More products and capabilities will be added to the API soon - sign up for a Telnyx account to be the first to hear about new updates!