Use the Call Detail Records (CDR) API to query your interaction detail records from your account. Apply various request parameters as filters to limit the number of records in the response.
Important: You may only query CDRs for which access has been granted to you by your account privileges. Refer to Security Access Groups.
To obtain values for certain CDR request filters, such as queue_ids, agent_ids, and so on, you can use the following APIs to get IDs and other details for these contact center objects:
Refer to the Parameter Reference table, below, for more information.
The following is an example of a request that returns all interaction records for outbound calls from December 12, 2023 onwards. The response should include the first 1000 or fewer records on a single page:
"method": "GET",
"url": "https://cluster1.voiso.com/api/v2/cdr",
"headers": {
"Accept": "application/json"
},
"params": {
"key": "a387aaf1f101fc...fe284aaf61",
"page": "1",
"per_page": "1000",
"type": "outbound",
"start_date": "2023-12-01"
}
}
The CDR API returns up to 10,000 results per request. To obtain more than 10,000 results, you must make multiple requests, adding the search_token parameter to subsequent requests.
If your first request returns 10,000 records, but additional records match the search criteria, the response includes the search_token parameter and value. For example:
{
"records": [ …array of records… ],
"total":176,
"page":1,
"search_token": "WzE2NjkwMTcyNDkwMTUsImNkcl9pdGVtI2MzNTY2ZTFiL"
}
To continue searching the records from where you left off, enter your request again, adding the search_token parameter. For example:
{
"method": "GET",
"url": "https://cluster1.voiso.com/api/v2/cdr",
"params": {
"key": "a387aaf1f101fc...fe284aaf61",
"page": "1",
"per_page": "1000",
"type": "outbound",
"start_date": "2023-12-01",
"search_token": "WzE2NjkwMTcyNDkwMTUsImNkcl9pdGVtI2MzNTY2ZTFiL
}
}
Repeat the search process, replacing the search_token value with the new value in the response until the response is "search_token": null. For example:
{
"records":[],
"total":310,
"search_token":null
}
The following parameters are supported by the CDR API.
| Parameter Name | Description | Required | Type | Example |
|---|---|---|---|---|
| key | The API key of a specific user. | Required | string | user_api_key |
| search_token | Parameter should be used to query more than 10000 records. | Required | string | dkeouof13kjhk4HHH59 |
| page | Indicates the current page number | Optional | integer (int32) | 1 |
| per_page | Number of records per page | Optional | integer (int32) | 20 |
| start_date | Include only records on or after this date. Must be in the 'YYYY-MM-DD' format (ISO 8601). | Optional | string | 2020-04-01 |
| end_date | Include only records on or before this date. Must be in the 'YYYY-MM-DD' format (ISO 8601). | Optional | string | 2020-05-01 |
| cli | The call line identity (CLI) calling number. A 'starting with' search of the ANI/From field. | Optional | string | 197 |
| number | The called number. A 'starting with' search of the DNIS/To field. | Optional | string | 187 |
| wildcard_cli | The call line identity (CLI) calling number. An 'includes' search of the ANI/From field. | Optional | string | 971231 |
| wildcard_number | The called number. An 'includes' search of the DNIS/To field. | Optional | string | 7751 |
| type | Direction and type of the interaction | Optional | type (custom schema) | - |
| disposition | Retrieved call outcome | Optional | disposition_code (custom schema) | - |
| queue_ids | Single or multiple queue IDs, separated by commas. These can be obtained with the /api/v2/cdr/queues method | Optional | string | 199, 201 |
| agent_ids | Single or multiple agent IDs, separated by commas. These can be obtained with the /api/v2/cdr/agents method | Optional | string | 1,2,3 |
| team_ids | Single or multiple agent team IDs, separated by commas. These can be obtained with the /api/v2/cdr/teams method | Optional | string | 3,4 |
| wrapup_codes | Single or multiple wrap-up code IDs, separated by commas. These can be obtained with the /api/v2/cdr/wrapup_codes method | Optional | string | 0001, 1002 |
| event | Standard call events | Optional | events (custom schema) | - |
| end_reason | Standard call end reasons | Optional | end_reason (custom schema) | - |
| campaign_ids | Single or multiple campaign IDs, separated by commas. These can be obtained with the /api/v2/cdr/campaigns method | Optional | string | 15, 13, 22 |
| duration_from | Calls which have a duration longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| duration_to | Calls which have a duration shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| dialing_time_from | Calls which have a dialing time longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| dialing_time_to | Calls which have a dialing time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| talk_time_from | Calls which have a talk time longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| talk_time_to | Calls which have a talk time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| hold_time_from | Calls which have a hold time longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| hold_time_to | Calls which have a hold time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| ivr_time_from | Calls which have a pre-queue (IVR) time longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| ivr_time_to | Calls which have a pre-queue (IVR) time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| queue_time_from | Calls which have a queue time longer than the specified value (in seconds) | Optional | integer (int32) | 1 |
| queue_time_to | Calls which have a queue time shorter than the specified value (in seconds) | Optional | integer (int32) | 10 |
| deleted_agent_ids | Single or multiple deleted (archived) agent IDs, separated by commas. These can be obtained with the /api/v2/cdr/deleted_agents method | Optional | string | 15, 16, 17 |
| first_seen | Set to Required to get only new numbers that have never been dialed before | Optional | first_seen (custom schema) | - |
| lead_source | Calls with a specified lead source type (available only for dialer campaigns with a specified lead source) | Optional | string | Google ADS |
| start_datetime | Must be in this format: 'YYYY-MM-DD'T'HH:MM:SS'. | Optional | string | 2022-08-19T02:56:02 |
| end_datetime | Must be in this format: 'YYYY-MM-DD'T'HH:MM:SS'. | Optional | string | 2022-08-19T02:56:02 |
| uuid | UUID of the call. | Optional | string | a6c74840-574b-4e6e-baad-6b69bc38ccfc |
| related_call_uuid | UUID of the parent call if the callback was requested from the queue. | Optional | string | 8d1371d2-e166-4677-b158-b1782ddd412d |
| destination_name | The name of destination country. Valid for outbound calls only. | Optional | string | Germany - Other |
With these parameters, you can make a GET request:
{
"method": "GET",
"url": "https://cluster1.voiso.com.voiso.com/api/v2/cdr",
"params": {
"key": "a387aaf1f101fc...fe284aaf61",
"search_token": "dkeouof13kjhk4HHH59",
"page": "1",
"per_page": "20",
"start_date": "2020-04-01",
"end_date": "2020-05-01",
"cli": "197",
"number": "187",
"wildcard_cli": "971231",
"wildcard_number": "7751",
"queue_ids": "199, 201",
"agent_ids": "1,2,3",
"team_ids": "3,4",
"wrapup_codes": "0001, 1002",
"campaign_ids": "15, 13, 22",
"duration_from": "1",
"duration_to": "10",
"dialing_time_from": "1",
"dialing_time_to": "10",
"talk_time_from": "1",
"talk_time_to": "10",
"hold_time_from": "1",
"hold_time_to": "10",
"ivr_time_from": "1",
"ivr_time_to": "10",
"queue_time_from": "1",
"queue_time_to": "10",
"deleted_agent_ids": "15, 16, 17",
"lead_source": "Google ADS",
"start_datetime": "2022-08-19T02:56:02",
"end_datetime": "2022-08-19T02:56:02",
"uuid": "a6c74840-574b-4e6e-baad-6b69bc38ccfc",
"related_call_uuid": "8d1371d2-e166-4677-b158-b1782ddd412d",
"destination_name": "Germany - Other"
}
}
The following table describes the elements of the response.
| Element | Description | Type | Notes |
|---|---|---|---|
| page | Indicates the current page number. | number | |
| total | Indicates the total number of pages in the response. | number | |
| records | An array of interaction records from the Call Detail Records. | array | Refer to the Records table below. |
| search_token | A token that is returned if the response contains more than 10,000 records. | string | Use the token in the next API request to skip the records that have already been returned. Refer to Querying more than 10,000 records above. |
The parameters returned for each record are determined by the interaction type, including voice, SMS, and digital interactions (refer to the Notes column).
| Element | Description | Type | Notes |
|---|---|---|---|
| agent | The name of the user (agent or supervisor) who first handled the interaction. | string | |
| from | The ANI of a voice interaction, the Sender ID of an SMS, or the name of a social media account for digital interactions. | string | |
| disposition | The end-of-call status. | string | Refer to Disposition codes for details. |
| duration | The length of the interaction in hours, minutes, and seconds. | string | Format: hh:mm:ss |
| queue | The inbound queue that distributed the call. | string | Inbound interactions only. |
| to | The DNIS of a voice interaction, the name of the receiver of an SMS, or the name of a social media account for digital interactions. | string | |
| timestamp | The date and time that the interaction ended. | string | The timestamp format is ISO 8601: yyyy-mm-ddThh:mm:ss.sss-hh:mm, where -/+hh:mm is the time zone offset from UTC. |
| uuid | The unique identification code assigned to the interaction. | string | |
| wrapup_code | The Wrap-up code assigned by the agent at the end of the interaction. | string | Refer to Wrap-up codes for details. |
| type | The type of interaction. | string | Valid values include: inbound, outbound, dialer, click-to-call, hlr_ookup, outbound SMS, whatsapp, chat, instagram, facebook, telegram, viber, queue_callback, and scheduled_callback. |
| agent_id | The identification number assigned by the system when the user was created. | number | These can be obtained with the /api/v2/cdr/agents method. |
| cpc | The cost per call or cost to send a message. | number | In U.S. dollars. |
| sid | The Sender ID for SMS interactions. | string | |
| text | The body of the SMS. | string | |
| related_call | The UUID of the interaction related to the SMS. | string | |
| template | The name of the template used for the digital interaction or SMS. | string | |
| num_segments | The number of segments required to contain the complete text of an SMS if the text of the message contains more than 160 characters. | number | Each segment is up to 160 characters in length. |
| destination_name | The name associated with the recipient's phone number. | string | |
| sla | Service Level Agreement parameters that indicate the time to complete each metric. | array | Refer to the SLA table below. |
For digital (chat-based) interactions, the following service level agreement array parameters are included in the sla parameter:
| Element | Description | Type | Notes |
|---|---|---|---|
| time_to_first_response | The duration before an interaction assigned to an agent reaches the maximum allowed time for a first response. | string | Format: hh:mm:ss |
| time_to_resolution | The maximum time that an agent has to archive an interaction. | string | Format: hh:mm:ss |
| time_to_reply | The duration before an interaction assigned to an agent reaches the maximum allowed time for a reply to each text message from a contact. | string | Format: hh:mm:ss |
{
"records": [
{
"agent": "Mike A",
"from": "15557571011",
"disposition": "answered",
"duration": "00:01:19",
"queue": null,
"to": "31208112500",
"timestamp": "2024-07-31T12:43:09.000-03:00",
"uuid": "5d73e973-4103-48ac-84ad-4861155f86db",
"wrapup_code": "0101",
"type": "outbound",
"agent_id": 56215,
"cpc": 0.3972
},
// ... more records ...
{
"agent": "Chandra Agarwal",
"from": "155535189249",
"disposition": "answered",
"duration": "00:00:30",
"queue": null,
"to": "155555554236",
"timestamp": "2024-07-31T11:14:30.000-03:00",
"uuid": "c61c6ebb-d216-4caa-927a-461c8c8cc705",
"wrapup_code": "1007",
"type": "click_to_call",
"agent_id": 52715,
"cpc": 0.0032
},
// ... more records ...
{
"agent": null,
"from": "Guest",
"disposition": "archived",
"duration": "00:00:00",
"to": "Olek's test",
"timestamp": "2024-07-24T06:15:40.407-03:00",
"uuid": "7a221595-6dcd-483a-b37f-65e12317756d",
"wrapup_code": null,
"type": "chat",
"agent_id": null,
"cpc": 0.0,
"sla": {
"time_to_first_response": "00:01:45",
"time_to_resolution": "48:16:27",
"time_to_reply": "00:00:23"
},
"queue": null
}
],
"total": 2632,
"page": 1,
"search_token": "WzE2ODU1Mzg3MTg5ODUsIySjcl9pdGVtIzkzMjUyOGEyLTdhYYZtNGY3Zi04OWIwLWFhY2M4ZDc2OTk5YiJd"
}
Was this page helpful?