CloudTalk REST API v1.7 — Complete Developer Reference

The CloudTalk REST API v1.7 gives you programmatic access to your call center data and operations. It is organized around resources — Calls, Contacts, Agents, Numbers, and more — and follows predictable, resource-oriented URL conventions. All requests must be made over HTTPS, and responses are returned as UTF-8 encoded JSON. Core endpoints wrap payloads in a responseData envelope; some specialized surfaces differ — see the notes below.

Base URLs

Most API endpoints share a single base URL. A handful of specialized capabilities — detailed analytics, AI features, and real-time agent guidance — use their own dedicated hosts.

Purpose	Base URL
Standard API (calls, contacts, agents, etc.)	`https://my.cloudtalk.io/api/`
Detailed call flow analytics	`https://analytics-api.cloudtalk.io/api/`
Conversation Intelligence & VoiceAgent (AI)	`https://api.cloudtalk.io/v1/`
CueCard (real-time agent guidance)	`https://platform-api.cloudtalk.io/api/`
Dialer partner API	`https://api.cloudtalk.io/v1`

Always use the correct base URL for the resource you are accessing. Using the wrong host will result in a 404 response even if the path is correct.

Authentication

Every request to the CloudTalk API must include HTTP Basic Auth credentials — the same key pair on every host. Use your API Access Key ID as the username and your API Access Key Secret as the password.

curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  https://my.cloudtalk.io/api/calls/index.json

Only Administrators can create API keys. You can generate and manage them in the CloudTalk Dashboard under Account → Settings → API Keys (open directly).

Keep your API credentials secure. Do not commit them to source control or expose them in client-side code. Rotate your credentials immediately if they are compromised.

Response Envelope

All successful responses from the standard API are wrapped in a top-level responseData object. Paginated collection endpoints include pagination metadata alongside the data array.

{
  "responseData": {
    "itemsCount": 100,
    "pageCount": 2,
    "pageNumber": 1,
    "limit": 50,
    "data": [ ... ]
  }
}

Single-resource responses omit the pagination fields and return the resource object directly inside responseData.

{
  "responseData": {
    "id": "42",
    "status": "answered",
    ...
  }
}

HTTP Methods

The core API does not use POST and PUT the way most REST APIs do. On my.cloudtalk.io/api, PUT creates and POST updates — the reverse of the usual convention. Reaching for POST to create a resource will not work.

Method	Usage on the core API (`my.cloudtalk.io/api`)
`GET`	Access a resource and perform queries. Never modifies data.
`PUT`	Create a resource — e.g. `PUT /agents/add.json`, `PUT /contacts/add.json`.
`POST`	Update an existing resource — e.g. `POST /agents/edit/{agentId}.json`.
`DELETE`	Delete a resource.

Three core endpoints are actions rather than updates, and use POST for that: Make a call, Send sms and Contact actions. PATCH is not used by the core API.

Newer surfaces use conventional REST

The newer surfaces follow the usual convention, but most expose only a slice of it: Conversation Intelligence is read-only, and VoiceAgent and CueCard are POST-only. Dialer is the only surface with PATCH, PUT or DELETE operations:

Method	Usage
`GET`	Retrieve a resource or a list of resources
`POST`	Create a resource or trigger an action
`PATCH`	Partially update an existing resource
`PUT`	Replace a sub-collection wholesale (Dialer associations, disposition buttons, survey questions)
`DELETE`	Delete a resource

Error Handling

When a request fails, CloudTalk returns an appropriate HTTP status code along with a JSON body describing the error.

{
  "responseData": {
    "status": 404,
    "message": "Call not found"
  }
}

Common status codes you will encounter across all endpoints:

Status	Meaning
`200`	Success
`400`	Bad request — malformed parameters
`401`	Unauthorized — missing or invalid credentials
`403`	Forbidden — action not permitted for this account
`404`	Not found — resource does not exist
`406`	Not acceptable — invalid input value
`409`	Conflict — resource state prevents this action
`410`	Gone — resource existed but has been permanently deleted
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

Pagination

Collection endpoints support pagination via limit and page query parameters. The response envelope includes itemsCount, pageCount, and pageNumber fields to help you iterate through large result sets.

# Fetch page 2 with 100 items per page
curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  'https://my.cloudtalk.io/api/calls/index.json?limit=100&page=2'

The maximum value for limit is 1000.

Resources

The API is divided into the following resource groups:

Calls

Access call history, download recordings, initiate outbound calls, and retrieve real-time group statistics.

Contacts

Create, update, and delete contacts. Manage tags, notes, and contact activity history.

Agents

Manage agent accounts, update agent details, and control group memberships.

Numbers

List and configure the phone numbers assigned to your CloudTalk account.

Groups

Create and manage agent groups, including group membership and routing rules.

SMS & WhatsApp

Send outbound SMS messages and WhatsApp messages to contacts.

Campaigns

Manage outbound dialer campaigns including power dialer and predictive dialer configurations.

Bulks

Perform batch operations on contacts, such as bulk import and bulk tagging.

CueCard

Deliver real-time agent guidance cards during live calls via the CueCard platform API.

Conversation Intelligence

Access AI-powered call analysis including summaries, full transcriptions, and sentiment scores.

VoiceAgent

Initiate AI voice agent calls programmatically, and stop outbound VoiceAgent dialing in an emergency.

Dialer

Manage sales-dialer campaigns, contacts, call scripts, surveys, disposition buttons, statistics, and exports. Separate base URL and response shape; same Basic-auth credentials.

Utilities

Access supporting data such as the countries list and manage the inbound call blacklist.

Rate Limits

CloudTalk enforces rate limits to ensure platform stability. If you exceed the allowed request rate, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle transient rate-limit errors gracefully.

For high-volume integrations, batch your requests using the Bulks endpoints where available, and cache reference data (agents, groups, tags) locally rather than fetching it on every request.

Overview

Endpoints

CloudTalk REST API v1.7 — Complete Developer Reference

Base URLs

Authentication

Response Envelope

HTTP Methods

Newer surfaces use conventional REST

Error Handling

Resources

Calls

Contacts

Agents

Numbers

Groups

SMS & WhatsApp

Tags

Campaigns

Bulks

CueCard

Conversation Intelligence

VoiceAgent

Dialer

Utilities

Rate Limits

​Base URLs

​Authentication

​Response Envelope

​HTTP Methods

​Newer surfaces use conventional REST

​Error Handling

​Pagination

​Resources

Calls

Contacts

Agents

Numbers

Groups

SMS & WhatsApp

Tags

Campaigns

Bulks

CueCard

Conversation Intelligence

VoiceAgent

Dialer

Utilities

​Rate Limits

Base URLs

Authentication

Response Envelope

HTTP Methods

Newer surfaces use conventional REST

Error Handling

Pagination

Resources

Rate Limits