CloudTalk API Response Envelope Formats and Schema

Structured responses from the CloudTalk REST API (v1.7) are JSON documents encoded in UTF-8 per RFC 8259. On the core API at my.cloudtalk.io/api, the top-level key is responseData. Understanding the three envelope shapes — single-item, collection, and error — lets you write one parsing layer that handles most core API responses your integration receives.

The responseData envelope is a core API convention, not a platform-wide contract. Call Flow Analytics, Conversation Intelligence, VoiceAgent, CueCard and Dialer each use their own top-level structure — see Envelope Exceptions. Endpoints that return binary content, such as Recording media (audio/x-wav), return no envelope at all.

Envelope Types

The CloudTalk API uses three distinct envelope shapes depending on the nature of the request. Each is described below with its full field reference and a representative JSON example.

Single-Item Envelope

When you request or mutate a single resource on the core API, the API commonly returns an HTTP 200 status and wraps the resource object directly inside responseData. There are no pagination fields — you receive only the object itself.

Single-item response

{
  "responseData": {
    "id": 123,
    "created": "2018-01-10 12:34:56"
  }
}

object

required

The root envelope object for single-item core API responses.

Show fields

integer

The unique identifier of the returned resource.

string

UTC timestamp recording when the resource was created, e.g. 2018-01-10 12:34:56.

A 200 does not always carry a resource. Make a call returns {"responseData": {"status": 200}} and no call record. Core PUT create endpoints return 201; some newer endpoints return 204 with no body at all. Read the status codes and schema on the endpoint’s own reference page.

Collections Envelope

When you query a paginated core API list endpoint, the API returns an HTTP 200 status and wraps the result set inside responseData, together with four pagination metadata fields alongside the data array so you can determine how many pages remain. See the Pagination guide for iteration patterns.

Collection response

{
  "responseData": {
    "itemsCount": 65,
    "pageCount": 3,
    "pageNumber": 1,
    "limit": 30,
    "data": [
      { "id": 123, "created": "2018-01-10 12:34:56" },
      { "id": 456, "created": "2017-10-19 09:21:29" }
    ]
  }
}

object

required

The root envelope object for collection responses.

Show fields

integer int64

required

Total number of resources that match the query across all pages.

integer int64

required

Total number of pages available given the current limit.

integer int64

required

The current page number returned in this response (1-indexed).

integer int64

required

Maximum number of items per page, as applied by the server. Send limit (1–1000) to set it; omit it and the server applies its own default, which this field reports back to you.

array

required

The array of resource objects for the current page. Each element’s schema varies by endpoint.

Not every collection endpoint paginates. List countries puts a plain array directly in responseData, with no itemsCount, pageCount, pageNumber or limit. Treat the four pagination fields as present only where the endpoint documents them.

Error Envelope

When a request to the core API fails, it returns an appropriate HTTP error status code and wraps a short diagnostic payload inside responseData. The status field mirrors the HTTP status code, and message provides a human-readable description. The other surfaces use different error shapes — see the Error Codes reference.

Error response

{
  "responseData": {
    "status": 404,
    "message": "Not Found"
  }
}

object

required

The root envelope object for error responses.

Show fields

integer

required

The HTTP status code that describes the error, e.g. 400, 401, 404, 429.

string

required

A short, human-readable description of the error. Use this field for logging and debugging.

For a complete list of status codes, their meanings, and remediation steps, see the Error Codes reference.

Dates and Timestamps

All date and time values are expressed in UTC, but the exact wire representation varies by endpoint — take it from the endpoint’s own reference page. Both of these forms appear in the API:

Timestamp formats in use

YYYY-MM-DD HH:MM:SS        →   2018-01-10 12:34:56   envelope examples; the
                                                     date_from / date_to filters
YYYY-MM-DDTHH:MM:SS.sssZ   →   2017-10-04T06:33:37.000Z   call record fields such
                                                          as started_at, ended_at

When you store or compare timestamps, ensure your application treats them as UTC to avoid off-by-one-hour bugs around daylight saving transitions.

Envelope Exceptions

The responseData envelope belongs to the core API. Every other surface has its own shape — use this matrix, then confirm against the endpoint’s reference page.

