# CloudTalk

> CloudTalk developer documentation — REST API reference and integration guides.

## Docs

- [CloudTalk REST API: Call Center Automation Platform](https://developers.cloudtalk.io/guides/introduction.md): CloudTalk's REST API v1.7 lets engineers automate call center operations — calls, contacts, agents, AI insights, SMS, and more over HTTPS with JSON.
- [How to Authenticate Requests to the CloudTalk REST API](https://developers.cloudtalk.io/guides/authentication.md): The CloudTalk API uses HTTP Basic Auth with an API Access Key ID and Secret on every host. Learn how to generate keys, pass credentials, and secure your requests.
- [Quickstart: Make Your First CloudTalk REST API Call](https://developers.cloudtalk.io/guides/quickstart.md): Get up and running with the CloudTalk REST API in minutes. List calls, initiate outbound calls, and explore the full endpoint library.
- [CloudTalk API Response Envelope Formats and Schema](https://developers.cloudtalk.io/guides/response-envelopes.md): Core CloudTalk API responses use a responseData envelope. Learn the single-item, collection, and error formats, plus the shapes used by Analytics, Conversation Intelligence, VoiceAgent, CueCard and Dialer.
- [How to Paginate CloudTalk API Collection Responses](https://developers.cloudtalk.io/guides/pagination.md): Core CloudTalk collection endpoints use page-based pagination with the page and limit query parameters. Dialer endpoints use cursor pagination instead.
- [CloudTalk API Rate Limits, Headers, and Throttling](https://developers.cloudtalk.io/guides/rate-limiting.md): CloudTalk enforces a 60 requests-per-minute limit per company. Learn how to read rate-limit headers and implement retry logic to avoid 429 errors.
- [CloudTalk API HTTP Error Codes: Causes and Resolutions](https://developers.cloudtalk.io/guides/error-codes.md): Reference for the HTTP status codes returned by the CloudTalk API, with common causes and recommended fixes for 4xx and 5xx errors, plus the error body shapes each surface uses.
- [Changelog](https://developers.cloudtalk.io/changelog.md): Updates to the CloudTalk API and developer documentation
- [CloudTalk REST API v1.7 — Complete Developer Reference](https://developers.cloudtalk.io/api-reference/overview.md): Complete reference for CloudTalk REST API v1.7. All endpoints use HTTP Basic Auth; core endpoints wrap payloads in a responseData envelope, while the Dialer partner API has its own base URL and response shape.
- [Create CueCard](https://developers.cloudtalk.io/api-reference/cuecard/create-cuecard.md): Pushes a CueCard to the agent currently handling a live call, so guidance appears in their CloudTalk interface while the conversation is still in progress. `call_uuid` identifies the live call; `type`, `title` and `content` are also required, and `subtitle` and `icon_url` are optional.
- [List agents](https://developers.cloudtalk.io/api-reference/agents/list-agents.md): Returns agents of the company. `availability_status` reflects the agent's current state; when the agent state source is temporarily unavailable it is returned as "unknown" and the listing still succeeds.
- [Add an agent](https://developers.cloudtalk.io/api-reference/agents/add-an-agent.md): Creates an agent. `firstname`, `lastname`, `email` and `pass` are required. The optional fields allow outbound calling (`status_outbound`), cap daily call spend in EUR (`daily_price_limit`, 1–200), assign a four-digit `extension` that must be unique across the company (1000–9999), and set a default…
- [Edit an agent](https://developers.cloudtalk.io/api-reference/agents/edit-an-agent.md): Updates the agent identified by `agentId`. `firstname`, `lastname` and `email` must be sent on every request, even when unchanged. The agent's password cannot be changed here. Returns `404` if no agent has that ID.
- [Delete an agent](https://developers.cloudtalk.io/api-reference/agents/delete-an-agent.md): Deletes the agent identified by `agentId`. Returns `404` if no agent has that ID.
- [List groups](https://developers.cloudtalk.io/api-reference/groups/list-groups.md): Returns the account's agent groups. Page through the result with `limit` and `page`; the envelope carries `itemsCount`, `pageCount`, `pageNumber` and `limit` alongside the `data` array.
- [Add agent to group](https://developers.cloudtalk.io/api-reference/groups/add-agent-to-group.md): Adds an agent to a group. Both `group_id` and `agent_id` are required and together identify the membership to create.
- [Remove agent from group](https://developers.cloudtalk.io/api-reference/groups/remove-agent-from-group.md): Removes one agent from one group. The agent comes from the `agent_id` path parameter and the group from `group_id` in the request body — this deletes a single membership, not the agent and not the group. Returns `404` if the group does not exist.
- [Contact actions](https://developers.cloudtalk.io/api-reference/bulks/contact-actions.md): Max 10 actions are available in one request. Only sent parameters/values will be updated. If you want to clear the value, just set empty string for that attribute. After sending empty string for properties of `ContactNumber`, `ContactEmail`, `ContactsTag` or `ContactAttribute` all data from these pr…
- [List campaigns](https://developers.cloudtalk.io/api-reference/campaigns/list-campaigns.md): Returns the account's campaigns. Pass `id` to fetch a single campaign, or page through them with `limit` and `page`.
- [Add campaign](https://developers.cloudtalk.io/api-reference/campaigns/add-campaign.md): Creates a campaign. `name` and the `Button` array are required; everything else is optional and configures scheduling (`has_schedule_date`, `schedule_start_date`, `schedule_start_time`), dialing behaviour (`answer_wait_time`, `after_call_dialing_auto`, `after_call_time`, `attempts`, `attempts_interv…
- [Edit campaign](https://developers.cloudtalk.io/api-reference/campaigns/edit-campaign.md): Edit a campaign
- [Delete campaign](https://developers.cloudtalk.io/api-reference/campaigns/delete-campaign.md): Deletes the campaign identified by `id`. Returns `404` if no campaign has that ID.
- [List contacts](https://developers.cloudtalk.io/api-reference/contacts/list-contacts.md): Returns contacts together with their phone numbers, email addresses and custom attributes. Narrow the result with `country_id`, `tag_id`, `industry` or a free-text `keyword`, and page through it with `limit` and `page`.
- [Add contact](https://developers.cloudtalk.io/api-reference/contacts/add-contact.md): Creates a contact. Only `name` is required. The remaining scalar fields describe the company and postal address, and the `ContactNumber`, `ContactEmail`, `ContactsTag`, `ContactAttribute` and `ExternalUrl` arrays attach phone numbers, email addresses, tags, custom attribute values and links to exter…
- [Edit contact](https://developers.cloudtalk.io/api-reference/contacts/edit-contact.md): Only sent parameters/values will be updated. If you want to clear the value, just set empty string for that attribute. After sending empty string for properties of `ContactNumber`, `ContactEmail`, `ContactsTag` or `ContactAttribute` all data from these properties will be cleared. When you send value…
- [Delete contact](https://developers.cloudtalk.io/api-reference/contacts/delete-contact.md): Deletes the contact identified by `contactId`. Returns `404` if no contact has that ID.
- [Inspect a contact](https://developers.cloudtalk.io/api-reference/contacts/inspect-a-contact.md): Returns one contact in full — the contact record plus its phone numbers, email addresses, tags, custom attributes and external URLs. Use this when you already have the contact's ID; use List contacts to search for one.
- [Attributes](https://developers.cloudtalk.io/api-reference/contacts/attributes.md): List all attributes which can be assigned to a contact.
- [Assign Tags](https://developers.cloudtalk.io/api-reference/contacts/assign-tags.md): Assign tags to contact.
- [Unassign Tags](https://developers.cloudtalk.io/api-reference/contacts/unassign-tags.md): Unassign tags to contact.
- [List notes](https://developers.cloudtalk.io/api-reference/contacts/list-notes.md): List all notes assigned to contacts
- [Add note](https://developers.cloudtalk.io/api-reference/contacts/add-note.md): Assign a note to existing contact.
- [Edit note](https://developers.cloudtalk.io/api-reference/contacts/edit-note.md): Updates the note identified by `noteId`. `contact_id` and `note` are required on every request; `user_id` optionally records which agent the note belongs to. Returns `404` if no note has that ID.
- [Delete note](https://developers.cloudtalk.io/api-reference/contacts/delete-note.md): Deletes the note identified by `noteId`. Returns `404` if no note has that ID.
- [List activities](https://developers.cloudtalk.io/api-reference/contacts/list-activities.md): List all activities assigned to contacts
- [Add activity](https://developers.cloudtalk.io/api-reference/contacts/add-activity.md): Assign an activity to existing contact.
- [Edit activity](https://developers.cloudtalk.io/api-reference/contacts/edit-activity.md): Updates the activity identified by `activityId`. `contact_id` is required on every request. The optional fields set the activity `type` (`order`, `task`, `chat`, `ticket`, `other`, `invoice`, `proforma`, `estimate` or `cancel`), its name, timestamp, description and author, and the `external_id` / `e…
- [Delete activity](https://developers.cloudtalk.io/api-reference/contacts/delete-activity.md): Deletes the activity identified by `activityId`. Returns `404` if no activity has that ID.
- [List numbers](https://developers.cloudtalk.io/api-reference/numbers/list-numbers.md): Returns the phone numbers assigned to the account. Filter by `id`, `country_code`, `area_code`, what the number is `connected_to`, or `is_free` to show only numbers with no routing configured; page with `limit` and `page`.
- [Edit a number](https://developers.cloudtalk.io/api-reference/numbers/edit-a-number.md): Updates the number identified by `id`. All three fields are optional: `internal_name` sets the number's internal label, and `connected_to` with `source_id` set what it routes to. To strip a number's routing entirely, use Unregister a number instead. Returns `404` if no number has that ID.
- [Unregister a number](https://developers.cloudtalk.io/api-reference/numbers/unregister-a-number.md): Clear current route settings of the number. Number will be marked as free.
- [List countries](https://developers.cloudtalk.io/api-reference/utilities/list-countries.md): Returns every country CloudTalk recognises, with the `country_id` values used by the contact endpoints. Takes no parameters.
- [List blacklist](https://developers.cloudtalk.io/api-reference/utilities/list-blacklist.md): List blacklisted numbers.
- [Add number to blacklist](https://developers.cloudtalk.io/api-reference/utilities/add-number-to-blacklist.md): Add number to blacklist.
- [Edit number on blacklist](https://developers.cloudtalk.io/api-reference/utilities/edit-number-on-blacklist.md): Edit blacklisted number.
- [Delete number from blacklist](https://developers.cloudtalk.io/api-reference/utilities/delete-number-from-blacklist.md): Delete the number from blacklist.
- [Send sms](https://developers.cloudtalk.io/api-reference/sms/send-sms.md): The success response for sms/send.json may include false success attribute, where attribute data is populated with the provider error message
- [Call history](https://developers.cloudtalk.io/api-reference/calls/call-history.md): Returns call history. Filter by the numbers involved (`public_internal`, `public_external`), a date range (`date_from`, `date_to`), `contact_id`, `user_id`, `agent_extension`, call `type` or `status`, `tag_id`, or a specific `call_id`; page through the result with `limit` and `page`.
- [Get call details](https://developers.cloudtalk.io/api-reference/calls/get-call-details.md): Returns everything recorded about a single call — its timings, the steps it took through the call flow, the agents and contacts involved, tags, rating and notes.
- [Recording media](https://developers.cloudtalk.io/api-reference/calls/recording-media.md): Api endpoint returns media data of recording for selected call. Media data are returned in WAV format.
- [Delete call recording](https://developers.cloudtalk.io/api-reference/calls/delete-call-recording.md): Delete call recording file for good. Call recording will be deleted from all our systems.
- [Make a call](https://developers.cloudtalk.io/api-reference/calls/make-a-call.md): Make a call using to any phone numbers. To place a new outbound call, make an HTTP POST request. At first it will initiate a call to an agent. Maximum waiting time for an agent to pick up the call is 20 seconds. After an agent picks up, we will automatically call desired phone number.
- [Group statistics](https://developers.cloudtalk.io/api-reference/calls/group-statistics.md): Returns today's live call statistics for every group: agents in the group, answered and unanswered calls, abandon rate, average call duration, and average and maximum waiting times — plus a `real_time` block giving the current queue length and waiting times. Takes no parameters.
- [List tags](https://developers.cloudtalk.io/api-reference/tags/list-tags.md): Returns the tags defined in the account. Pass `id` to fetch a single tag, or page through them with `limit` and `page`.
- [Add a tag](https://developers.cloudtalk.io/api-reference/tags/add-a-tag.md): Creates a tag with the given `name`. Returns `201` with the new tag's ID.
- [Edit a tag](https://developers.cloudtalk.io/api-reference/tags/edit-a-tag.md): Renames the tag identified by `id`. `name` is required. Returns `404` if no tag has that ID.
- [Delete a tag](https://developers.cloudtalk.io/api-reference/tags/delete-a-tag.md): Deletes the tag identified by `id`. Returns `404` if no tag has that ID.
- [Summary](https://developers.cloudtalk.io/api-reference/conversation-intelligence/summary.md): Returns the AI-generated summary of a completed call.
- [Overall sentiment](https://developers.cloudtalk.io/api-reference/conversation-intelligence/overall-sentiment.md): Returns the sentiment scored across a completed call as a whole — one of `very negative`, `negative`, `neutral`, `positive` or `very positive`.
- [Talk-listen ratio](https://developers.cloudtalk.io/api-reference/conversation-intelligence/talk-listen-ratio.md): Returns how much each participant spoke during a completed call: talking time in seconds and a talk-to-listen percentage per caller, alongside the list of callers the identifiers refer to.
- [Topics](https://developers.cloudtalk.io/api-reference/conversation-intelligence/topics.md): Returns the topics detected in a completed call, each with a weight and the transcript spans it was drawn from. Page through the result with `limit` and `offset`.
- [Transcription](https://developers.cloudtalk.io/api-reference/conversation-intelligence/transcription.md): Returns the transcript of a completed call as time-stamped segments, each attributed to a caller, together with the detected language. Page through the segments with `limit` and `offset`.
- [Smart notes](https://developers.cloudtalk.io/api-reference/conversation-intelligence/smart-notes.md): Returns the structured notes generated for a completed call — call details, action items, decisions made, open questions and any dates or deadlines mentioned.
- [Call details link](https://developers.cloudtalk.io/api-reference/conversation-intelligence/call-details-link.md): Returns a link to the call's detail page in CloudTalk analytics.
- [Initiate VoiceAgent call](https://developers.cloudtalk.io/api-reference/voiceagent/initiate-voiceagent-call.md): Creates a new VoiceAgent call with specified parameters and properties. Call properties are optional and can be used to configure the call.
- [Stop outbound VoiceAgent calls](https://developers.cloudtalk.io/api-reference/voiceagent/stop-outbound-voiceagent-calls.md): Emergency stop for outbound VoiceAgent dialing.
- [List dialer campaigns](https://developers.cloudtalk.io/api-reference/dialer/list-dialer-campaigns.md): Returns the company's campaigns newest first, cursor-paginated. Pass `meta.nextCursor` from a page back as `cursor` to fetch the following page; a null `nextCursor` means there are no more pages. Soft-deleted campaigns are only returned when explicitly filtered with `status=deleted`.
- [Create a dialer campaign](https://developers.cloudtalk.io/api-reference/dialer/create-a-dialer-campaign.md): Creates a campaign in the `initializing` state: the contact membership defined by its target tags is built asynchronously, after which the campaign can be moved to `active`. Only `name` and `mode` are required — every policy bundle falls back to the service default when omitted. Target tags, queue g…
- [Get a dialer campaign](https://developers.cloudtalk.io/api-reference/dialer/get-a-dialer-campaign.md): Returns a single campaign with its full configuration. A campaign belonging to another company reads as 404.
- [Delete a dialer campaign](https://developers.cloudtalk.io/api-reference/dialer/delete-a-dialer-campaign.md): Soft-deletes the campaign: its status becomes `deleted` (terminal) and its deletion is timestamped. Allowed from any status and idempotent — repeating the call on an already-deleted campaign is a no-op. Returns 409 only while the campaign still has active dialing sessions; end those and retry. Nothi…
- [Update a dialer campaign](https://developers.cloudtalk.io/api-reference/dialer/update-a-dialer-campaign.md): Partially updates the campaign's configuration and/or moves it through its lifecycle. Every key is optional and an omitted key is left unchanged; a supplied policy bundle replaces that bundle wholesale. Legal `status` transitions: `initializing` → `active` | `archived`; `active` ↔ `inactive`; `activ…
- [Get a campaign's associations](https://developers.cloudtalk.io/api-reference/dialer/get-a-campaigns-associations.md): Returns the campaign's associations grouped by kind. Target tags carry their serving `priority`, their `label` and their read-only `origin` provenance; queue groups and agents are returned as plain id arrays.
- [Replace a campaign's associations](https://developers.cloudtalk.io/api-reference/dialer/replace-a-campaigns-associations.md): Replaces every association of the campaign in one call: the contact tags that define its membership (`target_tag`), the queue groups it draws agents from (`queue_group`), and the individually assigned agents (`agent`). Each array is optional and defaults to empty, so an omitted kind clears that kind…
- [Get a campaign's disposition buttons](https://developers.cloudtalk.io/api-reference/dialer/get-a-campaigns-disposition-buttons.md): Returns the campaign's disposition buttons as a plain array ordered by `display_order`, with each button's name, colour and outcome resolved from its referenced call tag.
- [Replace a campaign's disposition buttons](https://developers.cloudtalk.io/api-reference/dialer/replace-a-campaigns-disposition-buttons.md): Replaces the campaign's whole disposition-button set — the buttons an agent picks from to close a call. Each button references a call tag by `tag_id` (list them with the disposition-tags call) and declares the `outcome_kind` that tells the dialer what to do next (retry, reschedule, stop calling, …).…
- [List disposition tags](https://developers.cloudtalk.io/api-reference/dialer/list-disposition-tags.md): Lists the call tags the company can wire onto a campaign's disposition buttons. Use the returned `id` as `tag_id` when replacing a campaign's buttons. The catalogue is returned whole, so `meta.nextCursor` is always null.
- [Get a campaign's statistics](https://developers.cloudtalk.io/api-reference/dialer/get-a-campaigns-statistics.md): Returns the campaign's aggregated performance on one of two bases, told apart by `range` in the response:
- [List a campaign's contacts](https://developers.cloudtalk.io/api-reference/dialer/list-a-campaigns-contacts.md): Returns the campaign's members ordered by dialing eligibility (`next_eligible_at`, then id), cursor-paginated. `meta.total` counts the filtered set, so it moves with `queueTag` and `search`.
- [Peek at the next contacts to be dialed](https://developers.cloudtalk.io/api-reference/dialer/peek-at-the-next-contacts-to-be-dialed.md): Returns, in order, the contacts the allocator would serve next — a read-only, NON-BINDING snapshot. Nothing is held, locked or recorded, so any of these contacts may be taken by an agent a moment later; treat the answer as a display hint, never a reservation. There is no partner-facing way to claim…
- [Get one campaign contact](https://developers.cloudtalk.io/api-reference/dialer/get-one-campaign-contact.md): Returns one campaign membership row, enriched with the contact's current tag names from Contacts. The enrichment is best-effort and fails open: `tags: null` means the tag lookup was unavailable or the contact could not be resolved — it does NOT mean the contact has no tags. A contact that genuinely…
- [Request a campaign data export](https://developers.cloudtalk.io/api-reference/dialer/request-a-campaign-data-export.md): Queues an asynchronous export of the campaign's call history or survey responses as CSV or XLSX and returns immediately with a job handle — nothing is generated during the request. Poll the job with the export-status call.
- [Get an export job's status](https://developers.cloudtalk.io/api-reference/dialer/get-an-export-jobs-status.md): Polls an export job by its id. `status` walks `queued` → `running` → `completed` | `failed`, and `progress` gives a coarse hint of how far the runner has got. A job belonging to another company reads as 404.
- [Get a download link for a completed export](https://developers.cloudtalk.io/api-reference/dialer/get-a-download-link-for-a-completed-export.md): Mints a fresh pre-signed S3 link for a completed export job and returns it in a JSON body together with the instant it expires. This is deliberately not a redirect and not a file stream: the body lets a machine consumer read the expiry, and HTTP clients that strip credentials on redirects cannot mis…
- [List call scripts](https://developers.cloudtalk.io/api-reference/dialer/list-call-scripts.md): Returns the company's call scripts newest first, cursor-paginated. Archived scripts are hidden unless `include_archived=true`.
- [Create a call script](https://developers.cloudtalk.io/api-reference/dialer/create-a-call-script.md): Creates a call script agents read while dialing. The body supports `{{merge}}` fields resolved by the agent's phone at call time. Attach the script to a campaign via the campaign's `call_script_id`.
- [Get a call script](https://developers.cloudtalk.io/api-reference/dialer/get-a-call-script.md): Returns one script by id, archived or not. A script belonging to another company reads as 404.
- [Archive a call script](https://developers.cloudtalk.io/api-reference/dialer/archive-a-call-script.md): Archives the script — a soft delete, never a hard one. The script drops out of the default list but stays readable by id (and via `include_archived=true`), and campaigns already pointing at it keep working. Restore it with `PATCH {"is_archived": false}`. Archiving an already-archived script succeeds…
- [Update a call script](https://developers.cloudtalk.io/api-reference/dialer/update-a-call-script.md): Partial update — omitted fields stay untouched; `updated_at` is always bumped. `is_archived: false` restores an archived script, making this the inverse of the DELETE call.
- [List surveys](https://developers.cloudtalk.io/api-reference/dialer/list-surveys.md): Returns the company's surveys newest first, cursor-paginated. List items are summaries carrying a `question_count` instead of the questions themselves — fetch one survey by id for the full definition. Archived surveys are hidden unless `include_archived=true`.
- [Create a survey](https://developers.cloudtalk.io/api-reference/dialer/create-a-survey.md): Creates a survey agents fill after a call. Omit `questions` to create an empty survey and add questions later with the replace-questions call. Question and option ids are server-generated — never send them. Attach the survey to a campaign via the campaign's `survey_id`.
- [Get a survey](https://developers.cloudtalk.io/api-reference/dialer/get-a-survey.md): Returns one survey by id with its full ordered question set, archived or not. A survey belonging to another company reads as 404.
- [Rename or archive a survey](https://developers.cloudtalk.io/api-reference/dialer/rename-or-archive-a-survey.md): Updates the survey's `name` and/or `is_archived` flag — nothing else is patchable here; questions change only through the replace-questions call. Archiving (`is_archived: true`) is the survey's soft delete: there is deliberately no DELETE route, because archiving preserves the answers already collec…
- [Replace a survey's questions](https://developers.cloudtalk.io/api-reference/dialer/replace-a-surveys-questions.md): Atomically replaces the survey's entire question set — this is a replace, not a merge. The body is the desired end state: existing questions (and their options) are deleted and the provided set is inserted in one transaction, ordered by `display_order`. `{"questions": []}` is valid and clears the su…

## OpenAPI Specs

- [openapi](https://developers.cloudtalk.io/api-reference/openapi.json)