API Reference

Get list of CDRs

get
https://{defaultHost}/api/v4/reporting/cdrs

Returns a paginated list of Call Detail Records (CDRs). Use the cursor returned in metadata.next_cursor to continue fetching records beyond the first 10000 results. When cursor is not provided, pagination is limited to the first 10000 records using limit and offset.

The Get list of CDRs endpoint returns a paginated list of interaction records from

Voiso
reporting.

Requirements: Base URL, Authentication, Error codes

Scope: reporting.cdrs.read

What this does

When you send a Get list of CDRs request,

Voiso
returns a list of CDR records that can include multiple interaction types, such as voice calls, digital conversations, SMS, and HLR lookups.

Each record includes a common set of fields, such as id, type, started_at, and ended_at, and a data object that contains type-specific fields.

When to use it

  • Build reporting and audit workflows in an external system
  • Retrieve CDR IDs before calling Get CDR
  • Filter interactions by time range, user, queue, campaign, phone numbers, tags, and more

Endpoint


GET /api/v4/reporting/cdrs

Query parameters

All query parameters are optional.

Pagination:

  • limit
    The number of items to return. Default is 100. Maximum is 1000.

  • offset
    The number of items to skip before collecting results. Default is 0. Ignored when a valid cursor is provided.

  • cursor
    Cursor returned in the previous response metadata as next_cursor. Use it to continue cursor-based pagination. Treat this value as an opaque token and pass it back unchanged.

    If both cursor and offset are provided:

    • If cursor is valid, cursor-based pagination is used and offset is ignored.
    • If cursor is invalid, the API falls back to offset-based pagination.
    • If the fallback offset is also invalid, the API returns 400 Bad Request.

Common filters:

  • started_at
    Filter by start time. Supports comparisons, such as gte and lt.
  • ended_at
    Filter by end time. Supports comparisons, such as gte and lt.
  • type
    Filter by CDR type. Accepts a single value or an array. Values include call, conversation, hlr_lookup, sms.
  • subtype
    Filter by subtype. Accepts a single value or an array.
  • disposition
    Filter by disposition. Accepts a single value or an array.
  • user_id, team_id, queue_id, campaign_id
    Filter by related objects.
  • from_phone_number, to_phone_number
    Filter by exact phone numbers.
  • from_phone_number_like, to_phone_number_like
    Filter by partial phone number match.
  • tag
    Filter by event tags.
  • account_id
    Filter by external account ID. Accepts a single value or an array.

Examples

Minimal request

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by time range and type

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?type=call&started_at[gte]=2025-12-01T00:00:00Z&started_at[lt]=2026-01-01T00:00:00Z&limit=20&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by multiple types

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?type[]=call&type[]=sms&limit=20&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by date and time range

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?started_at[gte]=2026-02-01T00:00:00Z&started_at[lt]=2026-02-02T00:00:00Z&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by type and subtype

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?type=call&subtype=outbound&started_at[gte]=2026-02-01T00:00:00Z&started_at[lt]=2026-02-08T00:00:00Z&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by queue and disposition

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?queue_id=1&disposition=answered&started_at[gte]=2026-02-01T00:00:00Z&started_at[lt]=2026-02-08T00:00:00Z&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by phone number

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?to_phone_number=33123456789&started_at[gte]=2026-02-01T00:00:00Z&started_at[lt]=2026-02-08T00:00:00Z&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by partial phone number match

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?to_phone_number_like=456789&started_at[gte]=2026-02-01T00:00:00Z&started_at[lt]=2026-02-08T00:00:00Z&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by account ID (single value):

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?account_id=123321&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Filter by account ID (multiple values):

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?account_id[]=123321&account_id[]=987654&limit=50&offset=0" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Continue pagination with cursor

Use metadata.next_cursor from the previous response as the cursor query parameter in the next request.

curl -X GET "https://{cluster_id}.voiso.com/api/v4/reporting/cdrs?limit=1000&cursor=WzE3NDcwNDU1NjAwMDAsIjdkN2Y4Yzc0LWRhMDgtNGViMy1iNzc5LTQxMzY0YzEyOWQ4YSJd" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Response

If successful, the API returns an array of CDR records and pagination metadata.