Surface	Base URL	Success shape	Error shape
Core API	`my.cloudtalk.io/api`	`responseData` — single item, or a collection with pagination where documented	`{"responseData": {"status", "message"}}`
Recording media	`my.cloudtalk.io/api`	Binary `audio/x-wav`, no envelope	`{"responseData": {"status", "message"}}`
Call Flow Analytics	`analytics-api.cloudtalk.io/api`	Direct JSON object, no envelope	`{"statusCode", "message", "error"}`
Conversation Intelligence	`api.cloudtalk.io/v1`	Direct per-call object; Topics and Transcription add `{ data, pagination }`	`401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId"}`
VoiceAgent	`api.cloudtalk.io/v1`	`204` with no body on initiate; a direct JSON object on the outbound kill switch	`401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId"}`
CueCard	`platform-api.cloudtalk.io/api`	`{"success": true}`	`{"success": false, "errors": [...]}`
Dialer	`api.cloudtalk.io/v1`	Varies — see below	`401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId", "subErrors?"}`

Dialer

Dialer endpoints do not follow the responseData envelope, and they do not share one shape either. What you get depends on the operation:

List endpoints return { "data": [...], "meta": { "nextCursor": "..." } }. Pass a returned meta.nextCursor back as the cursor query parameter to fetch the next page; a null cursor means there are no more pages.
Single-resource endpoints return the object directly — GET /dialer/campaigns/{campaignId} returns a campaign, not a wrapper.
Some sub-collections return a plain array — GET /dialer/campaigns/{campaignId}/disposition-buttons, for example.
Creates return 201 with the created object. Export requests return 202 with { "jobId", "status" }. Deletes return 204 with no body.

Conversation Intelligence

Conversation Intelligence is organized per call, not as a collection of calls. Each endpoint takes a call ID — /ai/calls/{callId}/summary, /overall-sentiment, /talk-listen-ratio, /topics, /transcription, /smart-notes, /details-link — and returns a direct JSON object at the top level with no responseData wrapper.

Most CI endpoints return their payload flat:

Overall sentiment

{
  "callId": 12345,
  "overallSentiment": "positive"
}

Topics and Transcription are the two that paginate — over the content of a single call, not over calls. They nest the payload under data and add a sibling pagination object:

Transcription (abridged)

{
  "data": {
    "callId": 12345,
    "segments": [
      { "start": 1.501, "end": 4.599, "caller": "caller2", "text": "Hello, I would like to ask for help." }
    ],
    "callers": [
      { "id": 5000, "type": "contact", "localIdentifier": "caller1" }
    ],
    "language": "en"
  },
  "pagination": { "limit": 1, "offset": 0, "total": 10 }
}

Call Flow Analytics

Get call details is served by analytics-api.cloudtalk.io and returns its payload as a direct JSON object — { "cdr_id": 12345, "uuid": "...", "contact": {...}, ... } — with no responseData wrapper. Its errors use { "statusCode", "message", "error" }.

CueCard

The CueCard endpoint also bypasses the standard envelope format. On success it returns {"success": true} directly; on failure, {"success": false, "errors": ["..."]}.

Quick Reference

Single Item

Core API. Usually HTTP 200 with the resource object inside responseData, no pagination metadata — but check for 201, 204 and status-only bodies.

Collection

Core API, where the endpoint documents pagination. HTTP 200 with itemsCount, pageCount, pageNumber, limit, and a data array.

Error

Core API. HTTP 4xx / 5xx with status (mirrors HTTP code) and a human-readable message. Other surfaces differ — see the matrix above.

Getting Started

API Concepts

Changelog

CloudTalk API Response Envelope Formats and Schema

Envelope Types

Single-Item Envelope

Collections Envelope

Error Envelope

Dates and Timestamps

Envelope Exceptions

Dialer

Conversation Intelligence

Call Flow Analytics

CueCard

Quick Reference

Single Item

Collection

Error

​Envelope Types

​Single-Item Envelope

​Collections Envelope

​Error Envelope

​Dates and Timestamps

​Envelope Exceptions

​Dialer

​Conversation Intelligence

​Call Flow Analytics

​CueCard

​Quick Reference

Single Item

Collection

Error

Envelope Types

Single-Item Envelope

Collections Envelope

Error Envelope

Dates and Timestamps

Envelope Exceptions

Dialer

Conversation Intelligence

Call Flow Analytics

CueCard

Quick Reference