{
  "cdrs": [
    {
      "id": "775a5558-59a6-4468-a502-0deef2a3315d",
      "type": "call",
      "subtype": "outbound",
      "disposition": "answered",
      "from": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "to": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "user": {
        "id": "1234",
        "name": "Jane Doe",
        "email": "[email protected]",
        "name_snapshot": "Snapshot name",
        "deleted": false
      },
      "cost": 0.055,
      "tags": [
        "conference",
        "whisper"
      ],
      "started_at": "2020-08-19T11:32:43.413Z",
      "ended_at": "2020-08-19T11:33:11.031Z",
      "data": {
        "queue": {
          "id": 1,
          "name": "Technical Support",
          "name_snapshot": "Snapshot name",
          "deleted": false
        },
        "campaign": {
          "id": 9,
          "name": "Retention Outreach",
          "name_snapshot": "Snapshot name",
          "deleted": false
        },
        "destination_country": "France",
        "durations": {
          "overall": 27.618,
          "dialing": 5.783,
          "ivr": 0,
          "queue": 10.796,
          "talk": 21.835,
          "hold": 0
        },
        "end_reason": "customer",
        "wrapup_code": {
          "code_snapshot": "0000"
        },
        "summary": "The agent called the customer to follow up on a previous inquiry.",
        "conversation_score": 3.3,
        "mos": 4.37,
        "mos_tc": 3.9
      }
    },
    {
      "id": "3f183f44-1551-45ad-bd6b-d3193b2ff617",
      "type": "conversation",
      "subtype": "whatsapp",
      "disposition": "archived",
      "from": {
        "type": "channel_account",
        "channel_account": {
          "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
          "channel": "whatsapp",
          "identifier": "15551234567",
          "data": {
            "name": "John Smith",
            "username": "johnsmith"
          },
          "name_snapshot": "Snapshot name",
          "deleted": false
        }
      },
      "to": {
        "type": "channel_account",
        "channel_account": {
          "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
          "channel": "whatsapp",
          "identifier": "15551234567",
          "data": {
            "name": "John Smith",
            "username": "johnsmith"
          },
          "name_snapshot": "Snapshot name",
          "deleted": false
        }
      },
      "user": {
        "id": "1234",
        "name": "Jane Doe",
        "email": "[email protected]",
        "name_snapshot": "Snapshot name",
        "deleted": false
      },
      "cost": 0.055,
      "tags": [
        "conference",
        "whisper"
      ],
      "started_at": "2020-08-19T11:32:43.413Z",
      "ended_at": "2020-08-19T11:33:11.031Z",
      "data": {
        "channel": "whatsapp",
        "flow": {
          "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
          "name": "Lead Qualification",
          "name_snapshot": "Snapshot name",
          "deleted": false
        },
        "queue": {
          "id": 1,
          "name": "Technical Support",
          "name_snapshot": "Snapshot name",
          "deleted": false
        },
        "wrapup_code": {
          "code_snapshot": "0000"
        },
        "durations": {
          "overall": 31372.8,
          "queue": 4233.2,
          "talk": 27139.6
        },
        "service_level_agreements": {
          "first_response": {
            "value": 27139.6,
            "status": "ok"
          },
          "resolution": {
            "value": 27139.6,
            "status": "ok"
          },
          "avg_reply": {
            "value": 27139.6,
            "status": "ok"
          }
        }
      }
    },
    {
      "id": "c763ee00-6a2f-4de1-bc9a-01aa5eaa123f",
      "type": "hlr_lookup",
      "subtype": "hlr_lookup",
      "disposition": "available",
      "from": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "to": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "user": {
        "id": "1234",
        "name": "Jane Doe",
        "email": "[email protected]",
        "name_snapshot": "Snapshot name",
        "deleted": false
      },
      "cost": 0.055,
      "tags": [
        "conference",
        "whisper"
      ],
      "started_at": "2020-08-19T11:32:43.413Z",
      "ended_at": "2020-08-19T11:33:11.031Z",
      "data": {
        "reachable": true,
        "roaming": true,
        "related_call": {
          "id": "7d7f8c74-da08-4eb3-b779-41364c129d8a"
        }
      }
    },
    {
      "id": "ff8013c6-8ea1-4d2c-a5c5-816c8ab57a38",
      "type": "sms",
      "subtype": "outbound_sms",
      "disposition": "sent",
      "from": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "to": {
        "type": "phone_number",
        "phone_number": "18885658889"
      },
      "user": {
        "id": "1234",
        "name": "Jane Doe",
        "email": "[email protected]",
        "name_snapshot": "Snapshot name",
        "deleted": false
      },
      "cost": 0.055,
      "tags": [
        "conference",
        "whisper"
      ],
      "started_at": "2020-08-19T11:32:43.413Z",
      "ended_at": "2020-08-19T11:33:11.031Z",
      "data": {
        "sent": true,
        "segments_count": 1,
        "message": "Hi Javier, this is a reminder about your appointment scheduled for 17:00.",
        "canned_message": {
          "id": 10,
          "name": "Payment Confirmation",
          "name_snapshot": "Snapshot name",
          "deleted": false
        },
        "related_call": {
          "id": "7d7f8c74-da08-4eb3-b779-41364c129d8a"
        }
      }
    }
  ],
"metadata": {
  "total": 100,
  "next_cursor": "WzE3NDcwNDU1NjAwMDAsIjdkN2Y4Yzc0LWRhMDgtNGViMy1iNzc5LTQxMzY0YzEyOWQ4YSJd"
}

Notes

  • cdrs[] is polymorphic. The fields inside data depend on the record type.
  • Some fields are nullable depending on the channel and interaction flow.
  • For detailed information about a single record, use the Get CDR endpoint.
  • metadata.next_cursor is returned when cursor-based pagination is supported. Use it as the cursor query parameter to request the next page.
  • Treat cursor as an opaque token. Do not modify or decode it.
  • When cursor is not provided, pagination is limited to the first 10000 records using limit and offset.
  • To retrieve records beyond the first 10000 records, use cursor-based pagination.

Troubleshooting

401 Unauthorized

What to check:

  • You are sending Authorization: Bearer <contact_center_api_key>.
  • Your Base URL includes the correct {cluster_id}.

403 Forbidden

What to check:

  • The API key is valid, but does not have access to reporting resources in this contact center.

422 Unprocessable Entity

Common causes:

  • A filter value is not valid for the parameter.
  • A date time filter is not formatted as ISO 8601.

429 Too many requests

What to do:

  • Reduce request frequency and retry with backoff.
Query Params
integer
0 to 1000
Defaults to 100

The number of items to return.

integer
≥ 0
Defaults to 0

The number of items to skip before starting to collect the result set. Ignored when a valid cursor is provided.

string

Cursor returned in the previous response metadata as next_cursor. Treat this value as an opaque token and pass it back unchanged. If both cursor and offset are provided: a valid cursor takes priority and offset is ignored. If cursor is invalid, the API falls back to offset-based pagination. If the fallback offset is also invalid, the API returns 400 Bad Request.

enum

Filter by CDR type. Accepts a single value or an array.

Filter by external account ID. Accepts a single value or an array.

enum

Filter by CDR subtype. Accepts a single value or an array.

enum

Filter by disposition. Accepts a single value or an array.

Filter by wrap-up code. Accepts a single value or an array.

enum

Filter by end reason. Accepts a single value or an array.

enum

Filter by event tag. Accepts a single value or an array. Special value all_transfers expands to all transfer types.

Filter by caller phone number. Accepts a single value or an array. Cannot be used with from_phone_number_like.

Filter by destination phone number. Accepts a single value or an array of values. Cannot be used with to_phone_number_like.

string

Filter by caller phone number pattern. Use * as a wildcard. Cannot be used with from_phone_number.

string

Filter by destination phone number pattern. Use * as a wildcard. Cannot be used with to_phone_number.

Filter by source channel account ID. Accepts a single value or an array.

Filter by destination channel account ID. Accepts a single value or an array.

Filter by source channel profile ID. Accepts a single value or an array.

Filter by destination channel profile ID. Accepts a single value or an array.

Filter by user ID. Accepts a single value or an array.

Filter by team ID. Accepts a single value or an array.

Filter by queue ID. Accepts a single value or an array.

Filter by campaign ID. Accepts a single value or an array.

Filter by related call ID. Accepts a single value or an array.

Filter by destination country name. Accepts a single value or an array.

≥ 0

Filter by conversation score or score range.

≥ 0

Filter by overall duration (seconds) or by duration range.

≥ 0

Filter by dialing duration (seconds) or by duration range.

≥ 0

Filter by time spent in IVR (seconds) or by a duration range.

≥ 0

Filter by time spent in queue (seconds) or by a duration range.

≥ 0

Filter by time spent talking (seconds) or by a duration range.

≥ 0

Filter by time spent on hold (seconds) or by a duration range.

Filter by start time or by start time range.

Filter by end time or by end time range.

Responses

Updated 19 days ago

Language
Credentials
Bearer
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 19 days ago