{
"openapi": "3.0.1",
"info": {
"title": "CloudTalk API",
"description": "# Introduction\nWelcome to CloudTalk API reference! Many of these businesses use the CloudTalk API to automate and enhance their customer support with CloudTalk Support. With CloudTalk we are re-building telco industry from the ground and taking it to the next level with first-class customer support system. Please find below the full documenation to CloudTalk.\n\n# API Overview\n\nThe API is organized around the following resources:\n\nAPI Area | Description\n----------------|-------------\nCalls | Browse your call history, download recordings and access all your calls data.\nContacts | Create and update Contacts. Use filters to get lists of Contacts, or access their profiles individually.\nNumbers | Automate Numbers modifications. List all your numbers.\nAgents | Create or update your Agents, access their settings.\nConversation Intelligence | Get Conversation Intelligence data about your calls.\nVoiceAgent | Initiate VoiceAgent calls\n\n\n[JSON](http://www.json.org/) is returned in all responses. XML is not supported.\n\nThe API also uses common approaches for the following:\n\nFunction | Description\n----------------|-------------\nData | API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.\nErrors | 4xx and 5xx responses returning JSON with error codes\nRate Limiting | Controls how many requests can be made in a time window\nHTTP | Methods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.\n\n\n## Authentication\n\nThis is an HTTPS-only API. Authentication is based on API Access Key ID and Access Key Secret. The API Access Key ID and Access Key Secret is passed via HTTP Basic Authentication.\n\n Basic Auth credentials are used to determine on which project should this request be executed on. List of all Basic Auth credentials for the project can be found by Administrators in the CloudTalk Dashboard under Account → Settings → API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).\n\nTo try the API via curl on the command-line, the general form used would be:\n```\ncurl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET API_URL\n```\n\nFor instance, you would execute:\n```\ncurl -u ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An https://my.cloudtalk.io/api/calls/index.json\n```\n\n## Usage\n\nThe API may rate limit submission of requests for your application. Such limits are managed as an allowed number of operations per time window, where an operation might be read or an update. In that case a **'429 Too Many Requests'** response code will be returned along with the following headers -\n\nHeader name | Description\n----------------|-------------\nX-CloudTalkAPI-Limit | Maximum number of API requests allowed in the current time window.\nX-CloudTalkAPI-Remaining | Number of API requests left in the current window.\nX-CloudTalkAPI-ResetTime | Time when rate limit window will be reset as a Unix timestamp.\n\nNote that the default rate limit is **60 operations per minute per company**. If you need to make more requests, please contact our support with detailed explanation of your use case.\n\n## Response Envelopes\n\n**Note:** Conversation Intelligence doesn't follow envelopes.\n\nThe API returns one of three envelopes depending upon the request issued:\n\n1. Single Item Envelope\n2. Collections Envelope\n3. Error Envelope\n\n### Single Item Envelope\n\nAll dates/times are returned in ISO8601 format and in UTC timezone.\n\n```\nStatus: 200 OK\n{\n \"responseData\": {\n \"id\": 123,\n ...\n \"created\": \"2018-01-10 12:34:56\"\n }\n}\n```\n\n### Collections Envelope\n\nAll dates/times are returned in ISO8601 format and in UTC timezone.\n\n```\nStatus: 200 OK\n{\n \"responseData\": {\n \"itemsCount\": 65,\n \"pageCount\": 3,\n \"pageNumber\": 1,\n \"limit\": 30,\n \"data\": [\n {\n \"id\": 123,\n ...\n \"created\": \"2018-01-10 12:34:56\"\n },\n {\n \"id\": 456,\n ...\n \"created\": \"2017-10-19 09:21:29\"\n },\n ...\n ]\n }\n}\n```\n\n### Error Envelope\n\n```\nStatus: 404 Not Found\n{\n \"responseData\": {\n \"status\": 404,\n \"message\": \"Not Found\"\n }\n}\n```\n\n## Encoding\n\nData is encoded as defined by JSON in [RFC4627](http://www.ietf.org/rfc/rfc4627.txt). The default encoding for APIs is UTF-8.\n\nSome query parameters may need to be [url encoded](https://www.wikiwand.com/en/Percent-encoding) when sending - for example, the email parameter value used to query users should be encoded.\n\n## Use of HTTP\n\nRequest methods are used in accordance with HTTP. **On the core API (`my.cloudtalk.io/api`) `PUT` creates and `POST` updates** — the reverse of the more common REST convention:\n\n- `GET` is used to access resources and perform queries. The API does not allow modifications (creates, updates, deletes) to occur via GET.\n- `PUT` is used to create resources.\n- `POST` is used to update resources. PATCH is not used by the core API.\n- `DELETE` is used to delete resources.\n\nDialer is the only surface with `PATCH` operations. Dialer and the VoiceAgent `/voice-agents` and `/knowledge-bases` operations follow the conventional mapping: `POST` creates and `PUT` replaces (on the Dialer, `PATCH` partially updates and `PUT` replaces a sub-collection wholesale). The other newer surfaces expose only a slice of the verbs — Conversation Intelligence is read-only, and CueCard is `POST`-only.\n\nResponses use standard HTTP codes. Where there are client or server errors, a list of of one or more errors in JSON format is returned in the body.\n\nThe `Accept` header must be used by a client used to indicate a preferred response for `GET/HEAD` requests. Requests without an `Accept` header of `application/json` may be rejected with a client error of 404 or 406. The `Content-Type` header should be used by clients to indicate the submitted format for `POST/PUT` requests.",
"contact": {
"name": "CloudTalk API Support",
"url": "https://www.cloudtalk.io/contact"
},
"version": "1.7",
"x-logo": {
"url": "https://my.cloudtalk.io/img/logo-cloudtalk-color.png"
}
},
"servers": [
{
"url": "https://my.cloudtalk.io/api"
}
],
"tags": [
{
"name": "Calls",
"description": "All data you can get about your calls."
},
{
"name": "Contacts",
"description": "All data you can get about your contacts."
},
{
"name": "Agents",
"description": "All data you can get about your agents."
},
{
"name": "Numbers",
"description": "All data you can get about your numbers."
},
{
"name": "Sms",
"description": "Sms handling."
},
{
"name": "Contact tags",
"description": "The tags you create and assign to your contacts."
},
{
"name": "Campaigns",
"description": "All data you can get about your campaigns."
},
{
"name": "Bulks",
"description": "Bulk actions."
},
{
"name": "CueCard",
"description": "CueCards API ver. 1.0.2"
},
{
"name": "Utilities",
"description": "All other helper endpoints."
},
{
"name": "Conversation Intelligence",
"description": "Conversation Intelligence data about your calls."
},
{
"name": "VoiceAgent",
"description": "VoiceAgent API ver. 1.0.0"
},
{
"name": "Dialer",
"description": "Partner API for the CloudTalk sales dialer — campaigns, campaign contacts, call scripts, surveys, disposition buttons, statistics and data exports.\n\nThe Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard. The legacy campaigns API under `/campaigns` is a different product and is not affected.\n\nAuthentication is the same HTTP Basic scheme as the rest of the API — your API Access Key ID as the username and API Access Key Secret as the password. This surface differs from the rest of the CloudTalk API in three ways:\n\n- **Base URL** `https://api.cloudtalk.io/v1` (not `my.cloudtalk.io/api`).\n- **Responses** never use the `responseData` envelope: list endpoints return `{ data, meta }` with cursor pagination (`meta.nextCursor` — pass it back as `cursor` to page forward), single resources return the object directly, and some sub-collections return plain arrays.\n- **Errors** return `{ statusCode, message, error, correlationId, subErrors? }` — except `401`, which is answered by the authentication layer in front of the host as `{ code, message }`. Quote the `correlationId` when contacting support.\n\nRate limiting is per company in a dedicated budget of 60 requests per minute, separate from the core API's quota."
},
{
"name": "Webhooks",
"description": "Manage webhook endpoints: subscriptions, signing secrets, test events and the delivery log. Endpoints created here and in the Dashboard are the same endpoints."
}
],
"paths": {
"/cuecards": {
"post": {
"servers": [
{
"url": "https://platform-api.cloudtalk.io/api/"
}
],
"summary": "Create CueCard",
"description": "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.\n\nCueCard is served by `platform-api.cloudtalk.io`, not the main API host. A `424` means no active call matched `call_uuid` — a card can only be delivered while the call is running.",
"operationId": "postCueCard",
"tags": [
"CueCard"
],
"requestBody": {
"description": "Cue Card request definition",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CueCardRequest"
}
}
}
},
"responses": {
"200": {
"description": "CueCard request processed correctly",
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "boolean"
}
}
},
"example": {
"success": true
}
}
}
},
"400": {
"description": "Request body not matching definition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CueCardError"
},
"example": {
"success": false,
"errors": [
"field validation for 'CallUUID' failed (required)"
]
}
}
}
},
"424": {
"description": "No active call matching call id was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CueCardError"
},
"example": {
"success": false,
"errors": [
"no such active call - call_uuid: aa-bb-cc"
]
}
}
}
},
"500": {
"description": "Unexpected server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CueCardError"
},
"example": {
"success": false,
"errors": [
"error processing cue card"
]
}
}
}
}
}
}
},
"/agents/index.json": {
"get": {
"tags": [
"Agents"
],
"summary": "List agents",
"description": "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.",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter by agent ID",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
},
{
"name": "associated_number",
"in": "query",
"description": "Filters agents by their assigned number. Please enter a valid number in e164 format",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agents data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Agent": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"Agent": {
"id": "99",
"name": "123456",
"firstname": "John",
"lastname": "Doe",
"email": "joh.doe@phoonio.com",
"is_daily_limit_ok": true,
"status_outbound": true,
"availability_status": "online",
"extension": "1001",
"call_number_id": 36,
"default_number": "+421123456789",
"associated_numbers": [
"+421123456789",
"+421987654321"
]
}
}
]
}
}
}
}
}
}
}
},
"/agents/add.json": {
"put": {
"tags": [
"Agents"
],
"summary": "Add an agent",
"description": "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 outbound number (`call_number_id`). Returns `201` with the new agent's ID; `403` means the account has reached its maximum number of agents.\n\nNote the core API creates with `PUT`, not `POST`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"email",
"firstname",
"lastname",
"pass"
],
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name"
},
"lastname": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email",
"format": "email"
},
"pass": {
"type": "string",
"description": "Password"
},
"status_outbound": {
"type": "boolean",
"description": "Does agent have outbound calls allowed?"
},
"daily_price_limit": {
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Daily price limit for all calls in EUR. Usually allowed values are from 1 to 200 EUR. Leave empty for using default value."
},
"extension": {
"maximum": 9999,
"minimum": 1000,
"type": "integer",
"description": "Extension of an agent. Extension must be four digits long and be unique across whole company."
},
"call_number_id": {
"minimum": 1,
"type": "integer",
"description": "Default outbound number ID"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"403": {
"description": "Max. number of agents reached",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 403,
"message": "Max. number of agents reached."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"email": [
"Please supply a valid email address."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/agents/edit/{agentId}.json": {
"post": {
"tags": [
"Agents"
],
"summary": "Edit an agent",
"description": "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.\n\nNote the core API updates with `POST`, not `PUT`.",
"parameters": [
{
"name": "agentId",
"in": "path",
"description": "Agent ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"email",
"firstname",
"lastname"
],
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name"
},
"lastname": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email",
"format": "email"
},
"status_outbound": {
"type": "boolean",
"description": "Does agent have outbound calls allowed?"
},
"daily_price_limit": {
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Daily price limit for all calls in EUR. Usually allowed values are from 1 to 200 EUR. Leave empty for using default value."
},
"call_number_id": {
"minimum": 1,
"type": "integer",
"description": "Default outbound number ID"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"email": [
"Please supply a valid email address."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/agents/delete/{agentId}.json": {
"delete": {
"tags": [
"Agents"
],
"summary": "Delete an agent",
"description": "Deletes the agent identified by `agentId`. Returns `404` if no agent has that ID.",
"parameters": [
{
"name": "agentId",
"in": "path",
"description": "Agent ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Agent not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
}
}
}
},
"/groups/index.json": {
"get": {
"tags": [
"Groups"
],
"summary": "List groups",
"description": "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.",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Groups data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Groups": {
"$ref": "#/components/schemas/Group"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 9,
"pageCount": 1,
"pageNumber": 1,
"limit": 9,
"data": [
{
"Group": {
"id": "568",
"internal_name": "Operátori"
}
}
]
}
}
}
}
}
}
}
},
"/groups/add.json": {
"put": {
"tags": [
"Groups"
],
"summary": "Add agent to group",
"description": "Adds an agent to a group. Both `group_id` and `agent_id` are required and together identify the membership to create.\n\nNote the core API creates with `PUT`, not `POST`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"group_id",
"agent_id"
],
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"description": "Group ID"
},
"agent_id": {
"type": "integer",
"description": "Agent ID"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200,
"data": {
"message": "Agent added successfully."
}
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/groups/delete/{agent_id}.json": {
"delete": {
"tags": [
"Groups"
],
"summary": "Remove agent from group",
"description": "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.",
"parameters": [
{
"name": "agent_id",
"in": "path",
"description": "Agent ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"group_id"
],
"type": "object",
"properties": {
"group_id": {
"type": "integer",
"description": "Group ID"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200,
"data": {
"message": "Agent deleted successfully."
}
}
}
}
}
},
"404": {
"description": "Group not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/bulk/contacts.json": {
"post": {
"tags": [
"Bulks"
],
"summary": "Contact actions",
"description": "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 properties will be cleared. When you send values for properties of `ContactNumber`, `ContactEmail`, `ContactsTag` or `ContactAttribute` only these data will be updated, all other will be cleared.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"maxItems": 10,
"example": [
{
"action": "add_contact",
"command_id": "123",
"data": {
"name": "John Snow",
"title": "Ing.",
"company": "Night watch",
"industry": "it",
"website": "https://www.castleblack.com/",
"address": "Room 1",
"city": "New York",
"zip": "18104",
"state": "NY",
"country_id": 201,
"ContactNumber": [
{
"public_number": 421901123456
}
],
"ContactEmail": [
{
"email": "snow@example.com"
}
],
"ContactsTag": [
{
"name": "watch"
}
]
}
},
{
"action": "delete_contact",
"command_id": "1234",
"data": {
"id": 1234
}
},
{
"action": "edit_contact",
"command_id": "12345",
"data": {
"id": 123,
"name": "Daenerys Stormborn",
"title": "Ing.",
"company": "Targaryen inc.",
"industry": "it",
"website": "https://www.fireandblood.com/",
"address": "First st.",
"zip": "18104",
"state": "NY",
"country_id": 201,
"ContactNumber": [
{
"public_number": 421901123456
},
{
"public_number": 421908123456
}
],
"ContactEmail": [
{
"email": "danny@example.com"
},
{
"email": "targ@example.com"
}
],
"ContactsTag": [
{
"name": "fire"
},
{
"name": "dragons"
}
]
}
},
{
"action": "add_activity",
"command_id": "123456",
"data": {
"contact_id": 123,
"type": "order",
"name": "Burn the usurper",
"activity_date": "2020-08-22T09:53:47.000Z",
"description": "Defeat the forces at kings landing",
"activity_author": "Danny Stormborn",
"external_id": 123456,
"external_url": "https://fireandblood.io/order"
}
},
{
"action": "delete_activity",
"command_id": "1234567",
"data": {
"id": 12345
}
},
{
"action": "edit_activity",
"command_id": "12345678",
"data": {
"id": 123456,
"contact_id": 123456,
"type": "order",
"name": "Defend the Wall",
"activity_date": "2020-08-25T09:53:47.000Z",
"description": "Repel white walkers attack",
"activity_author": "Danny Stormborn",
"external_id": 1234567,
"external_url": "https://fireandblood.com/defend"
}
},
{
"action": "add_note",
"command_id": "123456789",
"data": {
"contact_id": 1234,
"note": "Dont feed the dragon",
"user_id": 12345678
}
},
{
"action": "delete_note",
"command_id": "1234567890",
"data": {
"id": 1234567890
}
},
{
"action": "edit_note",
"command_id": "1234567890A",
"data": {
"id": 123456789,
"note": "Seriously, dont",
"user_id": 1075,
"contact_id": 1234
}
}
],
"items": {
"required": [
"action",
"command_id",
"data"
],
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "Action",
"enum": [
"add_contact",
"edit_contact",
"delete_contact",
"add_activity",
"edit_activity",
"delete_activity",
"add_note",
"edit_note",
"delete_note"
]
},
"command_id": {
"$ref": "#/components/schemas/command_id"
},
"data": {
"oneOf": [
{
"title": "add contact",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name. Only for actions add_contact, edit_contact, add_activity, edit_activity."
},
"title": {
"type": "string",
"description": "Title. Only for actions add_contact, edit_contact."
},
"company": {
"type": "string",
"description": "Company. Only for actions add_contact, edit_contact."
},
"industry": {
"type": "string",
"description": "Industry. Only for actions add_contact, edit_contact."
},
"website": {
"type": "string",
"description": "Website. Only for actions add_contact, edit_contact."
},
"address": {
"type": "string",
"description": "Address. Only for actions add_contact, edit_contact."
},
"city": {
"type": "string",
"description": "City. Only for actions add_contact, edit_contact."
},
"zip": {
"type": "string",
"description": "ZIP. Only for actions add_contact, edit_contact."
},
"state": {
"type": "string",
"description": "State. Only for actions add_contact, edit_contact."
},
"country_id": {
"type": "integer",
"description": "Country ID. Only for actions add_contact, edit_contact."
},
"favorite_agent": {
"type": "integer",
"description": "Favorite agent. Only for actions add_contact, edit_contact."
},
"ExternalUrl": {
"$ref": "#/components/schemas/ExternalUrlArray"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumberArray"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmailArray"
},
"ContactsTag": {
"$ref": "#/components/schemas/ContactsTag"
},
"ContactAttribute": {
"type": "array",
"description": "Attributes for contact. Only for actions add_contact, edit_contact.",
"items": {
"type": "object",
"properties": {
"attribute_id": {
"type": "integer",
"description": "Attribute ID"
},
"value": {
"type": "string",
"description": "Attribute value (max 255 chars per attribute)",
"maxLength": 255
}
}
}
}
}
},
{
"title": "delete contact/note/activity",
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID. Only for actions edit_contact, delete_contact, edit_activity, delete_activity, edit_note, delete_note."
}
}
},
{
"title": "edit contact",
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID. Only for actions edit_contact, delete_contact, edit_activity, delete_activity, edit_note, delete_note."
},
"name": {
"type": "string",
"description": "Name. Only for actions add_contact, edit_contact, add_activity, edit_activity."
},
"title": {
"type": "string",
"description": "Title. Only for actions add_contact, edit_contact."
},
"company": {
"type": "string",
"description": "Company. Only for actions add_contact, edit_contact."
},
"industry": {
"type": "string",
"description": "Industry. Only for actions add_contact, edit_contact."
},
"website": {
"type": "string",
"description": "Website. Only for actions add_contact, edit_contact."
},
"address": {
"type": "string",
"description": "Address. Only for actions add_contact, edit_contact."
},
"city": {
"type": "string",
"description": "City. Only for actions add_contact, edit_contact."
},
"zip": {
"type": "string",
"description": "ZIP. Only for actions add_contact, edit_contact."
},
"state": {
"type": "string",
"description": "State. Only for actions add_contact, edit_contact."
},
"country_id": {
"type": "integer",
"description": "Country ID. Only for actions add_contact, edit_contact."
},
"favorite_agent": {
"type": "integer",
"description": "Favorite agent. Only for actions add_contact, edit_contact."
},
"ExternalUrl": {
"$ref": "#/components/schemas/ExternalUrlArray"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumberArray"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmailArray"
},
"ContactsTag": {
"$ref": "#/components/schemas/ContactsTag"
},
"ContactAttribute": {
"type": "array",
"description": "Attributes for contact. Only for actions add_contact, edit_contact.",
"items": {
"type": "object",
"properties": {
"attribute_id": {
"type": "integer",
"description": "Attribute ID"
},
"value": {
"type": "string",
"description": "Attribute value (max 255 chars per attribute)",
"maxLength": 255
}
}
}
}
}
},
{
"title": "add activity",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name. Only for actions add_contact, edit_contact, add_activity, edit_activity."
},
"contact_id": {
"type": "integer",
"description": "Contact ID. Only for actions add_activity, edit_activity, add_note, edit_note."
},
"type": {
"type": "string",
"description": "Type of activity",
"enum": [
"order",
"task",
"chat",
"ticket",
"other",
"invoice",
"proforma",
"estimate",
"cancel"
]
},
"activity_date": {
"type": "string",
"description": "Activity date and time. Set to current company time by default.",
"format": "date-time"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"activity_author": {
"type": "string",
"description": "Author of activity - user name you want to show"
},
"external_id": {
"type": "integer",
"description": "Activity ID from external resource - e.g. your order ID"
},
"external_url": {
"type": "string",
"description": "External url which can be opened from activity detail"
}
}
},
{
"title": "edit activity",
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID. Only for actions edit_contact, delete_contact, edit_activity, delete_activity, edit_note, delete_note."
},
"name": {
"type": "string",
"description": "Name. Only for actions add_contact, edit_contact, add_activity, edit_activity."
},
"contact_id": {
"type": "integer",
"description": "Contact ID. Only for actions add_activity, edit_activity, add_note, edit_note."
},
"type": {
"type": "string",
"description": "Type of activity",
"enum": [
"order",
"task",
"chat",
"ticket",
"other",
"invoice",
"proforma",
"estimate",
"cancel"
]
},
"activity_date": {
"type": "string",
"description": "Activity date and time. Set to current company time by default.",
"format": "date-time"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"activity_author": {
"type": "string",
"description": "Author of activity - user name you want to show"
},
"external_id": {
"type": "integer",
"description": "Activity ID from external resource - e.g. your order ID"
},
"external_url": {
"type": "string",
"description": "External url which can be opened from activity detail"
}
}
},
{
"title": "add note",
"type": "object",
"properties": {
"contact_id": {
"type": "integer",
"description": "Contact ID. Only for actions add_activity, edit_activity, add_note, edit_note."
},
"user_id": {
"type": "integer",
"description": "Assigned agent ID"
},
"note": {
"type": "string",
"description": "Note content"
}
}
},
{
"title": "edit note",
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID. Only for actions edit_contact, delete_contact, edit_activity, delete_activity, edit_note, delete_note."
},
"contact_id": {
"type": "integer",
"description": "Contact ID. Only for actions add_activity, edit_activity, add_note, edit_note."
},
"user_id": {
"type": "integer",
"description": "Assigned agent ID"
},
"note": {
"type": "string",
"description": "Note content"
}
}
}
]
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"$ref": "#/components/schemas/ContactsBulkDataResponse"
}
}
}
}
},
"example": {
"responseData": {
"status": 200,
"data": [
{
"command_id": "123",
"status": 201,
"data": {
"id": "123"
}
},
{
"command_id": "1234",
"status": 200
},
{
"command_id": "12345",
"status": 200
},
{
"command_id": "123456",
"status": 201,
"data": {
"id": "123456"
}
},
{
"command_id": "1234567",
"status": 200
},
{
"command_id": "12345678",
"status": 200
},
{
"command_id": "12356789",
"status": 201,
"data": {
"id": "123456789"
}
},
{
"command_id": "1234567890",
"status": 200
},
{
"command_id": "123456789A",
"status": 200
}
]
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"email": [
"Please supply a valid email address."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/campaigns/index.json": {
"get": {
"tags": [
"Campaigns"
],
"summary": "List campaigns",
"description": "Returns the account's campaigns. Pass `id` to fetch a single campaign, or page through them with `limit` and `page`.\n\nThese are the campaigns of the original CloudTalk dialer. The newer sales dialer is a separate surface with its own host, authentication and response shape — see the Dialer endpoints.",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter by campaign ID",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Contacts data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Campaign": {
"$ref": "#/components/schemas/CampaignList"
},
"Button": {
"$ref": "#/components/schemas/Button"
},
"Tag": {
"$ref": "#/components/schemas/Tag"
},
"Group": {
"$ref": "#/components/schemas/Group"
},
"Agent": {
"$ref": "#/components/schemas/PdAgent"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"Campaign": {
"id": "63",
"name": "Test Dialer",
"status": "inactive",
"has_schedule_date": false,
"answer_wait_time": "45",
"after_call_dialing_auto": false,
"after_call_time": "5",
"is_recording": false,
"is_predictive": false,
"attempts": "1",
"attempts_interval": "18"
},
"Button": [
{
"id": "252",
"title": "Sale",
"type": "successful_positive",
"color": "#2980b9",
"description": "Sold"
}
],
"ContactsTag": [
{
"id": "133",
"name": "dialer"
}
],
"Group": [
{
"id": "568",
"internal_name": "Agents"
}
],
"Agent": [
{
"id": "1075",
"fullname": "Jane Doe"
}
]
}
]
}
}
}
}
}
}
}
},
"/campaigns/add.json": {
"put": {
"tags": [
"Campaigns"
],
"summary": "Add campaign",
"description": "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_interval`), predictive mode (`is_predictive`, `calls_percentage`), call recording, and which contacts, agents and groups the campaign covers. Returns `201`.\n\nNote the core API creates with `PUT`, not `POST`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"Button",
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"status": {
"type": "string",
"description": "Campaign status (active/inactive)"
},
"has_schedule_date": {
"type": "boolean",
"description": "Is campaign scheduled?"
},
"schedule_start_date": {
"type": "string",
"description": "Campaign start date",
"format": "date"
},
"schedule_start_time": {
"type": "string",
"description": "Campaign start time",
"format": "time"
},
"answer_wait_time": {
"type": "integer",
"description": "Maximum number of seconds we will wait for the call to be answered."
},
"after_call_dialing_auto": {
"type": "boolean",
"description": "Automatically dial next contact after a call ends true/false"
},
"after_call_time": {
"type": "integer",
"description": "After call time (in seconds)"
},
"is_recording": {
"type": "boolean",
"description": "Calls recording true/false"
},
"call_number_id": {
"type": "integer",
"description": "Outbound caller id"
},
"call_script_id": {
"type": "integer",
"description": "Call script ID"
},
"survey_id": {
"type": "integer",
"description": "Survey ID"
},
"is_predictive": {
"type": "integer",
"description": "Is predictive dialer campaign 0/1"
},
"calls_percentage": {
"type": "integer",
"description": "Agents utilization"
},
"attempts": {
"type": "integer",
"description": "Attempts per contact"
},
"attempts_interval": {
"type": "integer",
"description": "Hours between attempts"
},
"Button": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Button title"
},
"type": {
"type": "string",
"enum": [
"successful_positive",
"successful_negative",
"rescheduled",
"unsuccessful_call_again",
"unsuccessful_do_not_call"
],
"description": "Button type"
},
"color": {
"type": "string",
"description": "Button color (hex code)"
},
"description": {
"type": "string",
"description": "Button description"
}
}
}
},
"ContactsTag": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
}
}
}
},
"Agent": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
}
}
}
},
"Group": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Group ID"
}
}
}
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Campaign ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"name": [
"Please supply a valid campaign name."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/campaigns/edit/{id}.json": {
"post": {
"tags": [
"Campaigns"
],
"summary": "Edit campaign",
"description": "Edit a campaign",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Campaign ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"Button",
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"status": {
"type": "string",
"description": "Campaign status (active/inactive)"
},
"has_schedule_date": {
"type": "boolean",
"description": "Is campaign scheduled?"
},
"schedule_start_date": {
"type": "string",
"description": "Campaign start date",
"format": "date"
},
"schedule_start_time": {
"type": "string",
"description": "Campaign start time",
"format": "time"
},
"answer_wait_time": {
"type": "integer",
"description": "Maximum number of seconds we will wait for the call to be answered."
},
"after_call_dialing_auto": {
"type": "boolean",
"description": "Automatically dial next contact after a call ends true/false"
},
"after_call_time": {
"type": "integer",
"description": "After call time (in seconds)"
},
"is_recording": {
"type": "boolean",
"description": "Calls recording true/false"
},
"call_number_id": {
"type": "integer",
"description": "Outbound caller id"
},
"call_script_id": {
"type": "integer",
"description": "Call script ID"
},
"survey_id": {
"type": "integer",
"description": "Survey ID"
},
"is_predictive": {
"type": "integer",
"description": "Is predictive dialer campaign 0/1"
},
"calls_percentage": {
"type": "integer",
"description": "Agents utilization"
},
"attempts": {
"type": "integer",
"description": "Attempts per contact"
},
"attempts_interval": {
"type": "integer",
"description": "Hours between attempts"
},
"Button": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Button id"
},
"title": {
"type": "string",
"description": "Button title"
},
"type": {
"type": "string",
"enum": [
"successful_positive",
"successful_negative",
"rescheduled",
"unsuccessful_call_again",
"unsuccessful_do_not_call"
],
"description": "Button type"
},
"color": {
"type": "string",
"description": "Button color (hex code)"
},
"description": {
"type": "string",
"description": "Button description"
}
}
}
},
"ContactsTag": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
}
}
}
},
"Agent": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
}
}
}
},
"Group": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Group ID"
}
}
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"name": [
"Please supply a valid campaign name."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/campaigns/delete/{id}.json": {
"delete": {
"tags": [
"Campaigns"
],
"summary": "Delete campaign",
"description": "Deletes the campaign identified by `id`. Returns `404` if no campaign has that ID.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Campaign ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Campaign not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/contacts/index.json": {
"get": {
"tags": [
"Contacts"
],
"summary": "List contacts",
"description": "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`.",
"parameters": [
{
"name": "country_id",
"in": "query",
"description": "Filter by country ID",
"schema": {
"type": "integer"
}
},
{
"name": "tag_id",
"in": "query",
"description": "Filter by tag ID",
"schema": {
"type": "integer"
}
},
{
"name": "industry",
"in": "query",
"description": "Filter by industry",
"schema": {
"type": "string"
}
},
{
"name": "keyword",
"in": "query",
"description": "Filter by keyword",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Contacts data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Contact": {
"$ref": "#/components/schemas/ContactList"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumber"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmail"
},
"ContactAttribute": {
"$ref": "#/components/schemas/ContactAttribute"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"Contact": {
"id": "1234",
"name": "John Doe",
"company": "Google"
},
"ContactNumber": {
"public_number": 442012345678
},
"ContactEmail": {
"email": "john.doe@gmail.com"
}
}
]
}
}
}
}
}
}
}
},
"/contacts/add.json": {
"put": {
"tags": [
"Contacts"
],
"summary": "Add contact",
"description": "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 external systems in the same request. Returns `201` with the new contact's ID.\n\nNote the core API creates with `PUT`, not `POST`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name",
"maxLength": 150
},
"title": {
"type": "string",
"description": "Title",
"maxLength": 255
},
"company": {
"type": "string",
"description": "Company name",
"maxLength": 100
},
"industry": {
"type": "string",
"description": "Industry",
"maxLength": 100
},
"website": {
"type": "string",
"description": "Website",
"maxLength": 100
},
"address": {
"type": "string",
"description": "Address",
"maxLength": 255
},
"city": {
"type": "string",
"description": "City",
"maxLength": 255
},
"zip": {
"type": "string",
"description": "ZIP code",
"maxLength": 15
},
"state": {
"type": "string",
"description": "State",
"maxLength": 255
},
"country_id": {
"type": "integer",
"description": "Country ID"
},
"favorite_agent": {
"type": "integer",
"description": "Favorite agent ID"
},
"ExternalUrl": {
"$ref": "#/components/schemas/ExternalUrlArray"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumberArray"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmailArray"
},
"ContactsTag": {
"$ref": "#/components/schemas/ContactsTag"
},
"ContactAttribute": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attribute_id": {
"type": "integer",
"description": "Attribute ID"
},
"value": {
"type": "string",
"description": "Attribute value (max 255 chars per attribute)",
"maxLength": 255
}
}
}
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Contact ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"email": [
"Please supply a valid email address."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/contacts/edit/{contactId}.json": {
"post": {
"tags": [
"Contacts"
],
"summary": "Edit contact",
"description": "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 values for properties of `ContactNumber`, `ContactEmail`, `ContactsTag` or `ContactAttribute` only these data will be updated, all other will be cleared.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name",
"maxLength": 150
},
"title": {
"type": "string",
"description": "Title",
"maxLength": 255
},
"company": {
"type": "string",
"description": "Company name",
"maxLength": 100
},
"industry": {
"type": "string",
"description": "Industry",
"maxLength": 100
},
"website": {
"type": "string",
"description": "Website",
"maxLength": 100
},
"address": {
"type": "string",
"description": "Address",
"maxLength": 255
},
"city": {
"type": "string",
"description": "City",
"maxLength": 255
},
"zip": {
"type": "string",
"description": "ZIP code",
"maxLength": 15
},
"state": {
"type": "string",
"description": "State",
"maxLength": 255
},
"country_id": {
"type": "integer",
"description": "Country ID"
},
"favorite_agent": {
"type": "integer",
"description": "Favorite agent ID"
},
"ExternalUrl": {
"$ref": "#/components/schemas/ExternalUrlArray"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumberArray"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmailArray"
},
"ContactsTag": {
"$ref": "#/components/schemas/ContactsTag"
},
"ContactAttribute": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attribute_id": {
"type": "integer",
"description": "Attribute ID"
},
"value": {
"type": "string",
"description": "Attribute value (max 255 chars per attribute)",
"maxLength": 255
}
}
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"email": [
"Please supply a valid email address."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/contacts/delete/{contactId}.json": {
"delete": {
"tags": [
"Contacts"
],
"summary": "Delete contact",
"description": "Deletes the contact identified by `contactId`. Returns `404` if no contact has that ID.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/contacts/show/{contactId}.json": {
"get": {
"tags": [
"Contacts"
],
"summary": "Inspect a contact",
"description": "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.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID to show",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Contacts data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"Contact": {
"$ref": "#/components/schemas/Contact"
},
"ExternalUrl": {
"$ref": "#/components/schemas/ExternalUrlArray"
},
"ContactNumber": {
"$ref": "#/components/schemas/ContactNumberArray"
},
"ContactEmail": {
"$ref": "#/components/schemas/ContactEmailArray"
},
"ContactsTag": {
"$ref": "#/components/schemas/ContactsTag"
},
"ContactAttribute": {
"$ref": "#/components/schemas/ContactAttribute"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"Contact": {
"id": "1234",
"name": "John Doe",
"title": "Dr.",
"company": "Google",
"industry": "it",
"website": "https://www.google.com/",
"address": "First st.",
"city": "New York",
"zip": "11804",
"state": "NY",
"country_id": "1",
"favorite_agent": "123",
"created": "2017-11-11T15:25:42.000Z",
"modified": "2017-04-26T22:57:50.000Z"
},
"ExternalUrl": [
{
"name": "CRM",
"url": "https://cloudtalk.io/c/show/123"
}
],
"ContactEmail": [
{
"email": "joh.doe@gmail.com"
}
],
"ContactNumber": [
{
"public_number": 442012345678
}
],
"ContactsTag": [
{
"name": "vipClients"
},
{
"name": "shopify"
}
]
}
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
}
}
}
},
"/contacts/attributes.json": {
"get": {
"tags": [
"Contacts"
],
"summary": "Attributes",
"description": "List all attributes which can be assigned to a contact.",
"responses": {
"200": {
"description": "All attributes",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ContactAttribute": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Attribute ID"
},
"title": {
"type": "string",
"description": "Attribute name (max 255 chars per attribute)",
"maxLength": 255
}
}
}
}
}
}
}
},
"example": {
"responseData": [
{
"ContactAttribute": {
"id": "123",
"title": "Salary"
}
},
{
"ContactAttribute": {
"id": "124",
"title": "Custom notes"
}
}
]
}
}
}
}
}
}
},
"/contacts/addTags/{contactId}.json": {
"put": {
"tags": [
"Contacts"
],
"summary": "Assign contact tags",
"description": "Assign contact tags to a contact.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID for adding tags",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"tags"
],
"type": "object",
"properties": {
"tags": {
"type": "array",
"description": "Array of tag names",
"items": {
"type": "string"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Tags assigned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"message": {
"type": "string",
"description": "Success message"
},
"data": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
}
}
},
"contact_id": {
"type": "string",
"description": "Contact ID"
}
},
"description": "Data of assigned tags"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200,
"message": "Tags were sucessfully added.",
"data": {
"tags": [
{
"id": "123",
"name": "First"
},
{
"id": "456",
"name": "Second"
},
{
"id": "789",
"name": "Third"
}
],
"contact_id": "123456"
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/contacts/removeTags/{contactId}.json": {
"delete": {
"tags": [
"Contacts"
],
"summary": "Unassign contact tags",
"description": "Unassign contact tags from a contact. If a removed tag is one an AI Sales Dialer campaign uses to add contacts, the contact is taken out of that campaign's queue within about 5 minutes. A call already in progress isn't interrupted.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID for deleting tags",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"tags"
],
"type": "object",
"properties": {
"tags": {
"type": "array",
"description": "Array of tag names",
"items": {
"type": "string"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Tags unassigned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"message": {
"type": "string",
"description": "Success message"
},
"data": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
}
}
},
"contact_id": {
"type": "string",
"description": "Contact ID"
}
},
"description": "Data of unassigned tags"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200,
"message": "Tags were successfully removed.",
"data": {
"tags": [
{
"id": "123",
"name": "First"
},
{
"id": "456",
"name": "Second"
},
{
"id": "789",
"name": "Third"
}
],
"contact_id": "123456"
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/notes/index.json": {
"get": {
"tags": [
"Contacts"
],
"summary": "List notes",
"description": "List all notes assigned to contacts",
"parameters": [
{
"name": "contact_id",
"in": "query",
"description": "Filter by contact ID",
"schema": {
"type": "integer"
}
},
{
"name": "user_id",
"in": "query",
"description": "Filter by agent ID",
"schema": {
"type": "integer"
}
},
{
"name": "keyword",
"in": "query",
"description": "Filter by keyword in note content",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Notes data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ContactNote": {
"$ref": "#/components/schemas/ContactNote"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"ContactNote": {
"id": "1234",
"contact_id": "567",
"user_id": "456",
"note": "Note content...",
"created": "2018-05-01T12:12:12.000Z"
}
}
]
}
}
}
}
}
}
}
},
"/notes/add/{contactId}.json": {
"put": {
"tags": [
"Contacts"
],
"summary": "Add note",
"description": "Assign a note to existing contact.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID to which note will be assigned",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"note"
],
"type": "object",
"properties": {
"user_id": {
"type": "integer",
"description": "Assigned agent ID"
},
"note": {
"type": "string",
"description": "Note content"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Note ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"note": [
"This field is required."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/notes/edit/{noteId}.json": {
"post": {
"tags": [
"Contacts"
],
"summary": "Edit note",
"description": "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.\n\nNote the core API updates with `POST`, not `PUT`.",
"parameters": [
{
"name": "noteId",
"in": "path",
"description": "Note ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"contact_id",
"note"
],
"type": "object",
"properties": {
"contact_id": {
"type": "integer",
"description": "Assigned contact ID"
},
"user_id": {
"type": "integer",
"description": "Assigned agent ID"
},
"note": {
"type": "string",
"description": "Note content"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"note": [
"This field is required."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/notes/delete/{noteId}.json": {
"delete": {
"tags": [
"Contacts"
],
"summary": "Delete note",
"description": "Deletes the note identified by `noteId`. Returns `404` if no note has that ID.",
"parameters": [
{
"name": "noteId",
"in": "path",
"description": "Note ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Note not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/activity/index.json": {
"get": {
"tags": [
"Contacts"
],
"summary": "List activities",
"description": "List all activities assigned to contacts",
"parameters": [
{
"name": "contact_id",
"in": "query",
"description": "Filter by contact ID",
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by type - check below for possible values",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Activities data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ContactActivity": {
"$ref": "#/components/schemas/ContactActivity"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"ContactActivity": {
"id": "1234",
"contact_id": "567",
"type": "order",
"name": "Order #201712399",
"description": "Content of order...",
"activity_author": "John Doe",
"external_id": "201712399",
"external_url": "https://www.shopify.com/orders/detail/999",
"activity_date": "2018-02-02T12:12:12.000Z",
"created": "2018-05-01T12:12:12.000Z"
}
}
]
}
}
}
}
}
}
}
},
"/activity/add/{contactId}.json": {
"put": {
"tags": [
"Contacts"
],
"summary": "Add activity",
"description": "Assign an activity to existing contact.",
"parameters": [
{
"name": "contactId",
"in": "path",
"description": "Contact ID to which activity will be assigned",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"name",
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of activity",
"enum": [
"order",
"task",
"chat",
"ticket",
"other",
"invoice",
"proforma",
"estimate",
"cancel"
]
},
"name": {
"type": "string",
"description": "Name/Title"
},
"activity_date": {
"type": "string",
"description": "Activity date and time. Set to current company time by default.",
"format": "date-time"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"activity_author": {
"type": "string",
"description": "Author of activity - user name you want to show"
},
"external_id": {
"type": "integer",
"description": "Activity ID from external resource - e.g. your order ID"
},
"external_url": {
"type": "string",
"description": "External url which can be opened from activity detail"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Activity ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"name": [
"This field is required."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/activity/edit/{activityId}.json": {
"post": {
"tags": [
"Contacts"
],
"summary": "Edit activity",
"description": "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` / `external_url` pair that links it back to the system it came from. Returns `404` if no activity has that ID.\n\nNote the core API updates with `POST`, not `PUT`.",
"parameters": [
{
"name": "activityId",
"in": "path",
"description": "Activity ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"contact_id"
],
"type": "object",
"properties": {
"contact_id": {
"type": "integer",
"description": "Assigned contact ID"
},
"type": {
"type": "string",
"description": "Type of activity",
"enum": [
"order",
"task",
"chat",
"ticket",
"other",
"invoice",
"proforma",
"estimate",
"cancel"
]
},
"name": {
"type": "string",
"description": "Name/Title"
},
"activity_date": {
"type": "string",
"description": "Activity date and time. Set to current company time by default.",
"format": "date-time"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"activity_author": {
"type": "string",
"description": "Author of activity - user name you want to show"
},
"external_id": {
"type": "integer",
"description": "Activity ID from external resource - e.g. your order ID"
},
"external_url": {
"type": "string",
"description": "External url which can be opened from activity detail"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"contact_id": [
"This field is required."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/activity/delete/{activityId}.json": {
"delete": {
"tags": [
"Contacts"
],
"summary": "Delete activity",
"description": "Deletes the activity identified by `activityId`. Returns `404` if no activity has that ID.",
"parameters": [
{
"name": "activityId",
"in": "path",
"description": "Activity ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Activity not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/numbers/index.json": {
"get": {
"tags": [
"Numbers"
],
"summary": "List numbers",
"description": "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`.",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter by number ID",
"schema": {
"type": "integer"
}
},
{
"name": "country_code",
"in": "query",
"description": "Filter by country calling code",
"schema": {
"type": "integer"
}
},
{
"name": "area_code",
"in": "query",
"description": "Filter by local area code. Area code cannot contain 0 at the beginning",
"schema": {
"type": "integer"
}
},
{
"name": "connected_to",
"in": "query",
"description": "Filter by route type. `0 = 'group'`, `1 = 'agent'`, `2 = 'conference room'`, `3 = 'fax'`",
"schema": {
"type": "integer",
"enum": [
0,
1,
2,
3
]
}
},
{
"name": "is_free",
"in": "query",
"description": "Filter by availability. `0 = 'taken'`, `1 = 'free'`",
"schema": {
"type": "integer",
"enum": [
0,
1
]
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Numbers data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"CallNumber": {
"$ref": "#/components/schemas/CallNumber"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"CallNumber": {
"id": "123",
"country_code": "44",
"area_code": "20",
"internal_name": "Sales support",
"caller_id_e164": 442012345678,
"is_redirected": false,
"connected_to": "1",
"source_id": "4"
}
}
]
}
}
}
}
}
}
}
},
"/numbers/edit/{id}.json": {
"post": {
"tags": [
"Numbers"
],
"summary": "Edit a number",
"description": "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.\n\nNote the core API updates with `POST`, not `PUT`.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Number ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"internal_name": {
"type": "string",
"description": "Internal name"
},
"connected_to": {
"type": "integer",
"description": "Routing type. Where is the number connected. `0 = 'group'`, `1 = 'agent'`, `2 = 'conference room'`, `3 = 'fax'`"
},
"source_id": {
"type": "integer",
"description": "Source ID of where is the number located, e.g. Agent ID, Group ID..."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"type": [
"Please supply a valid type."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/numbers/clear/{id}.json": {
"delete": {
"tags": [
"Numbers"
],
"summary": "Unregister a number",
"description": "Clear current route settings of the number. Number will be marked as free.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Number ID to unregister",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Number not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/countries/index.json": {
"get": {
"tags": [
"Utilities"
],
"summary": "List countries",
"description": "Returns every country CloudTalk recognises, with the `country_id` values used by the contact endpoints. Takes no parameters.",
"responses": {
"200": {
"description": "All countries",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Country": {
"$ref": "#/components/schemas/Country"
}
}
}
}
}
},
"example": {
"responseData": [
{
"Country": {
"id": "61",
"name": "Denmark",
"country_code": "DK",
"iso3": "DNK",
"calling_code": "45"
}
},
{
"Country": {
"id": "235",
"name": "United Kingdom",
"country_code": "GB",
"iso3": "GBR",
"calling_code": "44"
}
}
]
}
}
}
}
}
}
},
"/blacklist/index.json": {
"get": {
"tags": [
"Utilities"
],
"summary": "List blacklist",
"description": "List blacklisted numbers.",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter by ID",
"schema": {
"type": "integer"
}
},
{
"name": "country_code",
"in": "query",
"description": "Filter by country calling code",
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by type",
"schema": {
"type": "string",
"enum": [
"all",
"incoming",
"outgoing"
]
}
},
{
"name": "public_number",
"in": "query",
"description": "Filter by number",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Blacklist data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Blacklist": {
"$ref": "#/components/schemas/Blacklist"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 2,
"pageCount": 1,
"pageNumber": 1,
"limit": 2,
"data": [
{
"Blacklist": {
"id": "123",
"type": "all",
"public_number": 442012345678
}
},
{
"Blacklist": {
"id": "456",
"type": "incoming",
"public_number": 442012345679
}
}
]
}
}
}
}
}
}
}
},
"/blacklist/add.json": {
"put": {
"tags": [
"Utilities"
],
"summary": "Add number to blacklist",
"description": "Add number to blacklist.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"public_number",
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of calls",
"enum": [
"all",
"incoming",
"outgoing"
]
},
"public_number": {
"type": "string",
"description": "Blacklisted number in E.164 format"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Blacklist ID"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"public_number": [
"Please supply only valid numbers. Number +441234 is not valid."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/blacklist/edit/{id}.json": {
"post": {
"tags": [
"Utilities"
],
"summary": "Edit number on blacklist",
"description": "Edit blacklisted number.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"public_number",
"type"
],
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of calls",
"enum": [
"all",
"incoming",
"outgoing"
]
},
"public_number": {
"type": "string",
"description": "Blacklisted number in E.164 format"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"public_number": [
"Please supply only valid numbers. Number +441234 is not valid."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/blacklist/delete/{id}.json": {
"delete": {
"tags": [
"Utilities"
],
"summary": "Delete number from blacklist",
"description": "Delete the number from blacklist.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Blacklist not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
}
}
},
"/sms/send.json": {
"post": {
"tags": [
"Sms"
],
"summary": "Send sms",
"description": "The success response for sms/send.json may include false success attribute, where attribute data is populated with the provider error message\n\nThere is no bulk SMS endpoint: each request sends one message to one recipient. To message many recipients, send one request per message and stay within your [rate limits](/guides/rate-limiting).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"message",
"recipient",
"sender"
],
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "Recipient number in E.164 format. To send Whatsapp message include prefix \"whatsapp:+421...\" to both sender and recipient numbers."
},
"message": {
"type": "string",
"description": "Message body/content."
},
"sender": {
"type": "string",
"description": "Sender number in E.164 format. To send Whatsapp message include prefix \"whatsapp:+421...\" to both sender and recipient numbers."
},
"country_code": {
"type": "string",
"description": "Country code of recipient number."
},
"images_by_url": {
"type": "array",
"items": {
"type": "string"
},
"description": "Image to be send as MMS. Will be downloaded from URL. MAX 5MB. Can contain up to 5 urls."
},
"images": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"description": "Image sent as blob to be send as MMS. MAX 5MB. Can contain up to 5 images."
},
"file_by_url": {
"type": "string",
"description": "File to be send to Whatsapp. Will be downloaded from URL. MAX 16MB. To send Whatsapp message recipient and sender number must contain prefix \"whatsapp:\" example \"whatsapp:+421...\". Field message must be empty."
},
"file": {
"type": "string",
"format": "binary",
"description": "File sent as blob to be send to Whatsapp. MAX 16MB. To send Whatsapp message recipient and sender number must contain prefix \"whatsapp:\" example \"whatsapp:+421...\". Field message must be empty."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Status of sms sending",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Success result"
},
"data": {
"type": "object",
"description": "If success is true, data contains object with properties : recipent,message, sender and country_code, else if success is false, data contains error message"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"success": "true|false",
"data": "{'recipient': 'string','message': 'string','sender': 'string','country_code': 'string'}\n |SMS send failed|Not allowed country.|Unknown number|Limit exceeded|Bad number configuration"
}
}
}
}
},
"400": {
"description": "Bad request ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 400,
"message": "Bad request"
}
}
}
}
},
"401": {
"description": "Unauthorized action ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 401,
"message": "Unauthorized action"
}
}
}
}
},
"403": {
"description": "Insufficient Funds",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 403,
"message": "Insufficient Funds"
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/calls/index.json": {
"get": {
"tags": [
"Calls"
],
"summary": "Call history",
"description": "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`.",
"parameters": [
{
"name": "public_internal",
"in": "query",
"description": "Filter by internal number of agent",
"schema": {
"type": "string"
}
},
{
"name": "public_external",
"in": "query",
"description": "Filter by number of caller",
"schema": {
"type": "string"
}
},
{
"name": "date_from",
"in": "query",
"description": "Filter by date from, e.g. 2017-12-24 12:22:00",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "date_to",
"in": "query",
"description": "Filter by date to, napríklad 2017-12-24 12:22:00",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "contact_id",
"in": "query",
"description": "Filter by assigned contact ID",
"schema": {
"type": "integer"
}
},
{
"name": "user_id",
"in": "query",
"description": "Filter by assigned agent ID",
"schema": {
"type": "integer"
}
},
{
"name": "agent_extension",
"in": "query",
"description": "Filter by assigned agent's extension.",
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "query",
"description": "Filter by call type",
"schema": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"internal"
]
}
},
{
"name": "status",
"in": "query",
"description": "Filter by call status - 'missed' = for only missed calls, 'answered' = for all answered calls",
"schema": {
"type": "string",
"enum": [
"missed",
"answered"
]
}
},
{
"name": "tag_id",
"in": "query",
"description": "Filter by assigned call tag ID",
"schema": {
"type": "integer"
}
},
{
"name": "call_id",
"in": "query",
"description": "Filter by call ID",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Calls data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Cdr": {
"$ref": "#/components/schemas/Cdr"
},
"Contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Contact ID"
},
"name": {
"type": "string",
"description": "Name",
"maxLength": 150
},
"title": {
"type": "string",
"description": "Title",
"maxLength": 255
},
"company": {
"type": "string",
"description": "Company name",
"maxLength": 100
},
"industry": {
"type": "string",
"description": "Industry",
"maxLength": 100
},
"address": {
"type": "string",
"description": "Address",
"maxLength": 255
},
"city": {
"type": "string",
"description": "City",
"maxLength": 255
},
"zip": {
"type": "string",
"description": "ZIP code",
"maxLength": 15
},
"state": {
"type": "string",
"description": "State",
"maxLength": 255
},
"type": {
"type": "string",
"description": "Type of contact (contact/lead)"
},
"contact_numbers": {
"type": "array",
"description": "Array of contact numbers",
"items": {
"type": "string"
}
},
"contact_emails": {
"type": "array",
"description": "Array of contact emails",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"description": "Array of contact tags",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
}
}
},
"external_urls": {
"type": "array",
"description": "Array of contact external urls",
"items": {
"type": "object",
"properties": {
"external_system": {
"type": "string",
"description": "Name of external service. Name will be shown to agents while working with contacts."
},
"external_url": {
"type": "string",
"description": "External URL to contact page"
}
}
}
},
"custom_fields": {
"type": "array",
"description": "Array of contact emails",
"items": {
"type": "object",
"maximum": 255,
"properties": {
"key": {
"type": "string",
"description": "Custom field key (max 255 chars per attribute)"
},
"value": {
"type": "string",
"description": "Custom field value (max 255 chars per attribute)"
}
}
}
},
"favorite_agent": {
"$ref": "#/components/schemas/FavoriteAgent"
}
},
"description": "Contact assigned to this call"
},
"CallNumber": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Number ID"
},
"internal_name": {
"type": "string",
"description": "Internal name"
},
"caller_id_e164": {
"type": "string",
"description": "Full number in international E.164 format"
},
"country_code": {
"type": "integer",
"description": "Country calling code"
},
"area_code": {
"type": "integer",
"description": "Local area code"
}
},
"description": "Internal number assigned to this call"
},
"BillingData": {
"$ref": "#/components/schemas/BillingData"
},
"Agent": {
"$ref": "#/components/schemas/AgentCall"
},
"Notes": {
"$ref": "#/components/schemas/CallNote"
},
"Tags": {
"$ref": "#/components/schemas/CallTag"
},
"Ratings": {
"$ref": "#/components/schemas/CallRating"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"Cdr": {
"id": "27",
"billsec": "0",
"type": "outgoing",
"country_code": "421",
"public_external": 421904247371,
"public_internal": 421221291400,
"recorded": true,
"is_voicemail": false,
"fax_email": "0",
"is_redirected": "0",
"redirected_from": "",
"is_local": true,
"user_id": "1234",
"talking_time": "21",
"started_at": "2017-10-04T06:33:37.000Z",
"answered_at": "2017-10-04T06:33:37.000Z",
"ended_at": "2017-10-04T06:33:49.000Z",
"waiting_time": 2,
"wrapup_time": 5,
"recording_link": "https://analytics.cloudtalk.io/call-details/27"
},
"Contact": {
"id": "1234",
"name": "Jon Doe",
"title": "title",
"company": "First ltd.",
"industry": "IT",
"address": "8th Avenue",
"city": "London",
"zip": "838298",
"state": "England",
"type": "contact",
"tags": [
{
"id": "615",
"name": "VIP"
},
{
"id": "609",
"name": "Security"
}
],
"external_urls": [
{
"external_system": "CloudTalk",
"external_url": "https://my.cloudtalk.io/c/show/1234"
}
],
"contact_numbers": [
18884871675
],
"contact_emails": [
"jon.doe@first.com"
],
"custom_fields": [
{
"key": "age",
"value": "33"
}
],
"favorite_agent": {
"id": "1234",
"firstname": "Max",
"lastname": "Yellow",
"fullname": "Max Yellow",
"email": "max.yellow@cloudtalk.io",
"language": "en",
"role": "Admin",
"status": "online",
"default_outbound_number": 442012345678,
"associated_numbers": [
442012345678
],
"groups": [
"sales",
"support"
]
}
},
"CallNumber": {
"id": "12345",
"internal_name": "Sales support",
"caller_id_e164": 442012345678,
"country_code": "44",
"area_code": "20"
},
"BillingCall": {
"price": "0.000000"
},
"Agent": {
"id": "1234",
"firstname": "Max",
"lastname": "Yellow",
"fullname": "Max Yellow",
"email": "max.yellow@cloudtalk.io",
"language": "en",
"role": "Admin",
"status": "online",
"default_outbound_number": 442012345678,
"associated_numbers": [
442012345678
],
"groups": [
"sales",
"support"
]
},
"Notes": [
{
"id": "23",
"note": "Call later"
}
],
"Tags": [
{
"id": "123",
"name": "Missed"
},
{
"id": "124",
"name": "VIP"
}
]
}
]
}
}
}
}
}
}
}
},
"/calls/{callId}": {
"get": {
"servers": [
{
"url": "https://analytics-api.cloudtalk.io/api/"
}
],
"tags": [
"Calls"
],
"summary": "Get call details",
"description": "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.\n\nThis endpoint is served by `analytics-api.cloudtalk.io`, not the main API host. Returns `400` if `callId` is malformed and `404` if no such call exists.",
"parameters": [
{
"name": "callId",
"in": "path",
"required": true,
"description": "ID of a call",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Detailed information about a given call",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Call"
},
"example": {
"cdr_id": 12345,
"uuid": "aaaa-bbbb-cccc-dddd",
"company_id": 100123,
"date": "2022-02-07T13:00:00.000Z",
"contact": {
"id": 1,
"name": "John Doe",
"country": "CZ",
"number": "+420123123123"
},
"call_tags": [
{
"id": 5,
"label": "Lead"
}
],
"call_rating": 3,
"internal_number": {
"id": 1,
"name": "Europe Sales",
"number": "+421456456456"
},
"call_times": {
"talking_time": 60,
"wrap_up_time": 10,
"ringing_time": 10,
"total_time": 80,
"waiting_time": 20,
"holding_time": 5
},
"direction": "incoming",
"type": "regular",
"status": "answered",
"call_steps": [
{
"type": "ivr",
"id": 1,
"date": "2022-02-07T13:00:00.000Z",
"total_time": 10,
"option": "1"
},
{
"type": "queue",
"id": 10,
"name": "Queue10",
"date": "2022-02-07T13:00:10.000Z",
"call_times": {
"talking_time": 60,
"wrap_up_time": 10,
"ringing_time": 10,
"total_time": 80,
"waiting_time": 10,
"holding_time": 3
},
"status": "answered",
"reason": null,
"resolved_by": null,
"resolved_by_call": {
"id": null,
"date": null,
"agent": {
"id": null,
"name": null
}
},
"strategy": "rrmemory",
"agent_calls": [
{
"type": "agent",
"id": 12,
"name": "Agent12",
"group_ids": [
10,
20
],
"date": "2022-02-07T13:00:10.000Z",
"call_times": {
"talking_time": null,
"wrap_up_time": null,
"ringing_time": 5,
"total_time": 5,
"holding_time": null
},
"status": "missed",
"reason": "offline",
"resolved_by": null,
"resolved_by_call": {
"id": null,
"date": null,
"agent": {
"id": null,
"name": null
}
}
},
{
"type": "agent",
"id": 11,
"name": "Agent11",
"group_ids": [
10,
20
],
"date": "2022-02-07T13:00:15.000Z",
"call_times": {
"talking_time": 60,
"wrap_up_time": 10,
"ringing_time": 5,
"total_time": 75,
"holding_time": 2
},
"status": "answered",
"reason": null,
"resolved_by": null,
"resolved_by_call": {
"id": null,
"date": null,
"agent": {
"id": null,
"name": null
}
}
}
]
}
],
"notes": [
"string"
],
"recorded": true,
"out_of_office": false
}
}
}
},
"400": {
"description": "Bad Request - Invalid call ID",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"description": "Status code"
},
"message": {
"type": "string",
"description": "The error message"
},
"error": {
"type": "string",
"description": "The error name"
}
}
},
"example": {
"statusCode": 400,
"message": [
"callId must be a number conforming to the specified constraints"
],
"error": "Bad Request"
}
}
}
},
"404": {
"description": "Call not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"description": "Status code"
},
"message": {
"type": "string",
"description": "The error message"
},
"error": {
"type": "string",
"description": "The error name"
}
}
},
"example": {
"statusCode": 404,
"message": "Call with id '12456' doesn't exist on company '100123'",
"error": "Not Found"
}
}
}
}
}
}
},
"/calls/recording/{callId}.json": {
"get": {
"tags": [
"Calls"
],
"summary": "Recording media",
"description": "Api endpoint returns media data of recording for selected call. Media data are returned in WAV format.",
"parameters": [
{
"name": "callId",
"in": "path",
"description": "Call ID for the requested recording",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Recording media data",
"content": {
"audio/x-wav": {
"schema": {
"$ref": "#/components/schemas/BinaryData"
}
}
}
},
"404": {
"description": "Recording not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
},
"audio/x-wav": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
}
}
}
},
"410": {
"description": "Recording expired",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 410,
"message": "Recording expired."
}
}
},
"audio/x-wav": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
}
}
}
}
}
}
},
"/recordings/delete/{callId}.json": {
"delete": {
"tags": [
"Calls"
],
"summary": "Delete call recording",
"description": "Delete call recording file for good. Call recording will be deleted from all our systems.",
"parameters": [
{
"name": "callId",
"in": "path",
"description": "Call ID for recording to be deleted",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Call not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"410": {
"description": "Recording not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 410,
"message": "Recording not found."
}
}
}
}
}
}
}
},
"/calls/create.json": {
"post": {
"tags": [
"Calls"
],
"summary": "Make a call",
"description": "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.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"agent_id",
"callee_number"
],
"type": "object",
"properties": {
"agent_id": {
"type": "integer",
"description": "Agent ID which will make the call."
},
"callee_number": {
"type": "string",
"description": "The phone number that will receive this Call. Phone numbers must be in E.164 format (e.g., +442012345678)."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"403": {
"description": "Agent is not online",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 403,
"message": "Agent is not online."
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data."
}
}
}
}
},
"409": {
"description": "Agent is already calling",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 409,
"message": "Agent is already calling."
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/statistics/realtime/groups.json": {
"get": {
"tags": [
"Calls"
],
"summary": "Group statistics",
"description": "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.",
"responses": {
"200": {
"description": "Group stats data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Group name."
},
"id": {
"type": "integer",
"description": "Group ID."
},
"operators": {
"type": "integer",
"description": "Number of agents in group."
},
"answered": {
"type": "integer",
"description": "Answered calls to group today."
},
"unanswered": {
"type": "integer",
"description": "Unanswered calls to group today."
},
"abandon_rate": {
"type": "number",
"description": "Abandon rate.",
"format": "float"
},
"avg_waiting_time": {
"type": "integer",
"description": "Average waiting time today."
},
"max_waiting_time": {
"type": "integer",
"description": "Max waiting time today."
},
"avg_call_duration": {
"type": "integer",
"description": "Average call duration today."
},
"real_time": {
"type": "object",
"properties": {
"waiting_queue": {
"type": "integer",
"description": "Waiting calls"
},
"avg_waiting_time": {
"type": "integer",
"description": "Average waiting time"
},
"max_waiting_time": {
"type": "integer",
"description": "Max waiting time."
},
"avg_abandonment_time": {
"type": "integer",
"description": "Average abandonment time."
}
},
"description": "Real time stats"
}
}
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"data": {
"groups": [
{
"name": "Agents",
"id": 123,
"operators": 3,
"answered": 12,
"unanswered": 2,
"abandon_rate": 14.29,
"avg_waiting_time": 48,
"max_waiting_time": 55,
"avg_call_duration": 24,
"real_time": {
"waiting_queue": 2,
"avg_waiting_time": 23,
"max_waiting_time": 53,
"avg_abandonment_time": 12
}
},
{
"name": "Avengers",
"id": 124,
"operators": 3,
"answered": 12,
"unanswered": 2,
"abandon_rate": 14.29,
"avg_waiting_time": 48,
"max_waiting_time": 55,
"avg_call_duration": 24,
"real_time": {
"waiting_queue": 2,
"avg_waiting_time": 23,
"max_waiting_time": 53,
"avg_abandonment_time": 12
}
}
]
}
}
}
}
}
}
}
}
},
"/tags/index.json": {
"get": {
"tags": [
"Contact tags"
],
"summary": "List contact tags",
"description": "Returns the contact tags defined in the account. Pass `id` to fetch a single tag, or page through them with `limit` and `page`.",
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter by tag ID",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Tags data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"itemsCount": {
"type": "integer",
"description": "number of resources in the response",
"format": "int64"
},
"pageCount": {
"type": "integer",
"description": "number of pages found",
"format": "int64"
},
"pageNumber": {
"type": "integer",
"description": "current page in the response",
"format": "int64"
},
"limit": {
"type": "integer",
"description": "number of objects sent per page",
"format": "int64"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"itemsCount": 3,
"pageCount": 1,
"pageNumber": 1,
"limit": 3,
"data": [
{
"Tag": {
"id": "99",
"name": "Tag"
}
}
]
}
}
}
}
}
}
}
},
"/tags/add.json": {
"put": {
"tags": [
"Contact tags"
],
"summary": "Add a contact tag",
"description": "Creates a contact tag with the given `name`. Returns `201` with the new tag's ID.\n\nNote the core API creates with `PUT`, not `POST`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tag name"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tag name"
}
}
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 201,
"data": {
"id": "12345"
}
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"name": [
"Tag has already been used. Please select different one."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/tags/edit/{id}.json": {
"post": {
"tags": [
"Contact tags"
],
"summary": "Edit a contact tag",
"description": "Renames the contact tag identified by `id`. `name` is required. Returns `404` if no tag has that ID.\n\nNote the core API updates with `POST`, not `PUT`.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Tag ID to edit",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tag name"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
},
"406": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorInvalidData"
},
"example": {
"responseData": {
"status": 406,
"message": "Invalid input data.",
"data": {
"name": [
"Tag has already been used. Please select different one."
]
}
}
}
}
}
},
"500": {
"description": "Something went wrong",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
}
}
}
},
"x-codegen-request-body-name": "body"
}
},
"/tags/delete/{id}.json": {
"delete": {
"tags": [
"Contact tags"
],
"summary": "Delete a contact tag",
"description": "Deletes the contact tag identified by `id`. Returns `404` if no tag has that ID.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Tag ID to delete",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "No error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessGeneralData"
},
"example": {
"responseData": {
"status": 200
}
}
}
}
},
"404": {
"description": "Tag not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorData"
},
"example": {
"responseData": {
"status": 404,
"message": "Not found."
}
}
}
}
}
}
}
},
"/ai/calls/{callId}/summary": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Summary",
"description": "Returns the AI-generated summary of a completed call.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
}
],
"responses": {
"200": {
"description": "Information about a given call's summary",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"summary": {
"type": "string",
"description": "Summary of the call"
}
},
"required": [
"callId",
"summary"
]
},
"example": {
"callId": 12345,
"summary": "This is a summary of the call."
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/overall-sentiment": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Overall sentiment",
"description": "Returns the sentiment scored across a completed call as a whole — one of `very negative`, `negative`, `neutral`, `positive` or `very positive`.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
}
],
"responses": {
"200": {
"description": "Information about a given call's overall sentiment",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallOverallSentiment"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/talk-listen-ratio": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Talk-listen ratio",
"description": "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.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
}
],
"responses": {
"200": {
"description": "Information about a given call's talk-listen ratio",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTalkListenRatio"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/topics": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Topics",
"description": "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`.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
},
{
"$ref": "#/components/parameters/paginationLimit"
},
{
"$ref": "#/components/parameters/paginationOffset"
}
],
"responses": {
"200": {
"description": "Information about a given call's topics",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTopics"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/transcription": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Transcription",
"description": "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`.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
},
{
"$ref": "#/components/parameters/paginationLimit"
},
{
"$ref": "#/components/parameters/paginationOffset"
}
],
"responses": {
"200": {
"description": "Information about a given call's transcription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallTranscription"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/smart-notes": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Smart notes",
"description": "Returns the structured notes generated for a completed call — call details, action items, decisions made, open questions and any dates or deadlines mentioned.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
}
],
"responses": {
"200": {
"description": "Information about a given call's smart notes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallSmartNotes"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/ai/calls/{callId}/details-link": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Conversation Intelligence"
],
"summary": "Call details link",
"description": "Returns a link to the call's detail page in CloudTalk analytics.\n\nConversation Intelligence runs on `api.cloudtalk.io/v1` and returns its payload at the top level — these responses are **not** wrapped in the core API's `responseData` envelope.",
"parameters": [
{
"$ref": "#/components/parameters/callId"
}
],
"responses": {
"200": {
"description": "Link to the details of the call in the analytics",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"link": {
"type": "string",
"description": "Link to the details of the call in the analytics"
}
},
"required": [
"link"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/voice-agent/calls": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Initiate VoiceAgent call",
"description": "Creates a new VoiceAgent call with specified parameters and properties. Call properties are optional and can be used to configure the call.",
"operationId": "createVoiceAgentCall",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"call_number",
"voice_agent_id"
],
"properties": {
"call_number": {
"type": "string",
"description": "The phone number to call",
"example": "+421000000000"
},
"voice_agent_id": {
"type": "string",
"description": "ID of the VoiceAgent to use for the call",
"example": "681b0639876543cfbc3d6b55"
},
"call_properties": {
"type": "object",
"description": "Additional properties for configuring the VoiceAgent call",
"properties": {
"output": {
"type": "object",
"description": "Variables that will be included in the VoiceAgent call analysis output",
"properties": {
"variables": {
"type": "object",
"additionalProperties": true,
"description": "Variables that will be included in the call analysis output",
"example": {
"external_contact_id": 12345
}
}
}
},
"system_prompt": {
"type": "object",
"description": "Variables that will be used during the actual call by the VoiceAgent",
"properties": {
"variables": {
"type": "object",
"additionalProperties": true,
"description": "Variables that will be used in the VoiceAgent's system prompt during the call",
"example": {
"name": "John Doe",
"company": "CloudTalk"
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"204": {
"$ref": "#/components/responses/NoContentResponse"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/voice-agent/outbound/kill": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Stop outbound VoiceAgent calls",
"description": "Emergency stop for outbound VoiceAgent dialing.\n\nQueued calls are cancelled and calls already in progress are ended within a few seconds, through the normal call-end path — billing, call records and analytics stay correct. **Inbound calls are unaffected**, as is the outbound traffic of every other company.\n\nThe stop **expires on its own** after `duration_seconds`, so a forgotten stop cannot silence an account indefinitely. Sending the request again overwrites the window; sending `duration_seconds: 0` lifts it early.\n\nBy default the stop covers all of the company's outbound calls. Supply `voice_agent_id` to stop a single VoiceAgent while the others keep dialing.\n\nQueued calls cancelled by a stop are **not dialed later** when the window expires — they are marked declined and removed.\n\nThis endpoint is rate limited to **10 requests per minute per company**, below the API-wide default of 60 — a single request already stops the whole company.",
"operationId": "killVoiceAgentOutbound",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"duration_seconds"
],
"properties": {
"duration_seconds": {
"type": "integer",
"description": "How long to stop outbound dialing, in seconds. `0` cancels a stop that is currently active for the same scope. Maximum 86400 (24 hours).",
"minimum": 0,
"maximum": 86400,
"example": 600
},
"voice_agent_id": {
"type": "string",
"description": "Restrict the stop to a single VoiceAgent. Omit to stop all of the company's outbound calls. Must be a VoiceAgent belonging to your company.",
"example": "681b0639876543cfbc3d6b55"
},
"reason": {
"type": "string",
"description": "Optional free text recorded in the audit log.",
"maxLength": 256,
"example": "runaway campaign"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Outbound dialing stopped, or resumed when `duration_seconds` was 0.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"killed_until_unix": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (seconds) at which the stop expires and dialing resumes on its own. This is a point in time, not a duration. `0` after a cancel.",
"example": 1786966737
},
"drained_count": {
"type": "integer",
"description": "Number of queued outbound calls this request cancelled.",
"example": 3
},
"cancelled": {
"type": "boolean",
"description": "True when the request lifted an existing stop instead of setting one.",
"example": false
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "The VoiceAgent named by `voice_agent_id` was not found. An id that belongs to another company is reported the same way as one that does not exist."
},
"422": {
"description": "The request body failed validation — for example `duration_seconds` outside 0–86400, or a property that is not part of this request."
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"description": "Outbound calling was **not** stopped: the request could not be delivered. Nothing changed, so the call is safe to retry — and must be, since dialing is still running."
}
}
}
},
"/voice-agents": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "List voice agents",
"description": "Returns one page of the company's voice agents. Pages are ordered by creation and walked with limit and cursor.",
"operationId": "public-v1-list-voice-agents",
"parameters": [
{
"description": "Page size, 1-100; out-of-range values are clamped and the effective value echoed in pagination.limit",
"example": 20,
"explode": false,
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"description": "Page size, 1-100; out-of-range values are clamped and the effective value echoed in pagination.limit",
"example": 20,
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page's pagination.next",
"explode": false,
"in": "query",
"name": "cursor",
"schema": {
"description": "Opaque cursor from a previous page's pagination.next",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollectionVoiceAgentListAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Create a voice agent",
"description": "Creates a voice agent from the attributes object.",
"operationId": "public-v1-create-voice-agent",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VoiceAgentAttributes"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleVoiceAgentAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/voice-agents/{voiceAgentId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Get a voice agent",
"description": "Returns one voice agent of the company.",
"operationId": "public-v1-get-voice-agent",
"parameters": [
{
"name": "voiceAgentId",
"in": "path",
"required": true,
"description": "Voice agent identifier",
"schema": {
"description": "Voice agent identifier",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleVoiceAgentAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"put": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Replace a voice agent",
"description": "Replaces the voice agent with the attributes object. An omitted optional attribute is reset to its default, never preserved, except provider, llm and minorVersion, which keep their stored values.",
"operationId": "public-v1-replace-voice-agent",
"parameters": [
{
"name": "voiceAgentId",
"in": "path",
"required": true,
"description": "Voice agent identifier",
"schema": {
"description": "Voice agent identifier",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VoiceAgentAttributes"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleVoiceAgentAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Delete a voice agent",
"description": "Deletes the voice agent. Attached knowledge bases and tools are unlinked, not deleted.",
"operationId": "public-v1-delete-voice-agent",
"parameters": [
{
"name": "voiceAgentId",
"in": "path",
"required": true,
"description": "Voice agent identifier",
"schema": {
"description": "Voice agent identifier",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/voice-agents/{voiceAgentId}/knowledge-bases/{knowledgeBaseId}": {
"put": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Attach a knowledge base to a voice agent",
"description": "Links the knowledge base to the agent. Repeating the call changes nothing.",
"operationId": "public-v1-attach-voice-agent-knowledge-base",
"parameters": [
{
"name": "voiceAgentId",
"in": "path",
"required": true,
"description": "Voice agent identifier",
"schema": {
"description": "Voice agent identifier",
"type": "string"
}
},
{
"name": "knowledgeBaseId",
"in": "path",
"required": true,
"description": "Knowledge base identifier",
"schema": {
"description": "Knowledge base identifier",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Detach a knowledge base from a voice agent",
"description": "Unlinks the knowledge base from the agent; the knowledge base itself is kept.",
"operationId": "public-v1-detach-voice-agent-knowledge-base",
"parameters": [
{
"name": "voiceAgentId",
"in": "path",
"required": true,
"description": "Voice agent identifier",
"schema": {
"description": "Voice agent identifier",
"type": "string"
}
},
{
"name": "knowledgeBaseId",
"in": "path",
"required": true,
"description": "Knowledge base identifier",
"schema": {
"description": "Knowledge base identifier",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/knowledge-bases": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "List knowledge bases",
"description": "Returns one page of the company's knowledge bases. Pages are ordered by identifier and walked with limit and cursor.",
"operationId": "public-v1-list-knowledge-bases",
"parameters": [
{
"description": "Page size, 1-100; out-of-range values are clamped and the effective value echoed in pagination.limit",
"example": 20,
"explode": false,
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"description": "Page size, 1-100; out-of-range values are clamped and the effective value echoed in pagination.limit",
"example": 20,
"type": "integer"
}
},
{
"description": "Opaque cursor from a previous page's pagination.next",
"explode": false,
"in": "query",
"name": "cursor",
"schema": {
"description": "Opaque cursor from a previous page's pagination.next",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollectionKnowledgeBaseAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Create a knowledge base",
"description": "Creates a knowledge base from an address or from inline text. A URL source starts SYNCHRONIZING and turns ACTIVE once it has been read. A company may hold at most 100 knowledge bases; at the cap the request answers 409 KNOWLEDGE_BASE_LIMIT_REACHED.",
"operationId": "public-v1-create-knowledge-base",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBaseCreateAttributes"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleKnowledgeBaseAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/knowledge-bases/files": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Upload a knowledge base file",
"description": "Creates a knowledge base from one uploaded file. The name is derived from the filename. A company may hold at most 100 knowledge bases; at the cap the request answers 409 KNOWLEDGE_BASE_LIMIT_REACHED.",
"operationId": "public-v1-upload-knowledge-base-file",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"additionalProperties": false,
"properties": {
"file": {
"description": "The file to ingest as a knowledge base",
"format": "binary",
"type": "string"
}
},
"required": [
"file"
],
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleKnowledgeBaseAttributes"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/knowledge-bases/{knowledgeBaseId}": {
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"VoiceAgent"
],
"summary": "Delete a knowledge base",
"description": "Deletes the knowledge base. A knowledge base attached to a voice agent must be detached first.",
"operationId": "public-v1-delete-knowledge-base",
"parameters": [
{
"name": "knowledgeBaseId",
"in": "path",
"required": true,
"description": "Knowledge base identifier",
"schema": {
"description": "Knowledge base identifier",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/dialer/campaigns": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Create a dialer campaign",
"description": "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 groups and agents are attached separately with the associations call.",
"operationId": "publicCreateCampaign",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCreateCampaignRequest"
},
"example": {
"name": "Q3 renewals",
"mode": "sequential",
"calling_policy": {
"answer_wait": 25,
"after_call": 10,
"recording": true
},
"queue_policy": {
"lock_size": 5,
"refill_amount": 3
},
"retry_policy": {
"max_attempts": 3,
"interval_hours": 24
},
"waterfall_order": [
"favorite",
"rescheduled",
"retry",
"fresh"
],
"agent_permissions": {
"skip": true
},
"call_script_id": 310
}
}
}
},
"responses": {
"201": {
"description": "The created campaign.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaign"
},
"example": {
"id": "42",
"name": "Q3 renewals",
"mode": "sequential",
"status": "initializing",
"calling_policy": {
"answer_wait": 25,
"after_call": 10,
"recording": true
},
"queue_policy": {
"lock_size": 5,
"refill_amount": 3
},
"retry_policy": {
"max_attempts": 3,
"interval_hours": 24
},
"schedule_policy": {
"start_date": "2026-08-10",
"start_time": "09:00"
},
"ttl_policy": {
"mode": "campaign",
"hours": 72
},
"waterfall_order": [
"favorite",
"rescheduled",
"retry",
"fresh"
],
"agent_permissions": {
"skip": true,
"remove": false,
"reorder": false
},
"call_script_id": "310",
"survey_id": null,
"created_at": "2026-08-01T09:15:00.000Z",
"updated_at": "2026-08-01T09:15:00.000Z",
"archived_at": null,
"deleted_at": null
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "List dialer campaigns",
"description": "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. Deleted campaigns are hidden unless `include_deleted=true`; pass `status=deleted` to list only them. When `status` is set, `include_deleted` has no effect.",
"operationId": "publicListCampaigns",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor taken from `meta.nextCursor` of a previous page. Pass it back unchanged. Omitting `cursor`, or sending it empty, starts from the first page — neither is an error. A non-empty cursor this endpoint cannot decode is rejected with `400` and `code: \"PAGINATION.INVALID_CURSOR\"` rather than silently restarting the list. Handle it as an error, not as a terminating `null` cursor: a loop that only stops on `null` would re-send the same rejected cursor. Drop the stored cursor and restart from a checkpoint you control.",
"schema": {
"type": "string"
},
"example": "eyJpZCI6IjQyIn0"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of campaigns per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Return only campaigns in this lifecycle status.",
"schema": {
"type": "string",
"enum": [
"initializing",
"active",
"inactive",
"archived",
"deleted"
]
}
},
{
"name": "include_deleted",
"in": "query",
"required": false,
"description": "Set to `true` to include campaigns whose status is `deleted`, which are hidden by default. Ignored when `status` is set. Only the literal strings `true` and `false` are accepted — anything else is a 400.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "mode",
"in": "query",
"required": false,
"description": "Return only campaigns using this dialing mode.",
"schema": {
"type": "string",
"enum": [
"sequential",
"parallel"
]
}
}
],
"responses": {
"200": {
"description": "One page of campaigns.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaignList"
},
"example": {
"data": [
{
"id": "42",
"name": "Q3 renewals",
"mode": "sequential",
"status": "active",
"calling_policy": {
"answer_wait": 25,
"after_call": 10,
"recording": true
},
"queue_policy": {
"lock_size": 5,
"refill_amount": 3
},
"retry_policy": {
"max_attempts": 3,
"interval_hours": 24
},
"schedule_policy": {
"start_date": "2026-08-10",
"start_time": "09:00"
},
"ttl_policy": {
"mode": "campaign",
"hours": 72
},
"waterfall_order": [
"favorite",
"rescheduled",
"retry",
"fresh"
],
"agent_permissions": {
"skip": true,
"remove": false,
"reorder": false
},
"call_script_id": "310",
"survey_id": null,
"created_at": "2026-08-01T09:15:00.000Z",
"updated_at": "2026-08-04T11:42:07.000Z",
"archived_at": null,
"deleted_at": null
}
],
"meta": {
"nextCursor": "eyJpZCI6IjQyIn0"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a dialer campaign",
"description": "Returns a single campaign with its full configuration. A campaign belonging to another company reads as 404.",
"operationId": "publicGetCampaign",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"responses": {
"200": {
"description": "The campaign.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaign"
},
"example": {
"id": "42",
"name": "Q3 renewals",
"mode": "sequential",
"status": "active",
"calling_policy": {
"answer_wait": 25,
"after_call": 10,
"recording": true
},
"queue_policy": {
"lock_size": 5,
"refill_amount": 3
},
"retry_policy": {
"max_attempts": 3,
"interval_hours": 24
},
"schedule_policy": {
"start_date": "2026-08-10",
"start_time": "09:00"
},
"ttl_policy": {
"mode": "campaign",
"hours": 72
},
"waterfall_order": [
"favorite",
"rescheduled",
"retry",
"fresh"
],
"agent_permissions": {
"skip": true,
"remove": false,
"reorder": false
},
"call_script_id": "310",
"survey_id": null,
"created_at": "2026-08-01T09:15:00.000Z",
"updated_at": "2026-08-04T11:42:07.000Z",
"archived_at": null,
"deleted_at": null
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"patch": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Update a dialer campaign",
"description": "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`; `active` → `archived`; `inactive` → `archived`; `archived` → `inactive`. An illegal transition — including `deleted`, which only the delete call may set — returns 422. Status changes never conflict with running work: in-flight dialing sessions drain naturally once the status is no longer `active`.",
"operationId": "publicPatchCampaign",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerPatchCampaignRequest"
},
"example": {
"status": "active",
"retry_policy": {
"max_attempts": 5,
"interval_hours": 12
}
}
}
}
},
"responses": {
"200": {
"description": "The updated campaign.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaign"
},
"example": {
"id": "42",
"name": "Q3 renewals",
"mode": "sequential",
"status": "active",
"calling_policy": {
"answer_wait": 25,
"after_call": 10,
"recording": true
},
"queue_policy": {
"lock_size": 5,
"refill_amount": 3
},
"retry_policy": {
"max_attempts": 3,
"interval_hours": 24
},
"schedule_policy": {
"start_date": "2026-08-10",
"start_time": "09:00"
},
"ttl_policy": {
"mode": "campaign",
"hours": 72
},
"waterfall_order": [
"favorite",
"rescheduled",
"retry",
"fresh"
],
"agent_permissions": {
"skip": true,
"remove": false,
"reorder": false
},
"call_script_id": "310",
"survey_id": null,
"created_at": "2026-08-01T09:15:00.000Z",
"updated_at": "2026-08-04T11:42:07.000Z",
"archived_at": null,
"deleted_at": null
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Delete a dialer campaign",
"description": "Soft-deletes the campaign: its status becomes `deleted` (terminal) and its deletion is timestamped. It stops being dialable and drops out of the default campaign list — `GET /dialer/campaigns` returns it only with `include_deleted=true` or `status=deleted`. 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. Nothing is erased, so historical statistics and exports stay available.",
"operationId": "publicDeleteCampaign",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"responses": {
"204": {
"$ref": "#/components/responses/NoContentResponse"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/associations": {
"put": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Replace a campaign's associations",
"description": "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. Entries can be given as objects or as bare ids — `[10, 11]` is shorthand for `[{ \"ref_id\": 10 }, { \"ref_id\": 11 }]`.\n\n`priority` and `label` rank a target tag (highest priority served first) and are only valid on `target_tag` entries — sending them on a queue group or agent returns 422. Naming the same `(kind, ref_id)` twice in one body returns 409 and nothing is written. A target tag owned by a CRM connection can be re-ranked here, but adding or removing it stays with the connection that owns it; leaving it out of the body does not remove it.\n\nEvery `ref_id` is a weak reference: this call does not check that a contact tag, queue group or agent with that id exists. A nonexistent target tag is stored and simply contributes no contacts, so validate the ids on your side before sending them.",
"operationId": "publicReplaceCampaignAssociations",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerReplaceAssociationsRequest"
},
"example": {
"target_tag": [
{
"ref_id": 10,
"priority": 10,
"label": "Hot"
},
11
],
"queue_group": [
20
],
"agent": [
800001
]
}
}
}
},
"responses": {
"200": {
"description": "The campaign's associations after the replace.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerAssociations"
},
"example": {
"target_tag": [
{
"ref_id": 10,
"priority": 10,
"label": "Hot",
"origin": "manual"
},
{
"ref_id": 11,
"priority": 0,
"label": null,
"origin": "manual"
},
{
"ref_id": 12,
"priority": 5,
"label": "HubSpot list",
"origin": "crm_connection"
}
],
"queue_group": [
20
],
"agent": [
800001
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a campaign's associations",
"description": "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.",
"operationId": "publicGetCampaignAssociations",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"responses": {
"200": {
"description": "The campaign's associations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerAssociations"
},
"example": {
"target_tag": [
{
"ref_id": 10,
"priority": 10,
"label": "Hot",
"origin": "manual"
},
{
"ref_id": 11,
"priority": 0,
"label": null,
"origin": "manual"
},
{
"ref_id": 12,
"priority": 5,
"label": "HubSpot list",
"origin": "crm_connection"
}
],
"queue_group": [
20
],
"agent": [
800001
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/disposition-buttons": {
"put": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Replace a campaign's disposition buttons",
"description": "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, …). An empty `buttons` array clears the set.\n\nThe button's display name and colour are always taken from the referenced tag, so a `color` key in the body is rejected with 400 rather than silently ignored. An `outcome_kind` outside the listed values is a schema violation and returns 400. Referencing the same tag twice returns 409, and a `tag_id` that is not an active call tag on your account — unknown, deleted or archived — returns 422.",
"operationId": "publicReplaceCampaignDispositionButtons",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerReplaceDispositionButtonsRequest"
},
"example": {
"buttons": [
{
"tag_id": 101,
"outcome_kind": "rescheduled",
"display_order": 0
},
{
"tag_id": 100,
"outcome_kind": "successful_positive",
"display_order": 1
}
]
}
}
}
},
"responses": {
"200": {
"description": "The campaign's disposition buttons after the replace, ordered by `display_order`.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerDispositionButton"
}
},
"example": [
{
"id": "15",
"tag_id": "101",
"outcome_kind": "rescheduled",
"color": "#FFAA00",
"display_order": 0,
"name": "Call back later",
"outcome": "rescheduled"
},
{
"id": "16",
"tag_id": "100",
"outcome_kind": "successful_positive",
"color": "#00AA55",
"display_order": 1,
"name": "Interested",
"outcome": "successful_positive"
}
]
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a campaign's disposition buttons",
"description": "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.\n\nA button whose call tag has since been deleted or archived on your account is left out of the response — removing a disposition removes it from every campaign. If the call tags cannot be read at that moment, every button is returned instead, with `name`, `color` and `outcome` set to null.",
"operationId": "publicGetCampaignDispositionButtons",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"responses": {
"200": {
"description": "The campaign's disposition buttons, ordered by `display_order`.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerDispositionButton"
}
},
"example": [
{
"id": "15",
"tag_id": "101",
"outcome_kind": "rescheduled",
"color": "#FFAA00",
"display_order": 0,
"name": "Call back later",
"outcome": "rescheduled"
},
{
"id": "16",
"tag_id": "100",
"outcome_kind": "successful_positive",
"color": "#00AA55",
"display_order": 1,
"name": "Interested",
"outcome": "successful_positive"
}
]
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/disposition-tags": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "List disposition tags",
"description": "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.\n\nArchived dispositions are not listed, because they can no longer be used on a call. Tags are created and edited in the CloudTalk dashboard, not through this API.",
"operationId": "publicListDispositionTags",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"responses": {
"200": {
"description": "The company's disposition-tag catalogue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerDispositionTagList"
},
"example": {
"data": [
{
"id": "100",
"name": "Interested",
"color": "#00AA55",
"outcome": "successful_positive"
},
{
"id": "101",
"name": "Call back later",
"color": "#FFAA00",
"outcome": "rescheduled"
}
],
"meta": {
"nextCursor": null
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/dialer/campaigns/{campaignId}/statistics": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a campaign's statistics",
"description": "Returns the campaign's aggregated performance on one of two bases, told apart by `range` in the response:\n\n- **All-time** (no `dateFrom`/`dateTo`): lifetime counters served from a projection refreshed in the background — `updated_at` tells you how fresh they are, and `range` is null. `call_durations` is included only when `includeDurations=true` (it is the one read whose cost grows with the campaign).\n- **Ranged** (`dateFrom` and `dateTo` both set): counters aggregated at request time over the half-open window `[dateFrom, dateTo)`. `range` echoes the resolved window, `updated_at` is null, and durations are always included (`includeDurations` is ignored).\n\nBoth bounds are RFC 3339 date-times. The service also reads the ISO 8601 date-only form `YYYY-MM-DD`, which lies outside that shape and is therefore only reachable from a client that does not validate against this schema: a date-only `dateTo` names a calendar day and is served inclusive of it — the exclusive end moves to the following UTC midnight, so equal date-only bounds are a valid one-day window. There is no limit on the window's length; the only bound is the 13-month event retention horizon on `dateFrom`. Supplying only one bound, an empty window, or a `dateFrom` past the horizon is a 422.\n\nThe membership-state blocks (`contact_states*`, `pending_by_category`, `open_assignments`) always describe the campaign's current state — a window does not narrow them. Unknown query parameters are rejected with 400 rather than ignored. A campaign that has never been dialed returns zeroed counters, not 404.",
"operationId": "publicGetCampaignStatistics",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
},
{
"name": "dateFrom",
"in": "query",
"required": false,
"description": "Inclusive lower bound of the statistics window, as an RFC 3339 date-time. Requires `dateTo`. Must not be older than the 13-month event retention horizon.",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-07-01T00:00:00.000Z"
},
{
"name": "dateTo",
"in": "query",
"required": false,
"description": "Exclusive upper bound of the statistics window, as an RFC 3339 date-time. Requires `dateFrom`. A date-only value — which the `date-time` format does not admit, so only a client that does not validate against this schema sends one — is served inclusive of that day.",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-08-01T00:00:00.000Z"
},
{
"name": "includeDurations",
"in": "query",
"required": false,
"description": "Set to `true` to include the `call_durations` block on an all-time read. Ignored on a ranged read, which always carries durations. Only the literal strings `true` and `false` are accepted — anything else is a 400.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "The campaign's statistics.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaignStatistics"
},
"example": {
"campaign_id": "42",
"contact_states": {
"pending": 120,
"scheduled": 4,
"completed": 38,
"dnc": 2,
"exhausted": 1,
"excluded": 0
},
"contact_states_dialable": {
"pending": 118,
"scheduled": 4,
"completed": 38,
"dnc": 2,
"exhausted": 1,
"excluded": 0
},
"contact_states_repeated": {
"pending": 31,
"scheduled": 4,
"completed": 38,
"dnc": 2,
"exhausted": 1,
"excluded": 0
},
"pending_by_category": {
"favorite": 6,
"rescheduled": 12,
"retry": 22,
"fresh": 80
},
"total_contacts_at_range_end": 165,
"open_assignments": 3,
"assigned_by_state": {
"pending": 2,
"scheduled": 1
},
"assigned_pending_by_category": {
"favorite": 0,
"rescheduled": 0,
"retry": 1,
"fresh": 1
},
"total_dialed": 240,
"total_answered": 150,
"answer_rate": 0.625,
"num_rescheduled": 12,
"num_dropped": 3,
"num_dispositioned": 96,
"num_conversions": 30,
"conversion_rate": 0.3125,
"num_reached_human": 130,
"num_reached_voicemail": 15,
"num_reached_other_machine": 5,
"attempt_no_split": {
"first_attempt": 152,
"repeat_attempt": 88
},
"distinct_called_contacts": null,
"distinct_answered_contacts": 112,
"call_durations": {
"calls": 238,
"answered_calls": 150,
"talk_seconds": 21540,
"total_seconds": 26310,
"ring_seconds": 4770,
"avg_talk_seconds": 144,
"avg_ring_seconds": 20,
"max_talk_seconds": 1260
},
"disposition_breakdown": [
{
"tag_id": "100",
"count": 17,
"name": "Interested",
"color": "#00AA55",
"outcome": "successful_positive"
},
{
"tag_id": "101",
"count": 9,
"name": "Call back later",
"color": "#FFAA00",
"outcome": "rescheduled"
}
],
"updated_at": "2026-08-04T11:40:00.000Z",
"range": null
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/contacts": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "List a campaign's contacts",
"description": "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`.\n\n`queue_tag` on each row is a derived queue position, not the raw membership state: an open agent hold reads `assigned`, a scheduled callback reads `scheduled`, terminal states read as themselves, and a pending contact reads its waterfall category (`fresh`, `retry`, `rescheduled`, `favorite`).\n\nThere is no contacts write route on this API — campaign membership is tag-defined, so contacts are added by tagging them in Contacts.",
"operationId": "publicListCampaignContacts",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor taken from `meta.nextCursor` of a previous page. Pass it back unchanged. Omitting `cursor`, or sending it empty, starts from the first page — neither is an error. A non-empty cursor this endpoint cannot decode is rejected with `400` and `code: \"PAGINATION.INVALID_CURSOR\"` rather than silently restarting the list. Handle it as an error, not as a terminating `null` cursor: a loop that only stops on `null` would re-send the same rejected cursor. Drop the stored cursor and restart from a checkpoint you control.",
"schema": {
"type": "string"
},
"example": "eyJuZXh0RWxpZ2libGVBdCI6IjIwMjYtMDgtMTIgMTI6MjI6MzEuOTIyNTY3KzAwIiwiaWQiOiI1MTAwIn0"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of contacts per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "queueTag",
"in": "query",
"required": false,
"description": "Narrow to one or more queue positions. Repeat the parameter (`?queueTag=fresh&queueTag=retry`) or comma-separate (`?queueTag=fresh,retry`). An unknown value is a 400.",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"assigned",
"scheduled",
"completed",
"dnc",
"exhausted",
"excluded",
"fresh",
"retry",
"rescheduled",
"favorite"
]
}
},
"explode": true,
"example": [
"fresh",
"retry"
]
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Case-insensitive substring match over the contact's display name and phone numbers. At most 200 characters.",
"schema": {
"type": "string",
"maxLength": 200
},
"example": "kowalski"
}
],
"responses": {
"200": {
"description": "One page of campaign contacts with a filtered-set total.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaignContactList"
},
"example": {
"data": [
{
"campaign_contact_id": "5100",
"contact_id": "88213",
"display_name": "Jane Kowalski",
"phone_number": "+421900123456",
"queue_tag": "fresh",
"attempt_count": 0,
"next_eligible_at": "2026-08-04T08:00:00.000Z",
"owner_user_id": null,
"callback_notes": null
}
],
"meta": {
"nextCursor": null,
"total": 1
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/contacts/next": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Peek at the next contacts to be dialed",
"description": "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 a contact.\n\nA campaign that exists but is not active, or whose queue is empty, answers 200 with an empty array — never 404. Contacts already held by an agent and contacts whose eligibility lies in the future are excluded. Callbacks pinned to a specific agent are not visible on this surface until their pin lapses.\n\nUnknown query parameters are rejected with 400 rather than ignored.",
"operationId": "publicPeekContacts",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
},
{
"name": "count",
"in": "query",
"required": false,
"description": "How many contacts to peek at. Defaults to the campaign's `queue_policy.lock_size`.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"example": 5
}
],
"responses": {
"200": {
"description": "The next contacts in dialing order — a bare array, empty when nothing is dialable.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerPeekContact"
}
},
"example": [
{
"campaign_contact_id": "5100",
"contact_id": "88213",
"category": "fresh",
"phone_numbers": [
"+421900123456",
"+421255512345"
],
"display_name": "Jane Kowalski",
"timezone": "Europe/Bratislava",
"callback_notes": null
}
]
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/contacts/{campaignContactId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get one campaign contact",
"description": "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 carries none answers `[]`. A membership belonging to another company or campaign reads as 404.",
"operationId": "publicGetCampaignContact",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
},
{
"$ref": "#/components/parameters/dialerCampaignContactId"
}
],
"responses": {
"200": {
"description": "The campaign contact with tag enrichment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCampaignContactDetail"
},
"example": {
"campaign_contact_id": "5100",
"contact_id": "88213",
"display_name": "Jane Kowalski",
"phone_number": "+421900123456",
"queue_tag": "fresh",
"attempt_count": 0,
"next_eligible_at": "2026-08-04T08:00:00.000Z",
"owner_user_id": null,
"callback_notes": null,
"tags": [
"DACH",
"VIP"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/campaigns/{campaignId}/exports": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Request a campaign data export",
"description": "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.\n\nWhen the job completes, fetch the file through the export-download call, which mints a pre-signed link; the same link is also emailed to the requester. Optional `filters` narrow the export by contact, agent or date range — omit them to export everything for the campaign.\n\nThe call is not idempotent: every request enqueues a new job, so a retry after a timeout creates a second export and a second link. There is no deduplication window or idempotency key.\n\n`filters.contactId` and `filters.userId` must be positive ids, and `dateFrom` / `dateTo` must be strict ISO 8601 — anything else is a 400 and no job is enqueued. Supplying only one bound is valid: a missing `dateTo` resolves to the time the job runs, a missing `dateFrom` to the campaign's creation. Each bound you do supply must itself be parseable as a date-time — strict ISO 8601 admits forms such as the week date `2026-W33` that cannot be read, and such a bound returns 422 (`dateFrom must be a parseable ISO 8601 date-time`, or the `dateTo` equivalent) whether or not the other bound is present. Supplying both with a `dateTo` that is not after `dateFrom` returns 422 (`dateTo must be after dateFrom`), and again nothing is enqueued.",
"operationId": "publicCreateCampaignExport",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerCampaignId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCreateExportRequest"
},
"example": {
"type": "call_history",
"format": "csv",
"filters": {
"dateFrom": "2026-07-01T00:00:00.000Z",
"dateTo": "2026-08-01T00:00:00.000Z"
}
}
}
}
},
"responses": {
"202": {
"description": "The export job was accepted and queued.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerExportJob"
},
"example": {
"jobId": "0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f",
"status": "queued"
}
}
}
},
"400": {
"description": "The body is invalid — an id below `1`, a `dateFrom` / `dateTo` that is not strict ISO 8601, a missing `type` or `format`. No job is enqueued.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 400,
"message": "Validation error",
"error": "Bad Request",
"correlationId": "YevPQs",
"subErrors": [
"filters.contactId must not be less than 1"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "The date window cannot be served: `dateTo` is not after `dateFrom` (`dateTo must be after dateFrom`). No job is enqueued. The service also answers 422 for a bound that is valid strict ISO 8601 but lies outside the RFC 3339 `date-time` shape this schema declares and cannot be read as an instant — a week date such as `2026-W33` (`dateFrom must be a parseable ISO 8601 date-time`, or the `dateTo` equivalent). A client that validates against this schema never sends one.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 422,
"message": "dateTo must be after dateFrom",
"error": "Unprocessable Entity",
"correlationId": "YevPQs"
}
}
}
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/exports/{jobId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get an export job's status",
"description": "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.\n\nA `completed` job does not expose the file here — fetch it through the export-download call (a pre-signed link is also emailed to the requester).\n\nA `jobId` that is not a UUID is rejected with 400 before the job is looked up.",
"operationId": "publicGetExportJob",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerExportJobId"
}
],
"responses": {
"200": {
"description": "The export job's current state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerExportJobStatus"
},
"example": {
"jobId": "0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f",
"status": "running",
"progress": {
"currentPartition": 3,
"totalPartitions": 8
},
"createdAt": "2026-08-04T08:00:00.000Z",
"completedAt": null
}
}
}
},
"400": {
"description": "The `jobId` in the path is not a UUID. Rejected before any lookup.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 400,
"message": "Validation failed (uuid is expected)",
"error": "Bad Request",
"correlationId": "YevPQs"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/exports/{jobId}/download": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a download link for a completed export",
"description": "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 misbehave.\n\nEvery call mints a new link, so the call is idempotent and repeatable — when a link expires, call again for a fresh one. Links live at least 60 minutes. The job itself never expires; only individual links do. The same link is also emailed to the requester when the job completes.\n\nA job that is still `queued` or `running` answers 409 (keep polling the export-status call); a `failed` job answers 409 with a message saying no file exists (terminal — stop polling). A job belonging to another company reads as 404.\n\nA `jobId` that is not a UUID is rejected with 400 before the job is looked up.",
"operationId": "publicDownloadExportJob",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerExportJobId"
}
],
"responses": {
"200": {
"description": "A fresh download link and its expiry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerExportDownload"
},
"example": {
"url": "https://ct-dialer-exports.s3.eu-west-1.amazonaws.com/exports/700001/0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f/call_history-campaign-42.csv?X-Amz-Signature=…",
"expiresAt": "2026-08-04T09:05:00.000Z"
}
}
}
},
"400": {
"description": "The `jobId` in the path is not a UUID. Rejected before any lookup.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 400,
"message": "Validation failed (uuid is expected)",
"error": "Bad Request",
"correlationId": "YevPQs"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/scripts": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Create a call script",
"description": "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`.",
"operationId": "publicCreateScript",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCreateScriptRequest"
},
"example": {
"name": "Summer promo pitch",
"body": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…"
}
}
}
},
"responses": {
"201": {
"description": "The created script.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerScript"
},
"example": {
"id": "17",
"name": "Summer promo pitch",
"body": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…",
"is_archived": false,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "List call scripts",
"description": "Returns the company's call scripts newest first, cursor-paginated. Archived scripts are hidden unless `include_archived=true`.",
"operationId": "publicListScripts",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor taken from `meta.nextCursor` of a previous page. Pass it back unchanged. Omitting `cursor`, or sending it empty, starts from the first page — neither is an error. A non-empty cursor this endpoint cannot decode is rejected with `400` and `code: \"PAGINATION.INVALID_CURSOR\"` rather than silently restarting the list. Handle it as an error, not as a terminating `null` cursor: a loop that only stops on `null` would re-send the same rejected cursor. Drop the stored cursor and restart from a checkpoint you control.",
"schema": {
"type": "string"
},
"example": "eyJpZCI6IjQyIn0"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of items per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "include_archived",
"in": "query",
"required": false,
"description": "Set to `true` to include archived items. Only the literal strings `true` and `false` are accepted — anything else is a 400.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "One page of scripts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerScriptList"
},
"example": {
"data": [
{
"id": "17",
"name": "Summer promo pitch",
"body": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…",
"is_archived": false,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
],
"meta": {
"nextCursor": null
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/scripts/{scriptId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a call script",
"description": "Returns one script by id, archived or not. A script belonging to another company reads as 404.",
"operationId": "publicGetScript",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerScriptId"
}
],
"responses": {
"200": {
"description": "The script.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerScript"
},
"example": {
"id": "17",
"name": "Summer promo pitch",
"body": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…",
"is_archived": false,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"patch": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Update a call script",
"description": "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.",
"operationId": "publicPatchScript",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerScriptId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerPatchScriptRequest"
},
"example": {
"name": "Summer promo pitch v2"
}
}
}
},
"responses": {
"200": {
"description": "The updated script.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerScript"
},
"example": {
"id": "17",
"name": "Summer promo pitch",
"body": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…",
"is_archived": false,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Archive a call script",
"description": "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.",
"operationId": "publicArchiveScript",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerScriptId"
}
],
"responses": {
"204": {
"$ref": "#/components/responses/NoContentResponse"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/surveys": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Create a survey",
"description": "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`.",
"operationId": "publicCreateSurvey",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerCreateSurveyRequest"
},
"example": {
"name": "Post-call qualification",
"questions": [
{
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"label": "Yes",
"display_order": 0
},
{
"label": "No",
"display_order": 1
}
]
}
]
}
}
}
},
"responses": {
"201": {
"description": "The created survey with its full question set.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerSurveyDefinition"
},
"example": {
"id": "8",
"name": "Post-call qualification",
"is_archived": false,
"questions": [
{
"id": "310",
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"id": "901",
"label": "Yes",
"display_order": 0
},
{
"id": "902",
"label": "No",
"display_order": 1
}
]
}
],
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "List surveys",
"description": "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`.",
"operationId": "publicListSurveys",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor taken from `meta.nextCursor` of a previous page. Pass it back unchanged. Omitting `cursor`, or sending it empty, starts from the first page — neither is an error. A non-empty cursor this endpoint cannot decode is rejected with `400` and `code: \"PAGINATION.INVALID_CURSOR\"` rather than silently restarting the list. Handle it as an error, not as a terminating `null` cursor: a loop that only stops on `null` would re-send the same rejected cursor. Drop the stored cursor and restart from a checkpoint you control.",
"schema": {
"type": "string"
},
"example": "eyJpZCI6IjQyIn0"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of items per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "include_archived",
"in": "query",
"required": false,
"description": "Set to `true` to include archived items. Only the literal strings `true` and `false` are accepted — anything else is a 400.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "One page of survey summaries.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerSurveyList"
},
"example": {
"data": [
{
"id": "8",
"name": "Post-call qualification",
"is_archived": false,
"question_count": 1,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
],
"meta": {
"nextCursor": null
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/surveys/{surveyId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Get a survey",
"description": "Returns one survey by id with its full ordered question set, archived or not. A survey belonging to another company reads as 404.",
"operationId": "publicGetSurvey",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerSurveyId"
}
],
"responses": {
"200": {
"description": "The survey definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerSurveyDefinition"
},
"example": {
"id": "8",
"name": "Post-call qualification",
"is_archived": false,
"questions": [
{
"id": "310",
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"id": "901",
"label": "Yes",
"display_order": 0
},
{
"id": "902",
"label": "No",
"display_order": 1
}
]
}
],
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
},
"patch": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Rename or archive a survey",
"description": "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 collected — a `DELETE` on this path is an unmatched route and answers 404 `Route not found`. Restore with `is_archived: false`.",
"operationId": "publicPatchSurvey",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerSurveyId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerPatchSurveyRequest"
},
"example": {
"is_archived": true
}
}
}
},
"responses": {
"200": {
"description": "The updated survey definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerSurveyDefinition"
},
"example": {
"id": "8",
"name": "Post-call qualification",
"is_archived": false,
"questions": [
{
"id": "310",
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"id": "901",
"label": "Yes",
"display_order": 0
},
{
"id": "902",
"label": "No",
"display_order": 1
}
]
}
],
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/dialer/surveys/{surveyId}/questions": {
"put": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Dialer"
],
"summary": "Replace a survey's questions",
"description": "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 survey. Question and option ids are server-generated — never send them; every replace mints new ids.\n\nAnswers already collected are stored as immutable snapshots and are not rewritten by a replace.",
"operationId": "publicReplaceSurveyQuestions",
"x-mint": {
"content": "The Dialer is a newly released product surface: depending on your account's rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard."
},
"parameters": [
{
"$ref": "#/components/parameters/dialerSurveyId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerReplaceSurveyQuestionsRequest"
},
"example": {
"questions": [
{
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"label": "Yes",
"display_order": 0
},
{
"label": "No",
"display_order": 1
}
]
},
{
"label": "Notes",
"type": "textarea",
"is_required": false,
"display_order": 1
}
]
}
}
}
},
"responses": {
"200": {
"description": "The survey definition with the replacement question set.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerSurveyDefinition"
},
"example": {
"id": "8",
"name": "Post-call qualification",
"is_archived": false,
"questions": [
{
"id": "310",
"label": "Was the customer interested?",
"type": "radio",
"is_required": true,
"display_order": 0,
"options": [
{
"id": "901",
"label": "Yes",
"display_order": 0
},
{
"id": "902",
"label": "No",
"display_order": 1
}
]
}
],
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-08-04T11:40:00.000Z"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/webhooks/event-types": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "List webhook event types",
"description": "Returns every event type an endpoint can subscribe to. Deprecated and internal types are not listed. Readable without a webhooks-enabled plan, so you can see what you would receive before enabling it.",
"operationId": "public-v1-list-webhook-event-types",
"parameters": [
{
"name": "include",
"in": "query",
"required": false,
"description": "`schema` adds the JSON Schema of the full webhook body for every version of each type.",
"schema": {
"type": "string",
"enum": [
"schema"
]
}
}
],
"responses": {
"200": {
"description": "The event types.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEventTypeList"
},
"example": {
"data": [
{
"name": "call.ended",
"description": "A call ended.",
"groupName": "call"
}
],
"requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}
}
}
},
"400": {
"description": "`include` has a value other than `schema` (code VALIDATION.INVALID_PARAMETER).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "List webhook endpoints",
"description": "Returns one page of the company's webhook endpoints, newest first, including endpoints created in the Dashboard.",
"operationId": "public-v1-list-webhook-endpoints",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size, 1-100. Out-of-range values are clamped and the effective value is echoed in `pagination.limit`.",
"schema": {
"type": "integer",
"default": 20,
"example": 20
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from a previous page's `pagination.next`. Pass it back unchanged. A cursor this API cannot use is rejected with `400 PAGINATION.INVALID_CURSOR`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "One page of endpoints.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpointList"
},
"example": {
"data": [
{
"id": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s",
"url": "https://hooks.example.com/cloudtalk",
"description": "CRM sync",
"eventTypes": [
"call.ended",
"dialer.disposition_created"
],
"status": "enabled",
"createdAt": "2026-10-13T09:12:44Z",
"updatedAt": "2026-10-13T09:12:44Z"
}
],
"pagination": {
"limit": 20,
"next": null
},
"requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}
}
}
},
"400": {
"description": "Invalid `limit` or `cursor` (codes VALIDATION.INVALID_PARAMETER, PAGINATION.INVALID_CURSOR).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Create a webhook endpoint",
"description": "Creates an endpoint and returns it with its signing secret. This response is the only time the secret is part of the resource; read it again with `GET /webhooks/endpoints/{endpointId}/secret`.\n\nThe URL must be `https://` and point at a public host: private, loopback and other non-public addresses, internal names and non-ASCII hosts are rejected. A company can have at most 50 endpoints, Dashboard-created ones included.\n\nSend an `Idempotency-Key` to make retries safe. A retry with the same key and the same body returns the endpoint the first request created (201), even when the company has since reached the endpoint limit. The same key with a different body is rejected with 422. After the endpoint is deleted, the key creates a new one.",
"operationId": "public-v1-create-webhook-endpoint",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Free text up to 255 characters naming this create. See the operation description.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpointCreate"
},
"example": {
"url": "https://hooks.example.com/cloudtalk",
"description": "CRM sync",
"eventTypes": [
"call.ended"
]
}
}
}
},
"responses": {
"201": {
"description": "The created endpoint, with its signing secret.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpoint"
},
"example": {
"id": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s",
"url": "https://hooks.example.com/cloudtalk",
"description": "CRM sync",
"eventTypes": [
"call.ended"
],
"status": "enabled",
"createdAt": "2026-10-13T09:12:44Z",
"updatedAt": "2026-10-13T09:12:44Z",
"secret": "whsec_EXAMPLE_SIGNING_SECRET"
}
}
}
},
"400": {
"description": "The body is not valid JSON for this operation, or `Idempotency-Key` is longer than 255 characters (codes VALIDATION.INVALID_BODY, VALIDATION.INVALID_PARAMETER).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"409": {
"description": "The company already has the maximum number of endpoints (code WEBHOOKS.ENDPOINT_LIMIT_REACHED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "The body is not declared `application/json` (code UNSUPPORTED_MEDIA_TYPE).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"422": {
"description": "Invalid field: `url` (code WEBHOOKS.INVALID_URL), `eventTypes` with unknown types or empty (codes WEBHOOKS.UNKNOWN_EVENT_TYPE, VALIDATION.INVALID_FIELD), `description` over 500 characters, or an `Idempotency-Key` already used for a different body (code IDEMPOTENCY.KEY_REUSED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Get a webhook endpoint",
"description": "Returns one endpoint. The signing secret is not included.",
"operationId": "public-v1-get-webhook-endpoint",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"responses": {
"200": {
"description": "The endpoint.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpoint"
},
"example": {
"id": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s",
"url": "https://hooks.example.com/cloudtalk",
"description": "CRM sync",
"eventTypes": [
"call.ended",
"dialer.disposition_created"
],
"status": "enabled",
"createdAt": "2026-10-13T09:12:44Z",
"updatedAt": "2026-10-13T09:12:44Z"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"patch": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Update a webhook endpoint",
"description": "Changes any of `url`, `description`, `eventTypes` and `enabled`; fields you omit stay as they are. `eventTypes: null` subscribes the endpoint to every event type, including future ones. `url`, `description` and `enabled` cannot be null.\n\n`enabled: false` turns the endpoint off and its `status` becomes `disabled`; CloudTalk will not re-enable it automatically. `enabled: true` turns it back on, including an endpoint that was disabled automatically after repeated delivery failures (`status: failing`).",
"operationId": "public-v1-update-webhook-endpoint",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpointUpdate"
},
"example": {
"enabled": false
}
}
}
},
"responses": {
"200": {
"description": "The updated endpoint.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpoint"
},
"example": {
"id": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s",
"url": "https://hooks.example.com/cloudtalk",
"description": "CRM sync",
"eventTypes": [
"call.ended",
"dialer.disposition_created"
],
"status": "disabled",
"createdAt": "2026-10-13T09:12:44Z",
"updatedAt": "2026-10-13T09:12:44Z"
}
}
}
},
"400": {
"description": "The body is not valid JSON for this operation (code VALIDATION.INVALID_BODY).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "The body is not declared `application/json` (code UNSUPPORTED_MEDIA_TYPE).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"422": {
"description": "Nothing to update, an explicit null for `url`, `description` or `enabled`, or an invalid field (codes VALIDATION.INVALID_FIELD, WEBHOOKS.INVALID_URL, WEBHOOKS.UNKNOWN_EVENT_TYPE).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
},
"delete": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Delete a webhook endpoint",
"description": "Deletes the endpoint and stops delivery to it. This cannot be undone: the endpoint, its signing secret and its delivery history are gone.",
"operationId": "public-v1-delete-webhook-endpoint",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"responses": {
"204": {
"description": "Deleted."
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/secret": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Get the signing secret",
"description": "Returns the endpoint's current signing secret, used to verify webhook signatures.",
"operationId": "public-v1-get-webhook-endpoint-secret",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"responses": {
"200": {
"description": "The secret.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookSecret"
},
"example": {
"secret": "whsec_EXAMPLE_SIGNING_SECRET"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/secret/rotate": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Rotate the signing secret",
"description": "Replaces the signing secret and returns the new one. For the next 24 hours deliveries are signed with both the old and the new secret, so you can roll the new one out without dropping events.",
"operationId": "public-v1-rotate-webhook-endpoint-secret",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"responses": {
"200": {
"description": "The new secret, and when the previous one stops signing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookRotatedSecret"
},
"example": {
"secret": "whsec_EXAMPLE_NEW_SIGNING_SECRET",
"previousSecretExpiresAt": "2026-10-15T09:30:12Z"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/test": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Send a test event",
"description": "Sends a sample payload of one event type to the endpoint. The payload has the real structure of that event with placeholder values. Delivery is asynchronous: use the returned `deliveryId` with the delivery endpoints; it appears there from the first delivery attempt, usually within seconds.\n\nThe event type must be one the endpoint is subscribed to (an endpoint subscribed to every type accepts any), and the endpoint must be enabled. Test events and delivery retries share a limit of 10 per minute per company.",
"operationId": "public-v1-send-webhook-test-event",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookTestRequest"
},
"example": {
"eventType": "call.ended"
}
}
}
},
"responses": {
"202": {
"description": "The test event is queued.",
"headers": {
"X-CloudTalkAPI-Send-Limit": {
"description": "Test and retry requests allowed per company in the current one-minute window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-Remaining": {
"description": "Test and retry requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-ResetTime": {
"description": "Unix timestamp (seconds) when the current window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookAcceptedDelivery"
},
"example": {
"deliveryId": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3"
}
}
}
},
"400": {
"description": "The body is not valid JSON for this operation (code VALIDATION.INVALID_BODY).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"409": {
"description": "The endpoint is disabled (code WEBHOOKS.ENDPOINT_DISABLED). Enable it first.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"415": {
"description": "The body is not declared `application/json` (code UNSUPPORTED_MEDIA_TYPE).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"422": {
"description": "`eventType` is missing, unknown, or not one the endpoint is subscribed to (codes VALIDATION.INVALID_FIELD, WEBHOOKS.UNKNOWN_EVENT_TYPE, WEBHOOKS.EVENT_TYPE_NOT_SUBSCRIBED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"description": "Too many test or retry requests for this company in the current minute (code RATE_LIMIT.EXCEEDED), with the X-CloudTalkAPI-Send-* headers. A 429 can also come from the gateway's API rate limit; that one carries X-CloudTalkAPI-Limit, -Remaining and -ResetTime instead and no error body.",
"headers": {
"X-CloudTalkAPI-Send-Limit": {
"description": "Test and retry requests allowed per company in the current one-minute window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-Remaining": {
"description": "Test and retry requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-ResetTime": {
"description": "Unix timestamp (seconds) when the current window resets.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Seconds until the window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/deliveries": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "List deliveries",
"description": "Returns one page of the events sent to the endpoint, newest first, without payloads. A delivery is listed from its first attempt. Payloads are kept for 30 days.",
"operationId": "public-v1-list-webhook-deliveries",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size, 1-100. Out-of-range values are clamped and the effective value is echoed in `pagination.limit`.",
"schema": {
"type": "integer",
"default": 20,
"example": 20
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from a previous page's `pagination.next`. Pass it back unchanged. A cursor this API cannot use is rejected with `400 PAGINATION.INVALID_CURSOR`.",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Only deliveries with this final outcome. `failed` excludes deliveries that are still retrying.",
"schema": {
"type": "string",
"enum": [
"succeeded",
"failed"
]
}
},
{
"name": "eventType",
"in": "query",
"required": false,
"description": "Comma-separated event types to include.",
"schema": {
"type": "string",
"example": "call.ended,call.started"
}
},
{
"name": "since",
"in": "query",
"required": false,
"description": "Only deliveries created after this time (RFC 3339).",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "until",
"in": "query",
"required": false,
"description": "Only deliveries created before this time (RFC 3339). Must be later than `since`.",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "One page of deliveries.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryList"
},
"example": {
"data": [
{
"id": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3",
"eventType": "call.ended",
"eventId": "01929c4e-7a3b-7c1d-9f2e-5b6a8c0d1e2f",
"status": "retrying",
"nextAttemptAt": "2026-10-13T09:46:02Z",
"createdAt": "2026-10-13T09:12:44Z"
}
],
"pagination": {
"limit": 20,
"next": null
},
"requestId": "c9856b94-db55-402b-a6ba-adb130351158"
}
}
}
},
"400": {
"description": "Invalid query parameter or cursor (codes VALIDATION.INVALID_PARAMETER, PAGINATION.INVALID_CURSOR).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No endpoint with this id in this company (code WEBHOOKS.ENDPOINT_NOT_FOUND).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/deliveries/{deliveryId}": {
"get": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Get a delivery",
"description": "Returns one delivery with the payload that was sent and every attempt on this endpoint, newest first, including the HTTP status your server answered and the first 4 KB of its response body. After 30 days the payload is no longer kept and `payload` is null.",
"operationId": "public-v1-get-webhook-delivery",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"description": "Delivery id (`msg_...`). It is the same value as the `svix-id` header of the delivered request.",
"schema": {
"type": "string",
"example": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3"
}
}
],
"responses": {
"200": {
"description": "The delivery.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryDetail"
},
"example": {
"id": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3",
"eventType": "call.ended",
"eventId": "01929c4e-7a3b-7c1d-9f2e-5b6a8c0d1e2f",
"status": "retrying",
"nextAttemptAt": "2026-10-13T09:46:02Z",
"createdAt": "2026-10-13T09:12:44Z",
"payload": {
"type": "call.ended",
"data": {
"call_id": "123456"
}
},
"attempts": [
{
"id": "atmpt_2nJ5c1Lq8sRvY3kD0aWbXhZt7Me",
"createdAt": "2026-10-13T09:31:02Z",
"status": "failed",
"responseStatusCode": 503,
"responseDurationMs": 412,
"responseBody": "Service Unavailable",
"responseTruncated": false,
"trigger": "scheduled"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No such delivery on this endpoint (code WEBHOOKS.DELIVERY_NOT_FOUND), or no such endpoint (code WEBHOOKS.ENDPOINT_NOT_FOUND). A delivery is found from its first attempt.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"$ref": "#/components/responses/WebhooksRateLimited"
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
},
"/webhooks/endpoints/{endpointId}/deliveries/{deliveryId}/retry": {
"post": {
"servers": [
{
"url": "https://api.cloudtalk.io/v1"
}
],
"tags": [
"Webhooks"
],
"summary": "Retry a delivery",
"description": "Queues a new attempt of the delivery to this endpoint. Only a delivery this endpoint received can be retried on it. Test events and retries share a limit of 10 per minute per company.",
"operationId": "public-v1-retry-webhook-delivery",
"parameters": [
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "Webhook endpoint id (`ep_...`).",
"schema": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"description": "Delivery id (`msg_...`). It is the same value as the `svix-id` header of the delivered request.",
"schema": {
"type": "string",
"example": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3"
}
}
],
"responses": {
"202": {
"description": "The retry is queued.",
"headers": {
"X-CloudTalkAPI-Send-Limit": {
"description": "Test and retry requests allowed per company in the current one-minute window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-Remaining": {
"description": "Test and retry requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-ResetTime": {
"description": "Unix timestamp (seconds) when the current window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookAcceptedDelivery"
},
"example": {
"deliveryId": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Webhooks are not included in this company's plan (code WEBHOOKS.NOT_ENABLED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"404": {
"description": "No such delivery on this endpoint (code WEBHOOKS.DELIVERY_NOT_FOUND), or no such endpoint.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"429": {
"description": "Too many test or retry requests for this company in the current minute (code RATE_LIMIT.EXCEEDED), with the X-CloudTalkAPI-Send-* headers. A 429 can also come from the gateway's API rate limit; that one carries X-CloudTalkAPI-Limit, -Remaining and -ResetTime instead and no error body.",
"headers": {
"X-CloudTalkAPI-Send-Limit": {
"description": "Test and retry requests allowed per company in the current one-minute window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-Remaining": {
"description": "Test and retry requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Send-ResetTime": {
"description": "Unix timestamp (seconds) when the current window resets.",
"schema": {
"type": "integer"
}
},
"Retry-After": {
"description": "Seconds until the window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"502": {
"description": "The webhook service is unavailable (code WEBHOOKS.UPSTREAM_UNAVAILABLE). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
},
"504": {
"description": "The webhook service did not answer within the 10-second request budget (code WEBHOOKS.UPSTREAM_TIMEOUT). Retry the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicErrorBody"
}
}
}
}
}
}
}
},
"components": {
"responses": {
"BadRequest": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 400,
"message": "Validation error",
"error": "Bad Request",
"correlationId": "YevPQs",
"subErrors": [
"incorrect email"
]
}
}
}
},
"Unauthorized": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Error envelope returned by the authentication layer in front of the `api.cloudtalk.io/v1` surface. It differs from the per-service error shapes used for other statuses.",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "UNAUTHORIZED"
},
"message": {
"type": "string",
"description": "Error message",
"example": "You are not authorized to access this resource."
}
},
"required": [
"code",
"message"
]
},
"example": {
"code": "UNAUTHORIZED",
"message": "You are not authorized to access this resource."
}
}
}
},
"NotFound": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 404,
"message": "Not Found",
"error": "Not Found",
"correlationId": "YevPQs"
}
}
}
},
"InternalServerError": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 500,
"message": "Internal Server Error",
"error": "Internal Server Error",
"correlationId": "YevPQs"
}
}
}
},
"NoContentResponse": {
"description": "Operation completed successfully. A 204 response has an empty body."
},
"Conflict": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 409,
"message": "Conflict",
"error": "Conflict",
"correlationId": "YevPQs"
}
}
}
},
"ServiceUnavailable": {
"description": "Service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 503,
"message": "Service Unavailable",
"error": "Service Unavailable",
"correlationId": "YevPQs"
}
}
}
},
"TooManyRequests": {
"description": "Too many requests",
"headers": {
"X-CloudTalkAPI-Limit": {
"description": "Maximum number of API requests allowed in the current time window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Remaining": {
"description": "Number of API requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-ResetTime": {
"description": "Time when the rate-limit window resets, as a Unix timestamp.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 429,
"message": "Too Many Requests",
"error": "Too Many Requests",
"correlationId": "YevPQs"
}
}
}
},
"UnprocessableEntity": {
"description": "Unprocessable entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DialerError"
},
"example": {
"statusCode": 422,
"message": "Unprocessable Entity",
"error": "Unprocessable Entity",
"correlationId": "YevPQs"
}
}
}
},
"WebhooksRateLimited": {
"description": "Too many requests: this company is over the API rate limit (see the Rate limiting guide). The gateway answers before the request reaches the webhooks API, so there is no JSON error body; rely on the status and the headers X-CloudTalkAPI-Limit, X-CloudTalkAPI-Remaining and X-CloudTalkAPI-ResetTime.",
"headers": {
"X-CloudTalkAPI-Limit": {
"description": "Requests allowed per company in the current one-minute window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-Remaining": {
"description": "Requests left in the current window.",
"schema": {
"type": "integer"
}
},
"X-CloudTalkAPI-ResetTime": {
"description": "Unix timestamp (seconds) when the current window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"text/plain": {
"schema": {
"type": "string",
"description": "Empty or a short plain-text reason from the gateway. Do not parse it."
},
"example": ""
}
}
}
},
"schemas": {
"CallTranscription": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number",
"description": "Start time of the segment in seconds"
},
"end": {
"type": "number",
"description": "End time of the segment in seconds"
},
"caller": {
"type": "string",
"description": "Caller local identifier"
},
"text": {
"type": "string",
"description": "Transcription text of the segment"
}
},
"required": [
"start",
"end",
"caller",
"text"
]
}
},
"callers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Caller"
}
},
"language": {
"type": "string",
"description": "Language of the transcription"
}
},
"required": [
"callId",
"segments",
"callers",
"language"
]
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"data",
"pagination"
],
"example": {
"data": {
"callId": 12345,
"segments": [
{
"start": 1.501,
"end": 4.599,
"caller": "caller2",
"text": "Hello, I would like to ask for help."
},
{
"start": 5.173,
"end": 8.599,
"caller": "caller1",
"text": "Hi. What's your issue?"
}
],
"callers": [
{
"id": 5000,
"type": "contact",
"localIdentifier": "caller1"
},
{
"id": 1000,
"type": "agent",
"localIdentifier": "caller2"
}
],
"language": "en"
},
"pagination": {
"limit": 2,
"offset": 0,
"total": 10
}
}
},
"CallOverallSentiment": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"overallSentiment": {
"type": "string",
"description": "Overall sentiment of the call",
"enum": [
"very negative",
"negative",
"neutral",
"positive",
"very positive"
]
}
},
"required": [
"callId",
"overallSentiment"
],
"example": {
"callId": 12345,
"overallSentiment": "positive"
}
},
"CallTalkListenRatio": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"talkListenRatio": {
"type": "array",
"items": {
"type": "object",
"properties": {
"caller": {
"type": "string",
"description": "Caller local identifier"
},
"talkingTime": {
"type": "number",
"description": "Talking time of the caller in seconds"
},
"ratio": {
"type": "number",
"description": "Talk to listen ratio of the caller in percentage"
}
},
"required": [
"caller",
"talkingTime",
"ratio"
]
}
},
"callers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Caller"
}
}
},
"required": [
"callId",
"talkListenRatio",
"callers"
],
"example": {
"callId": 12345,
"talkListenRatio": [
{
"caller": "caller1",
"talkingTime": 120,
"ratio": 60
},
{
"caller": "caller2",
"talkingTime": 80,
"ratio": 40
}
],
"callers": [
{
"id": 5000,
"type": "contact",
"localIdentifier": "caller1"
},
{
"id": 1000,
"type": "agent",
"localIdentifier": "caller2"
}
]
}
},
"CallSmartNotes": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"smartNotes": {
"type": "object",
"description": "Smart notes of the call",
"properties": {
"callDetails": {
"$ref": "#/components/schemas/CallDetailsNote"
},
"actionItems": {
"type": "array",
"description": "Specific tasks assigned during the call",
"items": {
"type": "string"
}
},
"decisionsMade": {
"type": "array",
"description": "Important decisions agreed upon during the call",
"items": {
"type": "string"
}
},
"openQuestions": {
"type": "array",
"description": "Questions that need to be addressed after the call",
"items": {
"type": "string"
}
},
"importantDatesAndDeadlines": {
"$ref": "#/components/schemas/ImportantDatesAndDeadlinesNotes"
},
"risksAndIssues": {
"type": "array",
"description": "Identify potential risks or issues discussed during the call",
"items": {
"type": "string"
}
},
"customerFeedback": {
"type": "array",
"description": "Highlight feedback from customers that can inform product development or service improvement",
"items": {
"type": "string"
}
}
},
"required": [
"callDetails"
]
}
},
"required": [
"callId",
"smartNotes"
],
"example": {
"callId": 12345,
"smartNotes": {
"callDetails": {
"callDateTime": "2024-01-01T21:00:00Z",
"participants": [
{
"name": "Jone Smith",
"jobPosition": "Job position",
"company": "Company",
"callerType": "agent"
},
{
"name": "Tatiana Rogers",
"callerType": "contact"
}
],
"callMetadata": "Reservation number"
},
"actionItems": [
"Determine the final price"
],
"decisionsMade": [
"Make an order"
],
"openQuestions": [
"Final price"
],
"importantDatesAndDeadlines": [
{
"dateMention": "2024-01-11T10:00:00Z",
"eventDescription": "Repeat the call"
}
],
"risksAndIssues": [
"Concern about the cost of the services"
],
"customerFeedback": [
"Good service"
]
}
}
},
"CallDetailsNote": {
"type": "object",
"description": "Significant updates discussed during the call",
"properties": {
"callDateTime": {
"type": "string",
"description": "Date and time of the call",
"format": "date-time"
},
"participants": {
"type": "array",
"description": "Name, position and company of participants of the call",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "First and last name"
},
"jobPosition": {
"type": "string",
"description": "Job position"
},
"company": {
"type": "string",
"description": "Company name"
},
"callerType": {
"type": "string",
"description": "Caller type",
"enum": [
"agent",
"contact"
]
}
},
"required": [
"callerType"
]
}
},
"callMetadata": {
"type": "string",
"description": "Metadata such as location, reservation number, etc"
}
},
"required": [
"callDateTime",
"participants"
]
},
"ImportantDatesAndDeadlinesNotes": {
"type": "array",
"description": "Capture significant dates mentioned, with clickable links to add them directly to the calendar",
"items": {
"type": "object",
"properties": {
"dateMention": {
"type": "string",
"description": "Date and time of the event",
"format": "date-time"
},
"eventDescription": {
"type": "string",
"description": "Description of the event"
}
},
"required": [
"dateMention",
"eventDescription"
]
}
},
"CallTopicSpan": {
"type": "object",
"properties": {
"end": {
"type": "number",
"description": "End time of the span in seconds"
},
"text": {
"type": "string",
"description": "Transcription of the span"
},
"start": {
"type": "number",
"description": "Start time of the span in seconds"
},
"caller": {
"type": "string",
"description": "Caller local identifier"
}
},
"required": [
"end",
"text",
"start",
"caller"
]
},
"CallTopic": {
"type": "object",
"properties": {
"spans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallTopicSpan"
}
},
"topic": {
"type": "string",
"description": "Topic of the call"
},
"weight": {
"type": "number",
"description": "Weight of the topic"
}
},
"required": [
"spans",
"topic",
"weight"
]
},
"CallTopics": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"callId": {
"type": "number",
"description": "ID of the call"
},
"topics": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallTopic"
}
},
"callers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Caller"
}
}
},
"required": [
"callId",
"topics",
"callers"
]
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
},
"required": [
"data",
"pagination"
],
"example": {
"data": {
"callId": 12345,
"topics": [
{
"spans": [
{
"end": 3.182,
"text": "Let's start the discussion in this group.",
"start": 1.867,
"caller": "caller1"
}
],
"topic": "Group Call",
"weight": 0.5
}
],
"callers": [
{
"id": 5000,
"type": "contact",
"localIdentifier": "caller1"
},
{
"id": 1000,
"type": "agent",
"localIdentifier": "caller2"
}
]
},
"pagination": {
"limit": 1,
"offset": 0,
"total": 10
}
}
},
"Caller": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"agent",
"contact"
],
"description": "Type of caller"
},
"id": {
"type": "integer",
"description": "Caller ID if exists in the system",
"nullable": true
},
"localIdentifier": {
"type": "string",
"description": "Local identifier of the caller"
}
},
"required": [
"id",
"type",
"localIdentifier"
],
"example": {
"id": 1000,
"type": "agent",
"localIdentifier": "caller1"
}
},
"Pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of items to return",
"example": 10
},
"offset": {
"type": "integer",
"description": "Offset of the returned items",
"example": 0
},
"total": {
"type": "integer",
"description": "Total number of items",
"example": 100
}
},
"required": [
"limit",
"offset",
"total"
]
},
"CueCardRequest": {
"type": "object",
"required": [
"title",
"call_uuid",
"type",
"content"
],
"properties": {
"call_uuid": {
"type": "string",
"description": "unique id of the active call"
},
"type": {
"type": "string"
},
"title": {
"type": "string",
"description": "Cue card Title"
},
"subtitle": {
"type": "string",
"description": "Cue card Subtitle"
},
"icon_url": {
"type": "string",
"description": "Url path to the cue card icon"
},
"content": {
"oneOf": [
{
"$ref": "#/components/schemas/ContentHTML"
},
{
"$ref": "#/components/schemas/ContentBlock"
}
]
}
}
},
"ContentHTML": {
"type": "string",
"description": "The value as typed in html text editor"
},
"ContentBlock": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ContentBlockTextField"
},
{
"$ref": "#/components/schemas/ContentBlockRichText"
},
{
"$ref": "#/components/schemas/ContentBlockImage"
},
{
"$ref": "#/components/schemas/ContentBlockFile"
}
]
}
},
"ContentBlockTextField": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string",
"description": "Field name to display"
},
"value": {
"type": "string",
"description": "text field value"
}
}
},
"ContentBlockRichText": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string",
"description": "Field name to display"
},
"value": {
"type": "string",
"description": "The value as typed in Rich text editor"
}
}
},
"ContentBlockImage": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string",
"description": "image name to display"
},
"image_url": {
"type": "string",
"description": "url path to image"
}
}
},
"ContentBlockFile": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string",
"description": "file name to display"
},
"file_url": {
"type": "string",
"description": "url path to file"
},
"icon_url": {
"type": "string",
"description": "url path to file icon"
}
}
},
"CueCardError": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"description": "array of errors",
"items": {
"type": "string"
}
}
}
},
"Cdr": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Call ID"
},
"billsec": {
"type": "integer",
"description": "Duration of the call in seconds"
},
"type": {
"type": "string",
"description": "Type of call",
"enum": [
"incoming",
"outgoing",
"internal"
]
},
"public_external": {
"type": "string",
"description": "The number of the caller in E.164 format"
},
"public_internal": {
"type": "string",
"description": "The internal number of agent in E.164 format"
},
"recorded": {
"type": "boolean",
"description": "Was call recorded?"
},
"is_voicemail": {
"type": "boolean",
"description": "Is voicemail call?"
},
"fax_email": {
"type": "string",
"description": "If present, call was made to fax using this email"
},
"is_redirected": {
"type": "string",
"description": "Was call redirected?"
},
"redirected_from": {
"type": "string",
"description": "If the call was redirected, here is the number from which it was redirected"
},
"transferred_from": {
"type": "string",
"description": "Where did the call was transferred from?"
},
"is_local": {
"type": "boolean",
"description": "Is local or international call?"
},
"user_id": {
"type": "integer",
"description": "Agent ID assigned to this call"
},
"talking_time": {
"type": "integer",
"description": "Duration of the connection between agent and customer"
},
"started_at": {
"type": "string",
"description": "Date and time when the call started",
"format": "date-time"
},
"answered_at": {
"type": "string",
"description": "Date and time when the call was answered",
"format": "date-time"
},
"ended_at": {
"type": "string",
"description": "Date and time when the call finished",
"format": "date-time"
},
"waiting_time": {
"type": "integer",
"description": "Duration before connection between agent and customer"
},
"wrapup_time": {
"type": "integer",
"description": "Duration of wrap up time"
},
"recording_link": {
"type": "string",
"description": "Link to the analytics call-detail page for the call, which hosts the recording. Present only for recorded calls with a non-zero billed duration."
}
},
"description": "Call data"
},
"BillingData": {
"type": "object",
"properties": {
"price": {
"type": "number",
"description": "Price of the call"
}
},
"description": "Billing data of the call"
},
"Agent": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
},
"name": {
"type": "string",
"description": "Agent\\'s Voice ID"
},
"firstname": {
"type": "string",
"description": "First name"
},
"lastname": {
"type": "string",
"description": "Last name"
},
"email": {
"type": "string",
"description": "Email",
"format": "email"
},
"pass": {
"type": "string",
"description": "Password"
},
"daily_price_limit": {
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Daily price limit for all calls in EUR. Usually allowed values are from 1 to 200 EUR. Leave empty for using default value."
},
"is_daily_limit_ok": {
"type": "boolean",
"description": "Is daily price limit OK? If not, agent cannot make new calls"
},
"status_outbound": {
"type": "boolean",
"description": "Does agent have outbound calls allowed?"
},
"availability_status": {
"type": "string",
"description": "Current availability status of the agent; \"unknown\" is returned when the agent state source is temporarily unavailable",
"enum": [
"online",
"offline",
"paused",
"calling",
"unknown"
]
},
"extension": {
"maximum": 9999,
"minimum": 1000,
"type": "integer",
"description": "Extension of an agent. Extension must be four digits long and be unique across whole company."
},
"call_number_id": {
"minimum": 1,
"type": "integer",
"description": "Default outbound number ID"
},
"default_number": {
"type": "string",
"description": "Default outbound number in E164 format"
},
"associated_numbers": {
"type": "array",
"description": "array of e164 numbers that the agent has assigned",
"items": {
"type": "string"
}
}
},
"description": "Agent data"
},
"AgentCall": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
},
"firstname": {
"type": "string",
"description": "First name"
},
"lastname": {
"type": "string",
"description": "Last name"
},
"fullname": {
"type": "string",
"description": "Full name"
},
"email": {
"type": "string",
"description": "Email",
"format": "email"
},
"language": {
"type": "string",
"description": "Language"
},
"role": {
"type": "string",
"description": "Role"
},
"status": {
"type": "string",
"description": "Online status"
},
"default_outbound_number": {
"type": "string",
"description": "Default outbound number in E164 format"
},
"associated_numbers": {
"type": "array",
"description": "Array of associated numbers",
"items": {
"type": "string"
}
},
"groups": {
"type": "array",
"description": "Array of assigned groups",
"items": {
"type": "string"
}
}
},
"description": "Agent data"
},
"FavoriteAgent": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
},
"firstname": {
"type": "string",
"description": "First name"
},
"lastname": {
"type": "string",
"description": "Last name"
},
"fullname": {
"type": "string",
"description": "Full name"
},
"email": {
"type": "string",
"description": "Email",
"format": "email"
},
"language": {
"type": "string",
"description": "Language"
},
"role": {
"type": "string",
"description": "Role"
},
"status": {
"type": "string",
"description": "Online status"
},
"default_outbound_number": {
"type": "string",
"description": "Default outbound number in E164 format"
},
"associated_numbers": {
"type": "array",
"description": "Array of associated numbers",
"items": {
"type": "string"
}
},
"groups": {
"type": "array",
"description": "Array of assigned groups",
"items": {
"type": "string"
}
}
},
"description": "Agent data"
},
"CallNumber": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Number ID"
},
"country_code": {
"type": "integer",
"description": "Country calling code"
},
"area_code": {
"type": "integer",
"description": "Local area code"
},
"internal_name": {
"type": "string",
"description": "Internal name"
},
"caller_id_e164": {
"type": "string",
"description": "Full number in international E.164 format"
},
"is_redirected": {
"type": "boolean",
"description": "Is number redirected?"
},
"connected_to": {
"type": "integer",
"description": "Routing type. Where is the number connected. `0 = 'group'`, `1 = 'agent'`, `2 = 'conference room'`, `3 = 'fax'`"
},
"source_id": {
"type": "integer",
"description": "Source ID of where is the number located, e.g. Agent ID, Group ID..."
}
},
"description": "Number data"
},
"ContactList": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Contact ID"
},
"name": {
"type": "string",
"description": "Name"
},
"company": {
"type": "string",
"description": "Company name"
}
},
"description": "Contact data"
},
"Contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Contact ID"
},
"name": {
"type": "string",
"description": "Name",
"maxLength": 150
},
"title": {
"type": "string",
"description": "Title",
"maxLength": 255
},
"company": {
"type": "string",
"description": "Company name",
"maxLength": 100
},
"industry": {
"type": "string",
"description": "Industry",
"maxLength": 100
},
"website": {
"type": "string",
"description": "Website",
"maxLength": 100
},
"address": {
"type": "string",
"description": "Address",
"maxLength": 255
},
"city": {
"type": "string",
"description": "City",
"maxLength": 255
},
"zip": {
"type": "string",
"description": "ZIP code",
"maxLength": 15
},
"state": {
"type": "string",
"description": "State",
"maxLength": 255
},
"country_id": {
"type": "integer",
"description": "Country ID"
},
"favorite_agent": {
"type": "integer",
"description": "Favorite agent ID"
},
"type": {
"type": "string",
"description": "Type of contact (contact/lead)"
},
"created": {
"type": "string",
"description": "Created date and time",
"format": "date-time"
},
"modified": {
"type": "string",
"description": "Last modified date and time",
"format": "date-time"
},
"contact_numbers": {
"type": "array",
"description": "Array of contact numbers",
"items": {
"type": "string"
}
},
"contact_emails": {
"type": "array",
"description": "Array of contact emails",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"description": "Array of contact tags",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
}
}
},
"external_urls": {
"type": "array",
"description": "Array of contact external urls",
"items": {
"type": "object",
"properties": {
"external_system": {
"type": "string",
"description": "Name of external service. Name will be shown to agents while working with contacts."
},
"external_url": {
"type": "string",
"description": "External URL to contact page"
}
}
}
},
"custom_fields": {
"type": "array",
"description": "Array of contact emails",
"items": {
"type": "object",
"maximum": 255,
"properties": {
"key": {
"type": "string",
"description": "Custom field key (max 255 chars per attribute)"
},
"value": {
"type": "string",
"description": "Custom field value (max 255 chars per attribute)"
}
}
}
}
},
"description": "Contact data"
},
"ExternalUrlArray": {
"type": "array",
"maxItems": 3,
"description": "List of all URLs which points to a detail page of a contact in an external service, e.g. CRMs, Helpdesk or any other custom service you use. You may list up to 3 URLs.",
"items": {
"type": "object",
"properties": {
"name": {
"maxLength": 30,
"type": "string",
"description": "Name of external service. Name will be shown to agents while working with contacts."
},
"url": {
"type": "string",
"description": "External URL to contact page"
}
}
}
},
"ContactNumber": {
"type": "object",
"properties": {
"public_number": {
"type": "string",
"description": "Full number in international E.164 format"
}
},
"description": "Number assigned to contact"
},
"ContactNumberArray": {
"type": "array",
"description": "Numbers assigned to contact",
"items": {
"type": "object",
"properties": {
"public_number": {
"type": "string",
"description": "Full number in international E.164 format"
}
}
}
},
"ContactEmail": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address",
"format": "email"
}
},
"description": "Email assigned to contact"
},
"ContactEmailArray": {
"type": "array",
"description": "Emails assigned to contact",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address",
"format": "email"
}
}
}
},
"ContactsTag": {
"type": "array",
"description": "Tags for contact - can include multiple",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Tag"
}
}
}
},
"ContactAttribute": {
"type": "array",
"description": "Attributes for contact - can include multiple",
"items": {
"type": "object",
"properties": {
"attribute_id": {
"type": "integer",
"description": "Attribute ID"
},
"title": {
"type": "string",
"description": "Attribute name (max 255 chars per attribute)",
"maxLength": 255
},
"value": {
"type": "string",
"description": "Attribute value (max 255 chars per attribute)",
"maxLength": 255
}
}
}
},
"ContactNote": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Note ID"
},
"contact_id": {
"type": "integer",
"description": "Assigned contact ID"
},
"user_id": {
"type": "integer",
"description": "Assigned agent ID"
},
"note": {
"type": "string",
"description": "Note content"
},
"created": {
"type": "string",
"description": "Created date and time",
"format": "date-time"
}
},
"description": "Note data"
},
"ContactActivity": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Activity ID"
},
"contact_id": {
"type": "integer",
"description": "Assigned contact ID"
},
"type": {
"type": "string",
"description": "Type of activity",
"enum": [
"order",
"task",
"chat",
"ticket",
"other",
"invoice",
"proforma",
"estimate",
"cancel"
]
},
"name": {
"type": "string",
"description": "Name/Title"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"activity_author": {
"type": "string",
"description": "Author of activity - user name you want to show"
},
"external_id": {
"type": "integer",
"description": "Activity ID from external resource - e.g. your order ID"
},
"external_url": {
"type": "string",
"description": "External url which can be opened from activity detail"
},
"activity_date": {
"type": "string",
"description": "Activity date and time. Set to current company time by default.",
"format": "date-time"
},
"created": {
"type": "string",
"description": "Created date and time",
"format": "date-time"
}
},
"description": "Activity data"
},
"Country": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Country ID"
},
"name": {
"type": "string",
"description": "Name"
},
"country_code": {
"type": "string",
"description": "Country code by ISO_3166-1 Alpha-2"
},
"iso3": {
"type": "string",
"description": "Country code by ISO_3166-1 Alpha-3"
},
"calling_code": {
"type": "string",
"description": "Country calling code"
}
},
"description": "Country data"
},
"Blacklist": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Blacklist ID"
},
"type": {
"type": "string",
"description": "Type of calls",
"enum": [
"all",
"incoming",
"outgoing"
]
},
"public_number": {
"type": "string",
"description": "Blacklisted number in E.164 format"
},
"created": {
"type": "string",
"description": "Created date and time",
"format": "date-time"
},
"modified": {
"type": "string",
"description": "Last modified date and time",
"format": "date-time"
}
},
"description": "Blacklist data"
},
"CallTag": {
"type": "array",
"description": "Tags assigned to this call - can include multiple",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag"
}
}
}
},
"CallNote": {
"type": "array",
"description": "Notes assigned to this call",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Note ID"
},
"name": {
"type": "string",
"description": "Note"
}
}
}
},
"CallRating": {
"type": "array",
"description": "Ratings assigned to this call",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Rating ID"
},
"type": {
"type": "string",
"description": "Type of person who added the rating",
"enum": [
"agent",
"contact"
]
},
"rating": {
"type": "integer",
"description": "Rating value 1 to 5 (from worst to best)"
}
}
}
},
"CampaignList": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Campaign ID"
},
"name": {
"type": "string",
"description": "Campaign name"
},
"status": {
"type": "string",
"description": "Campaign status (active/inactive)"
},
"has_schedule_date": {
"type": "boolean",
"description": "Is campaign scheduled?"
},
"schedule_start_date": {
"type": "string",
"description": "Campaign start date",
"format": "date"
},
"schedule_start_time": {
"type": "string",
"description": "Campaign start time",
"format": "time"
},
"answer_wait_time": {
"type": "integer",
"description": "Maximum number of seconds we will wait for the call to be answered."
},
"after_call_dialing_auto": {
"type": "boolean",
"description": "Automatically dial next contact after a call ends true/false"
},
"after_call_time": {
"type": "integer",
"description": "After call time (in seconds)"
},
"is_recording": {
"type": "boolean",
"description": "Calls recording true/false"
},
"call_number_id": {
"type": "integer",
"description": "Outbound caller id"
},
"call_script_id": {
"type": "integer",
"description": "Call script ID"
},
"survey_id": {
"type": "integer",
"description": "Survey ID"
},
"is_predictive": {
"type": "integer",
"description": "Is predictive dialer campaign 0/1"
},
"calls_percentage": {
"type": "integer",
"description": "Agents utilization"
},
"attempts": {
"type": "integer",
"description": "Attempts per contact"
},
"attempts_interval": {
"type": "integer",
"description": "Hours between attempts"
}
},
"description": "Campaign data"
},
"Button": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Button ID"
},
"title": {
"type": "string",
"description": "Button title"
},
"type": {
"type": "string",
"enum": [
"successful_positive",
"successful_negative",
"rescheduled",
"unsuccessful_call_again",
"unsuccessful_do_not_call"
],
"description": "Button type"
},
"color": {
"type": "string",
"description": "Button color (hex code)"
},
"description": {
"type": "string",
"description": "Button description"
}
},
"description": "Campaign button"
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID"
},
"name": {
"type": "string",
"description": "Tag name"
}
},
"description": "Campaign tag"
},
"PdAgent": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Agent ID"
},
"fullname": {
"type": "string",
"description": "Agent name"
}
},
"description": "Campaign agent"
},
"Group": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Group ID"
},
"internal_name": {
"type": "string",
"description": "Group name"
}
},
"description": "Campaign group"
},
"ContactsBulkDataResponse": {
"type": "array",
"description": "Response data",
"items": {
"type": "object",
"properties": {
"command_id": {
"$ref": "#/components/schemas/command_id"
},
"status": {
"type": "integer",
"description": "Status code"
},
"message": {
"type": "string",
"description": "The error message"
},
"data": {
"type": "object",
"properties": {},
"description": "Available only in add actions or invalid action data. More data explaining the error or id of new entity."
}
}
}
},
"command_id": {
"type": "string",
"description": "Unique action identifier"
},
"ErrorData": {
"type": "object",
"description": "Error envelope returned by the core API on `my.cloudtalk.io/api`. The payload is always wrapped in `responseData`.",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "The error message"
}
},
"required": [
"status",
"message"
]
}
},
"required": [
"responseData"
]
},
"ErrorInvalidData": {
"type": "object",
"description": "Validation-error envelope returned by the core API on `my.cloudtalk.io/api`. The payload is always wrapped in `responseData`.",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "The error message"
},
"data": {
"type": "object",
"properties": {},
"description": "Field-level detail explaining the error"
}
},
"required": [
"status",
"message"
]
}
},
"required": [
"responseData"
]
},
"BinaryData": {
"type": "string",
"format": "binary"
},
"SuccessGeneralData": {
"type": "object",
"description": "Success envelope returned by the core API on `my.cloudtalk.io/api`. The payload is always wrapped in `responseData`.",
"properties": {
"responseData": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Status code"
}
}
}
},
"required": [
"responseData"
]
},
"CallTimes": {
"type": "object",
"properties": {
"total_time": {
"type": "number",
"nullable": true,
"description": "Total time spent in a call"
},
"talking_time": {
"type": "number",
"nullable": true,
"description": "Time spent talking to agent/customer"
},
"wrap_up_time": {
"type": "number",
"nullable": true,
"description": "Time spent in wrap-up screen"
},
"ringing_time": {
"type": "number",
"nullable": true,
"description": "Time spent ringing on an agent"
},
"waiting_time": {
"type": "number",
"nullable": true,
"description": "Time from after leaving IVR to getting answered/missed by agent"
},
"holding_time": {
"type": "number",
"nullable": true,
"description": "Time spent on hold during a call"
}
}
},
"ResolvedByCall": {
"type": "object",
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "ID of a call that resolved this call"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call was resolved"
},
"agent": {
"type": "object",
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "ID of an agent that resolved this call"
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of an agent that resolved this call"
}
}
}
}
},
"AgentStep": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"agent"
]
},
"id": {
"type": "number",
"nullable": true,
"description": "ID of an agent"
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of an agent"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the agent answered/missed the call"
},
"call_id": {
"type": "number",
"description": "ID of a call that was answered/missed by an agent"
},
"call_times": {
"$ref": "#/components/schemas/CallTimes"
},
"group_ids": {
"type": "array",
"items": {
"type": "number"
},
"description": "IDs of groups that the agent belongs to"
},
"status": {
"type": "string",
"enum": [
"answered",
"missed",
"cold_transfer"
],
"description": "Status of the agent call step"
},
"reason": {
"type": "string",
"enum": [
"busy",
"not_picked_up",
"offline",
"idle",
"canceled"
],
"description": "Reason why agent missed the call"
},
"resolved_by": {
"type": "number",
"nullable": true,
"description": "ID of a call that resolved this call"
},
"resolved_by_call": {
"$ref": "#/components/schemas/ResolvedByCall"
}
}
},
"QueueStep": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"queue"
]
},
"id": {
"type": "number",
"nullable": true,
"description": "ID of a queue"
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of a queue"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call was calling the queue"
},
"call_times": {
"$ref": "#/components/schemas/CallTimes"
},
"status": {
"type": "string",
"enum": [
"answered",
"missed",
"cold_transfer"
],
"description": "Status of the queue call step"
},
"reason": {
"type": "string",
"enum": [
"no_agents_online",
"no_agents_available",
"no_agents_picked_up",
"canceled"
],
"description": "Reason why the queue missed the call"
},
"resolved_by": {
"type": "number",
"nullable": true,
"description": "ID of a call that resolved this call"
},
"resolved_by_call": {
"$ref": "#/components/schemas/ResolvedByCall"
},
"strategy": {
"type": "string",
"enum": [
"ringall",
"rrmemory",
"random"
],
"description": "Strategy used by the queue"
},
"agent_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentStep"
}
}
}
},
"IVRStep": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"ivr"
]
},
"id": {
"type": "number",
"nullable": true,
"description": "ID of an IVR"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call was on the IVR step"
},
"total_time": {
"type": "number",
"nullable": true,
"description": "Total time spent in IVR"
},
"option": {
"type": "string",
"nullable": true,
"description": "Option pressed by the caller"
}
}
},
"PlaybackStep": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"playback"
]
},
"id": {
"type": "number",
"nullable": true,
"description": "ID of a playback"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call was on the playback step"
},
"file": {
"type": "string",
"nullable": true,
"description": "File played"
},
"total_time": {
"type": "number",
"nullable": true,
"description": "Total time spent in playback"
}
}
},
"TransferStep": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"transfer"
]
},
"id": {
"type": "number",
"nullable": true,
"description": "ID of a transfer"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call was on the transfer step"
},
"endpoint": {
"type": "string",
"nullable": true,
"description": "Endpoint of the transfer"
},
"status": {
"type": "string",
"enum": [
"answered",
"missed"
],
"description": "Status of the transfer call step"
}
}
},
"Call": {
"type": "object",
"properties": {
"cdr_id": {
"type": "number"
},
"uuid": {
"type": "string"
},
"company_id": {
"type": "number"
},
"date": {
"format": "date-time",
"type": "string",
"description": "Date when the call started"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "ID of a contact"
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of a contact"
},
"country": {
"type": "string",
"nullable": true,
"description": "Country of a contact"
},
"number": {
"type": "string",
"description": "Number of a contact"
}
}
},
"call_tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "ID of a tag"
},
"label": {
"type": "string",
"nullable": true,
"description": "Label of a tag"
}
}
}
},
"call_rating": {
"type": "number",
"nullable": true,
"description": "Rating of a call"
},
"internal_number": {
"type": "object",
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "ID of an internal number"
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of an internal number"
},
"number": {
"type": "string",
"description": "Phone number of an internal number"
}
}
},
"call_times": {
"$ref": "#/components/schemas/CallTimes"
},
"direction": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"internal"
]
},
"type": {
"type": "string",
"enum": [
"power_dialer",
"predictive_dialer",
"callback",
"redirected",
"transferred",
"regular"
]
},
"status": {
"type": "string",
"enum": [
"answered",
"missed"
]
},
"call_steps": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/QueueStep"
},
{
"$ref": "#/components/schemas/AgentStep"
},
{
"$ref": "#/components/schemas/IVRStep"
},
{
"$ref": "#/components/schemas/PlaybackStep"
},
{
"$ref": "#/components/schemas/TransferStep"
}
]
},
"description": "List of call steps"
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
},
"recorded": {
"type": "boolean",
"description": "Indicates if the call was recorded"
},
"out_of_office": {
"type": "boolean",
"description": "Indicates if the call was made in the out of office hours"
}
}
},
"DialerAgentPermissions": {
"type": "object",
"description": "Booleans gating what an agent may do to their queue. Deny by default — an omitted key is false.",
"properties": {
"skip": {
"type": "boolean",
"description": "Agent may skip the contact currently served to them.",
"example": true
},
"remove": {
"type": "boolean",
"description": "Agent may remove a contact from the campaign queue.",
"example": false
},
"reorder": {
"type": "boolean",
"description": "Agent may reorder their own queue.",
"example": false
}
}
},
"DialerAssociationEntry": {
"type": "object",
"description": "One association in the replace-all body. `priority` and `label` are only accepted on `target_tag` entries.",
"required": [
"ref_id"
],
"properties": {
"ref_id": {
"type": "integer",
"description": "Referenced id — a contact-tag id for `target_tag`, a queue-group id for `queue_group`, an agent (user) id for `agent`. Not checked for existence — see the operation description.",
"minimum": 1,
"example": 10
},
"priority": {
"type": "integer",
"description": "`target_tag` only — serving rank; the highest priority is served first. Defaults to 0.",
"minimum": 0,
"example": 10
},
"label": {
"type": "string",
"description": "`target_tag` only — human-readable level name (e.g. Hot / Warm / Cold).",
"maxLength": 60,
"example": "Hot"
}
}
},
"DialerAssociations": {
"type": "object",
"description": "A campaign's associations, grouped by kind.",
"properties": {
"target_tag": {
"type": "array",
"description": "Target-tag associations, each with its priority, label and origin.",
"items": {
"$ref": "#/components/schemas/DialerTargetTagAssociation"
}
},
"queue_group": {
"type": "array",
"description": "Associated queue-group ids.",
"items": {
"type": "integer"
},
"example": [
20
]
},
"agent": {
"type": "array",
"description": "Associated agent (user) ids.",
"items": {
"type": "integer"
},
"example": [
800001
]
}
}
},
"DialerAttemptNoSplit": {
"type": "object",
"description": "Attempts split by whether they were the contact's first attempt or a repeat.",
"properties": {
"first_attempt": {
"type": "integer",
"description": "Attempts that were a contact's first.",
"example": 152
},
"repeat_attempt": {
"type": "integer",
"description": "Attempts that were a repeat for the contact.",
"example": 88
}
}
},
"DialerCallDurationTotals": {
"type": "object",
"nullable": true,
"description": "Duration aggregate over the calls the basis covers; all values are whole seconds. Null means the block is not on the response — an all-time read without `includeDurations=true`, or a failed-open duration lookup. An all-zero block is a real answer: the window's calls simply carry no recorded duration yet (`calls` can trail the dialed count — duration records lag the dial). Zero and null must be treated as different states.",
"properties": {
"calls": {
"type": "integer",
"description": "Calls with a duration record.",
"example": 238
},
"answered_calls": {
"type": "integer",
"description": "Of those, calls with talk time — the denominator of `avg_talk_seconds`.",
"example": 150
},
"talk_seconds": {
"type": "integer",
"description": "Total talk time.",
"example": 21540
},
"total_seconds": {
"type": "integer",
"description": "Total leg time — talk plus ring.",
"example": 26310
},
"ring_seconds": {
"type": "integer",
"description": "`total_seconds - talk_seconds`, floored at 0.",
"example": 4770
},
"avg_talk_seconds": {
"type": "integer",
"description": "Mean talk time over answered calls; 0 when none answered.",
"example": 144
},
"avg_ring_seconds": {
"type": "integer",
"description": "Mean ring time over all matched calls.",
"example": 20
},
"max_talk_seconds": {
"type": "integer",
"description": "Longest single conversation.",
"example": 1260
}
}
},
"DialerCallingPolicy": {
"type": "object",
"description": "Per-call behaviour bundle. Every knob is optional — an omitted knob keeps the service default. Only the knobs documented here are stored — any other key in the bundle is silently dropped.",
"properties": {
"answer_wait": {
"type": "integer",
"description": "Seconds to wait for an answer before giving up on the number.",
"minimum": 0,
"example": 25
},
"after_call": {
"type": "integer",
"description": "Wrap-up (after-call work) seconds granted to the agent; 0 means no wrap-up.",
"minimum": 0,
"example": 10
},
"recording": {
"type": "boolean",
"description": "Whether calls placed by this campaign are recorded.",
"example": true
},
"number_selection": {
"type": "string",
"description": "Strategy used to pick which of a contact's numbers is dialed.",
"example": "first"
},
"outbound_number_id": {
"type": "integer",
"nullable": true,
"description": "Pins the campaign's outbound caller number; null lets the service pick.",
"minimum": 1,
"example": 12
},
"number_rotation_enabled": {
"type": "boolean",
"description": "Enables sequential rotation over a contact's numbers: a number that is not reached (no answer, busy, failed) advances a per-contact cursor to the next number; an answered call stops the cycle. Absent or `false` pins every attempt to the primary number. Must be a boolean when sent — an explicit null is rejected.",
"example": false
},
"parallel_calls": {
"type": "integer",
"description": "Number of simultaneous calls per agent in `parallel` mode.",
"minimum": 0,
"example": 2
},
"voicemail_drop_id": {
"type": "integer",
"description": "Voicemail-drop template used by the agent's voicemail action.",
"minimum": 0,
"example": 7
}
}
},
"DialerCampaign": {
"type": "object",
"description": "A dialer campaign. Identifiers are returned as strings because they are 64-bit integers server-side.",
"properties": {
"id": {
"type": "string",
"description": "Campaign ID.",
"example": "42"
},
"name": {
"type": "string",
"description": "Human-readable campaign name.",
"example": "Q3 renewals"
},
"mode": {
"type": "string",
"description": "Dialing mode.",
"enum": [
"sequential",
"parallel"
],
"example": "sequential"
},
"status": {
"type": "string",
"description": "Lifecycle status. `initializing`: created, membership backfill pending. `active`: the only dialable state. `inactive`: paused, fully reversible. `archived`: review/analytics state, not dialable, exits only back to `inactive`. `deleted`: soft-deleted, terminal.",
"enum": [
"initializing",
"active",
"inactive",
"archived",
"deleted"
],
"example": "active"
},
"calling_policy": {
"$ref": "#/components/schemas/DialerCallingPolicy"
},
"queue_policy": {
"$ref": "#/components/schemas/DialerQueuePolicy"
},
"retry_policy": {
"$ref": "#/components/schemas/DialerRetryPolicy"
},
"schedule_policy": {
"$ref": "#/components/schemas/DialerSchedulePolicy"
},
"ttl_policy": {
"$ref": "#/components/schemas/DialerTtlPolicy"
},
"waterfall_order": {
"type": "array",
"description": "Ordered, duplicate-free subset of the waterfall categories.",
"items": {
"type": "string",
"enum": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"example": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"agent_permissions": {
"$ref": "#/components/schemas/DialerAgentPermissions"
},
"call_script_id": {
"type": "string",
"description": "Linked call-script ID; null when none.",
"nullable": true,
"example": "310"
},
"survey_id": {
"type": "string",
"description": "Linked survey ID; null when none.",
"nullable": true,
"example": "44"
},
"created_at": {
"type": "string",
"description": "Creation timestamp (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-01T09:15:00.000Z"
},
"updated_at": {
"type": "string",
"description": "Last-update timestamp (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T11:42:07.000Z"
},
"archived_at": {
"type": "string",
"description": "When the campaign entered `archived`; cleared on exit, so non-null only while the status is `archived`.",
"format": "date-time",
"nullable": true,
"example": null
},
"deleted_at": {
"type": "string",
"description": "Soft-delete timestamp; null unless the campaign has been deleted.",
"format": "date-time",
"nullable": true,
"example": null
}
}
},
"DialerCampaignContact": {
"type": "object",
"description": "One campaign membership row. Ids are BIGINTs serialized as strings.",
"properties": {
"campaign_contact_id": {
"type": "string",
"description": "Membership row ID — the id used by the single-contact call.",
"example": "5100"
},
"contact_id": {
"type": "string",
"description": "The contact's ID in Contacts.",
"example": "88213"
},
"display_name": {
"type": "string",
"nullable": true,
"description": "Contact display name; null when the snapshot carries none.",
"example": "Jane Kowalski"
},
"phone_number": {
"type": "string",
"nullable": true,
"description": "Primary phone number — the first of the contact's ordered numbers.",
"example": "+421900123456"
},
"queue_tag": {
"type": "string",
"description": "Derived queue position (see the list call's description) — not the raw membership state.",
"enum": [
"assigned",
"scheduled",
"completed",
"dnc",
"exhausted",
"excluded",
"fresh",
"retry",
"rescheduled",
"favorite"
],
"example": "fresh"
},
"attempt_count": {
"type": "integer",
"description": "Completed attempts recorded for this membership.",
"example": 0
},
"next_eligible_at": {
"type": "string",
"description": "When the contact next becomes dialable (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T08:00:00.000Z"
},
"owner_user_id": {
"type": "string",
"nullable": true,
"description": "Agent a scheduled callback is pinned to; null when unpinned.",
"example": null
},
"callback_notes": {
"type": "string",
"nullable": true,
"description": "Free-text note attached to a scheduled callback; null otherwise.",
"example": null
}
}
},
"DialerCampaignContactDetail": {
"type": "object",
"description": "A campaign contact plus best-effort tag enrichment from Contacts.",
"properties": {
"campaign_contact_id": {
"type": "string",
"description": "Membership row ID — the id used by the single-contact call.",
"example": "5100"
},
"contact_id": {
"type": "string",
"description": "The contact's ID in Contacts.",
"example": "88213"
},
"display_name": {
"type": "string",
"nullable": true,
"description": "Contact display name; null when the snapshot carries none.",
"example": "Jane Kowalski"
},
"phone_number": {
"type": "string",
"nullable": true,
"description": "Primary phone number — the first of the contact's ordered numbers.",
"example": "+421900123456"
},
"queue_tag": {
"type": "string",
"description": "Derived queue position (see the list call's description) — not the raw membership state.",
"enum": [
"assigned",
"scheduled",
"completed",
"dnc",
"exhausted",
"excluded",
"fresh",
"retry",
"rescheduled",
"favorite"
],
"example": "fresh"
},
"attempt_count": {
"type": "integer",
"description": "Completed attempts recorded for this membership.",
"example": 0
},
"next_eligible_at": {
"type": "string",
"description": "When the contact next becomes dialable (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T08:00:00.000Z"
},
"owner_user_id": {
"type": "string",
"nullable": true,
"description": "Agent a scheduled callback is pinned to; null when unpinned.",
"example": null
},
"callback_notes": {
"type": "string",
"nullable": true,
"description": "Free-text note attached to a scheduled callback; null otherwise.",
"example": null
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "The contact's CURRENT tag names. Null means the enrichment was unavailable (unknown, not empty); an empty array means the contact genuinely has no tags.",
"example": [
"DACH",
"VIP"
]
}
}
},
"DialerCampaignContactList": {
"type": "object",
"description": "One cursor page of campaign contacts, ordered by dialing eligibility.",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerCampaignContact"
}
},
"meta": {
"$ref": "#/components/schemas/DialerCampaignContactMeta"
}
}
},
"DialerCampaignContactMeta": {
"type": "object",
"description": "Pagination block of the campaign-contacts list. Unlike the other dialer lists it carries `total`.",
"properties": {
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Cursor of the next page; null on the last page.",
"example": null
},
"total": {
"type": "integer",
"description": "Size of the filtered set — moves with `queueTag` and `search`.",
"example": 1
}
}
},
"DialerCampaignList": {
"type": "object",
"description": "Cursor-paginated page of campaigns. Unlike the legacy CloudTalk endpoints this resource is **not** wrapped in `responseData`.",
"properties": {
"data": {
"type": "array",
"description": "One page of campaigns.",
"items": {
"$ref": "#/components/schemas/DialerCampaign"
}
},
"meta": {
"$ref": "#/components/schemas/DialerCursorMeta"
}
}
},
"DialerCampaignStatistics": {
"type": "object",
"description": "Aggregated campaign performance. `range` tells the basis apart: null means all-time (cumulative over the campaign's lifetime, `updated_at` set), non-null means the counters cover exactly that window (`updated_at` null). The membership-state blocks always describe the campaign's current state regardless of any window.",
"properties": {
"campaign_id": {
"type": "string",
"description": "Campaign ID the statistics belong to.",
"example": "42"
},
"contact_states": {
"$ref": "#/components/schemas/DialerContactStateCounts"
},
"contact_states_dialable": {
"allOf": [
{
"$ref": "#/components/schemas/DialerContactStateCounts"
}
],
"description": "Per-state count of contacts that have at least one phone number — a breakout of `contact_states`, not a filter."
},
"contact_states_repeated": {
"allOf": [
{
"$ref": "#/components/schemas/DialerContactStateCounts"
}
],
"description": "Per-state count of contacts already attempted at least once — a breakout of `contact_states`, not a filter. Subtract it from `contact_states` for the never-attempted counts."
},
"pending_by_category": {
"$ref": "#/components/schemas/DialerPendingByCategoryCounts"
},
"total_contacts_at_range_end": {
"type": "integer",
"description": "Contacts that were members of the campaign at the window's end (on an all-time read: the full current membership).",
"example": 165
},
"open_assignments": {
"type": "integer",
"description": "Contacts currently held by agents. Always a current-state count, never narrowed by the window.",
"example": 3
},
"assigned_by_state": {
"type": "object",
"description": "open_assignments split by the held contact's current state. pending is the slice to subtract from a waiting reading (contact_states_dialable.pending), scheduled the slice to subtract from a scheduled reading — a held contact keeps its state while an agent works it. A breakout of open_assignments, not a filter. Always a current-state count, never narrowed by the window.",
"properties": {
"pending": {
"type": "integer",
"example": 2
},
"scheduled": {
"type": "integer",
"example": 1
}
}
},
"assigned_pending_by_category": {
"allOf": [
{
"$ref": "#/components/schemas/DialerPendingByCategoryCounts"
}
],
"description": "Waterfall-category slices of the PENDING held contacts only — which categories the contacts agents currently hold were taken from. Scoped like pending_by_category; sums to assigned_by_state.pending. Always a current-state count, never narrowed by the window."
},
"total_dialed": {
"type": "integer",
"description": "Calls placed.",
"example": 240
},
"total_answered": {
"type": "integer",
"description": "Calls answered.",
"example": 150
},
"answer_rate": {
"type": "number",
"description": "`total_answered` / `total_dialed`, in the range 0–1.",
"example": 0.625
},
"num_rescheduled": {
"type": "integer",
"description": "Calls dispositioned as rescheduled.",
"example": 12
},
"num_dropped": {
"type": "integer",
"description": "Calls dropped before an agent could take them.",
"example": 3
},
"num_dispositioned": {
"type": "integer",
"description": "Calls that received a disposition.",
"example": 96
},
"num_conversions": {
"type": "integer",
"description": "Calls dispositioned with a positive outcome.",
"example": 30
},
"conversion_rate": {
"type": "number",
"description": "`num_conversions` / `num_dispositioned`, in the range 0–1.",
"example": 0.3125
},
"num_reached_human": {
"type": "integer",
"description": "Attempts that reached a human.",
"example": 130
},
"num_reached_voicemail": {
"type": "integer",
"description": "Attempts that reached a voicemail.",
"example": 15
},
"num_reached_other_machine": {
"type": "integer",
"description": "Attempts that reached another machine (IVR, queue, tone).",
"example": 5
},
"attempt_no_split": {
"$ref": "#/components/schemas/DialerAttemptNoSplit"
},
"distinct_called_contacts": {
"type": "integer",
"nullable": true,
"description": "Distinct contacts dialed inside the window. Ranged-only — null on every all-time response.",
"example": null
},
"distinct_answered_contacts": {
"type": "integer",
"description": "Distinct contacts that answered. Never null; an all-time read counts contacts whose first answer is on record, a ranged read counts distinct answered contacts inside the window.",
"example": 112
},
"call_durations": {
"$ref": "#/components/schemas/DialerCallDurationTotals"
},
"disposition_breakdown": {
"type": "array",
"description": "Per-tag disposition counts.",
"items": {
"$ref": "#/components/schemas/DialerDispositionBreakdownEntry"
}
},
"updated_at": {
"type": "string",
"description": "Freshness of the all-time projection (ISO 8601, UTC). Null on every ranged response, and null on an all-time response whose projection has not materialized yet.",
"format": "date-time",
"nullable": true,
"example": "2026-08-04T11:40:00.000Z"
},
"range": {
"$ref": "#/components/schemas/DialerStatisticsRange"
}
}
},
"DialerContactStateCounts": {
"type": "object",
"description": "Contact counts per campaign-membership state.",
"properties": {
"pending": {
"type": "integer",
"description": "Not yet attempted or awaiting a retry.",
"example": 120
},
"scheduled": {
"type": "integer",
"description": "Has a scheduled callback.",
"example": 4
},
"completed": {
"type": "integer",
"description": "Reached a final disposition.",
"example": 38
},
"dnc": {
"type": "integer",
"description": "Marked do-not-call.",
"example": 2
},
"exhausted": {
"type": "integer",
"description": "Ran out of retry attempts.",
"example": 1
},
"excluded": {
"type": "integer",
"description": "Excluded from the campaign by configuration.",
"example": 0
}
}
},
"DialerCreateCampaignRequest": {
"type": "object",
"description": "Body of the campaign create call. Only `name` and `mode` are required; every policy bundle falls back to the service default when omitted.",
"required": [
"name",
"mode"
],
"properties": {
"name": {
"type": "string",
"description": "Human-readable campaign name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Q3 renewals"
},
"mode": {
"type": "string",
"description": "Dialing mode. `sequential` dials one number at a time per agent; `parallel` dials several.",
"enum": [
"sequential",
"parallel"
],
"example": "sequential"
},
"calling_policy": {
"$ref": "#/components/schemas/DialerCallingPolicy"
},
"queue_policy": {
"$ref": "#/components/schemas/DialerQueuePolicy"
},
"retry_policy": {
"$ref": "#/components/schemas/DialerRetryPolicy"
},
"schedule_policy": {
"$ref": "#/components/schemas/DialerSchedulePolicy"
},
"ttl_policy": {
"$ref": "#/components/schemas/DialerTtlPolicy"
},
"waterfall_order": {
"type": "array",
"description": "Ordered, duplicate-free subset of the waterfall categories. Contacts are served tier by tier in this order.",
"items": {
"type": "string",
"enum": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"example": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"agent_permissions": {
"$ref": "#/components/schemas/DialerAgentPermissions"
},
"call_script_id": {
"type": "integer",
"description": "Call script to link to the campaign; omit it or send `null` to create the campaign without a linked call script. Sent as an integer in requests; responses return the id as a string.",
"minimum": 1,
"nullable": true,
"example": 310
},
"survey_id": {
"type": "integer",
"description": "Survey to link to the campaign; omit it or send `null` to create the campaign without a linked survey. Sent as an integer in requests; responses return the id as a string.",
"minimum": 1,
"nullable": true,
"example": 44
}
}
},
"DialerCreateExportRequest": {
"type": "object",
"description": "Body of the export enqueue call.",
"required": [
"type",
"format"
],
"properties": {
"type": {
"type": "string",
"description": "What to export. `call_history` exports the campaign's dial log; `survey_responses` exports answers collected by the campaign's survey.",
"enum": [
"call_history",
"survey_responses"
],
"example": "call_history"
},
"format": {
"type": "string",
"description": "Serialisation format of the generated file.",
"enum": [
"csv",
"xlsx"
],
"example": "csv"
},
"filters": {
"$ref": "#/components/schemas/DialerExportFilters"
}
}
},
"DialerCreateScriptRequest": {
"type": "object",
"required": [
"name",
"body"
],
"description": "Body of the create-script call. Unknown fields are silently dropped.",
"properties": {
"name": {
"type": "string",
"description": "Display name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Summer promo pitch"
},
"body": {
"type": "string",
"description": "Script content; supports `{{merge}}` fields.",
"minLength": 1,
"example": "Hi {{first_name}}…"
}
}
},
"DialerCreateSurveyRequest": {
"type": "object",
"required": [
"name"
],
"description": "Body of the create-survey call.",
"properties": {
"name": {
"type": "string",
"description": "Display name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Post-call qualification"
},
"questions": {
"type": "array",
"description": "Initial question set. Omit to create an empty survey.",
"items": {
"$ref": "#/components/schemas/DialerSurveyQuestionInput"
}
}
}
},
"DialerCursorMeta": {
"type": "object",
"description": "Cursor-pagination metadata.",
"properties": {
"nextCursor": {
"type": "string",
"description": "Opaque cursor to pass as `cursor` to fetch the next page; null when this is the last page.",
"nullable": true,
"example": "eyJpZCI6IjQyIn0"
}
}
},
"DialerDispositionBreakdownEntry": {
"type": "object",
"description": "How often one disposition tag was recorded. Labels are null when the tag cannot be resolved.",
"properties": {
"tag_id": {
"type": "string",
"description": "Call-tag ID.",
"example": "100"
},
"count": {
"type": "integer",
"description": "Times this disposition was recorded.",
"example": 17
},
"name": {
"type": "string",
"description": "Tag display name; null when unresolvable.",
"nullable": true,
"example": "Interested"
},
"color": {
"type": "string",
"description": "Tag display colour; null when unresolvable.",
"nullable": true,
"example": "#00AA55"
},
"outcome": {
"type": "string",
"description": "Tag outcome classification; null when unresolvable.",
"nullable": true,
"example": "successful_positive"
}
}
},
"DialerDispositionButton": {
"type": "object",
"description": "One disposition button. `name`, `outcome` and `color` are resolved from the referenced call tag at read time. A button whose tag has been deleted or archived is not returned; all three are null only while the call tags cannot be read.",
"properties": {
"id": {
"type": "string",
"description": "Button ID.",
"example": "15"
},
"tag_id": {
"type": "string",
"description": "Referenced call-tag ID.",
"example": "101"
},
"outcome_kind": {
"type": "string",
"description": "How the dialer treats a call dispositioned with this button.",
"enum": [
"successful_positive",
"successful_negative",
"rescheduled",
"unsuccessful_call_again",
"unsuccessful_do_not_call"
],
"example": "rescheduled"
},
"color": {
"type": "string",
"description": "Colour of the referenced tag; null when the tag has no colour or the call tags cannot be read.",
"nullable": true,
"example": "#FFAA00"
},
"display_order": {
"type": "integer",
"description": "Ascending display position.",
"example": 0
},
"name": {
"type": "string",
"description": "Display name of the referenced tag; null only while the call tags cannot be read.",
"nullable": true,
"example": "Call back later"
},
"outcome": {
"type": "string",
"description": "Outcome of the referenced tag; null only while the call tags cannot be read.",
"nullable": true,
"example": "rescheduled"
}
}
},
"DialerDispositionButtonInput": {
"type": "object",
"description": "One disposition button in the replace-all body. The button's display name and colour are not set here — they come from the referenced tag.",
"required": [
"tag_id",
"outcome_kind"
],
"properties": {
"tag_id": {
"type": "integer",
"description": "Referenced call-tag id. List the available tags with the disposition-tags call. Sent as an integer in requests; responses return the id as a string.",
"minimum": 1,
"example": 100
},
"outcome_kind": {
"type": "string",
"description": "How the dialer treats a call dispositioned with this button.",
"enum": [
"successful_positive",
"successful_negative",
"rescheduled",
"unsuccessful_call_again",
"unsuccessful_do_not_call"
],
"example": "successful_positive"
},
"display_order": {
"type": "integer",
"description": "Ascending display position; defaults to 0.",
"minimum": 0,
"example": 1
},
"color": {
"not": {},
"description": "Not supported — any supplied value (including `null`) is rejected with 400. The button's colour always comes from the referenced tag. Other unknown keys are silently ignored."
}
}
},
"DialerDispositionTag": {
"type": "object",
"description": "One call tag usable as a campaign disposition button.",
"properties": {
"id": {
"type": "string",
"description": "Tag ID — pass this as `tag_id` when configuring disposition buttons.",
"example": "100"
},
"name": {
"type": "string",
"description": "Tag display name.",
"example": "Interested"
},
"color": {
"type": "string",
"description": "Tag display colour; null when unset.",
"nullable": true,
"example": "#00AA55"
},
"outcome": {
"type": "string",
"description": "Outcome classification carried by the tag.",
"example": "successful_positive"
}
}
},
"DialerDispositionTagList": {
"type": "object",
"description": "The company's disposition-tag catalogue. It uses the same envelope as the campaign list, but the catalogue is always returned whole, so `meta.nextCursor` is always null.",
"properties": {
"data": {
"type": "array",
"description": "The company's full disposition-tag catalogue.",
"items": {
"$ref": "#/components/schemas/DialerDispositionTag"
}
},
"meta": {
"type": "object",
"description": "Cursor envelope; the cursor is always null because the catalogue is unpaged.",
"properties": {
"nextCursor": {
"type": "string",
"description": "Always null — the catalogue is returned whole.",
"nullable": true,
"example": null
}
}
}
}
},
"DialerExportDownload": {
"type": "object",
"description": "A pre-signed download link for a completed export. Minted fresh on every call; valid at least 60 minutes.",
"properties": {
"url": {
"type": "string",
"description": "Pre-signed S3 URL of the export file. Fetch it without credentials — the signature is the authorization.",
"example": "https://ct-dialer-exports.s3.eu-west-1.amazonaws.com/exports/700001/0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f/call_history-campaign-42.csv?X-Amz-Signature=…"
},
"expiresAt": {
"type": "string",
"description": "Instant the URL stops working (ISO 8601, UTC). Call the endpoint again for a fresh link.",
"format": "date-time",
"example": "2026-08-04T09:05:00.000Z"
}
}
},
"DialerExportFilters": {
"type": "object",
"description": "Optional narrowing filters. Omitting the whole object exports everything for the campaign. Supplying only one of `dateFrom` / `dateTo` is valid — a missing end resolves to the time the job runs, a missing start to the campaign's creation.",
"properties": {
"contactId": {
"type": "integer",
"description": "Restrict the export to one contact. Must be a positive id — `0` or a negative value is rejected with 400 (`filters.contactId must not be less than 1` in `subErrors`).",
"minimum": 1,
"example": 900123
},
"userId": {
"type": "integer",
"description": "Restrict the export to one agent (user). Must be a positive id — `0` or a negative value is rejected with 400 (`filters.userId must not be less than 1` in `subErrors`).",
"minimum": 1,
"example": 800001
},
"dateFrom": {
"type": "string",
"description": "Only rows at or after this instant, as an RFC 3339 date-time. The service validates strict ISO 8601, so a calendar-impossible value such as `2026-02-31T00:00:00.000Z` is rejected with 400 rather than rolled forward.",
"format": "date-time",
"example": "2026-07-01T00:00:00.000Z"
},
"dateTo": {
"type": "string",
"description": "Only rows at or before this instant, as an RFC 3339 date-time. Validated exactly like `dateFrom`.",
"format": "date-time",
"example": "2026-08-01T00:00:00.000Z"
}
}
},
"DialerExportJob": {
"type": "object",
"description": "Handle for a queued export job. Poll it with the export-status call.",
"properties": {
"jobId": {
"type": "string",
"description": "Export job ID.",
"format": "uuid",
"example": "0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f"
},
"status": {
"type": "string",
"description": "Job status at the moment of enqueue.",
"enum": [
"queued",
"running",
"completed",
"failed"
],
"example": "queued"
}
}
},
"DialerExportJobStatus": {
"type": "object",
"description": "State of an export job. Once it reports `completed`, fetch the file through the export-download call — a pre-signed link is also emailed to the requester.",
"properties": {
"jobId": {
"type": "string",
"description": "Export job ID.",
"format": "uuid",
"example": "0197fbd1-6d0a-7e58-8f6f-1a2b3c4d5e6f"
},
"status": {
"type": "string",
"description": "Job status. `queued` → `running` → `completed` | `failed`.",
"enum": [
"queued",
"running",
"completed",
"failed"
],
"example": "running"
},
"progress": {
"$ref": "#/components/schemas/DialerExportProgress"
},
"createdAt": {
"type": "string",
"description": "When the job was enqueued (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T08:00:00.000Z"
},
"completedAt": {
"type": "string",
"description": "When the job finished; null while it is still queued or running.",
"format": "date-time",
"nullable": true,
"example": "2026-08-04T08:05:00.000Z"
}
}
},
"DialerExportProgress": {
"type": "object",
"description": "Coarse progress hint. Both counters stay at 0 until the runner picks the job up.",
"properties": {
"currentPartition": {
"type": "integer",
"description": "Partition the runner is currently streaming.",
"example": 3
},
"totalPartitions": {
"type": "integer",
"description": "Partitions the job has to stream in total.",
"example": 8
}
}
},
"DialerPatchCampaignRequest": {
"type": "object",
"description": "Body of the campaign update call. Every key is optional — an omitted key is left unchanged. `status` drives the lifecycle transition; `deleted` is never a valid target here (use the delete call).",
"properties": {
"name": {
"type": "string",
"description": "Human-readable campaign name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Q3 renewals — EMEA"
},
"mode": {
"type": "string",
"description": "Dialing mode.",
"enum": [
"sequential",
"parallel"
],
"example": "parallel"
},
"status": {
"type": "string",
"description": "Target lifecycle status. Legal transitions: `initializing` → `active` | `archived`; `active` ↔ `inactive`; `active` → `archived`; `inactive` → `archived`; `archived` → `inactive`. A patch that leaves the status unchanged is a no-op. `deleted` passes schema validation but is always rejected with 422 — only the delete call sets it.",
"enum": [
"initializing",
"active",
"inactive",
"archived",
"deleted"
],
"example": "active"
},
"calling_policy": {
"$ref": "#/components/schemas/DialerCallingPolicy"
},
"queue_policy": {
"$ref": "#/components/schemas/DialerQueuePolicy"
},
"retry_policy": {
"$ref": "#/components/schemas/DialerRetryPolicy"
},
"schedule_policy": {
"$ref": "#/components/schemas/DialerSchedulePolicy"
},
"ttl_policy": {
"$ref": "#/components/schemas/DialerTtlPolicy"
},
"waterfall_order": {
"type": "array",
"description": "Ordered, duplicate-free subset of the waterfall categories. Contacts are served tier by tier in this order.",
"items": {
"type": "string",
"enum": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"example": [
"favorite",
"rescheduled",
"retry",
"fresh"
]
},
"agent_permissions": {
"$ref": "#/components/schemas/DialerAgentPermissions"
},
"call_script_id": {
"type": "integer",
"description": "Call script to link to the campaign; `null` clears the link, an omitted key leaves it unchanged. Sent as an integer in requests; responses return the id as a string.",
"minimum": 1,
"nullable": true,
"example": 310
},
"survey_id": {
"type": "integer",
"description": "Survey to link to the campaign; `null` clears the link, an omitted key leaves it unchanged. Sent as an integer in requests; responses return the id as a string.",
"minimum": 1,
"nullable": true,
"example": 44
}
}
},
"DialerPatchScriptRequest": {
"type": "object",
"description": "Body of the patch-script call. Every field is optional; omitted fields stay untouched.",
"properties": {
"name": {
"type": "string",
"description": "New display name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Summer promo pitch v2"
},
"body": {
"type": "string",
"description": "New script content.",
"minLength": 1,
"example": "Hi {{first_name}}…"
},
"is_archived": {
"type": "boolean",
"description": "`true` archives the script, `false` restores it.",
"example": false
}
}
},
"DialerPatchSurveyRequest": {
"type": "object",
"description": "Body of the patch-survey call. Only these two fields are patchable — questions change through the replace-questions call.",
"properties": {
"name": {
"type": "string",
"description": "New display name. Leading and trailing whitespace is trimmed before validation, so a blank or whitespace-only name is rejected with 400 (`name should not be empty` in `subErrors`).",
"minLength": 1,
"pattern": "\\S",
"maxLength": 255,
"example": "Post-call qualification v2"
},
"is_archived": {
"type": "boolean",
"description": "`true` archives the survey (its soft delete), `false` restores it.",
"example": true
}
}
},
"DialerPeekContact": {
"type": "object",
"description": "One entry of the peek answer — a non-binding snapshot of the allocator's next picks.",
"properties": {
"campaign_contact_id": {
"type": "string",
"description": "Membership row ID.",
"example": "5100"
},
"contact_id": {
"type": "string",
"description": "The contact's ID in Contacts.",
"example": "88213"
},
"category": {
"type": "string",
"description": "Waterfall category the pick came from.",
"example": "fresh"
},
"phone_numbers": {
"type": "array",
"items": {
"type": "string"
},
"description": "The contact's numbers in dialing order (index 0 is primary).",
"example": [
"+421900123456",
"+421255512345"
]
},
"display_name": {
"type": "string",
"nullable": true,
"description": "Contact display name.",
"example": "Jane Kowalski"
},
"timezone": {
"type": "string",
"nullable": true,
"description": "Contact's IANA timezone.",
"example": "Europe/Bratislava"
},
"callback_notes": {
"type": "string",
"nullable": true,
"description": "Note attached to a scheduled callback; null otherwise.",
"example": null
}
}
},
"DialerPendingByCategoryCounts": {
"type": "object",
"description": "Breakout of `contact_states.pending` by waterfall category — the four sum exactly to the pending total. Includes non-dialable pending contacts, so it is not an available-to-dial count.",
"properties": {
"favorite": {
"type": "integer",
"description": "Pending contacts marked favorite.",
"example": 6
},
"rescheduled": {
"type": "integer",
"description": "Pending contacts whose last outcome rescheduled them.",
"example": 12
},
"retry": {
"type": "integer",
"description": "Pending contacts waiting on an automatic retry.",
"example": 22
},
"fresh": {
"type": "integer",
"description": "Pending contacts never attempted.",
"example": 80
}
}
},
"DialerQueuePolicy": {
"type": "object",
"description": "Allocation-batch and dynamic queue-sizing bundle. Every knob is optional.",
"properties": {
"lock_size": {
"type": "integer",
"description": "How many contacts an agent may hold allocated at once.",
"minimum": 0,
"example": 5
},
"pinned_callback_hold_ms": {
"type": "integer",
"description": "Hold window (ms) past an agent-pinned callback's due time after which any agent may serve it; 0 releases the pin as soon as the callback is overdue.",
"minimum": 0,
"example": 300000
},
"refill_amount": {
"type": "integer",
"description": "How many contacts are pulled per queue refill.",
"minimum": 0,
"example": 3
},
"sizing_mode": {
"type": "string",
"description": "Queue-sizing strategy (static or agent-count driven).",
"example": "dynamic"
},
"min": {
"type": "integer",
"description": "Lower bound on the dynamically sized queue.",
"minimum": 0,
"example": 10
},
"max": {
"type": "integer",
"description": "Upper bound on the dynamically sized queue.",
"minimum": 0,
"example": 200
},
"multiplier": {
"type": "number",
"description": "Queue size per available agent when sizing dynamically.",
"minimum": 0,
"example": 2.5
},
"threshold": {
"type": "integer",
"description": "Remaining-contact count that triggers a refill.",
"minimum": 0,
"example": 5
},
"manual_refill": {
"type": "boolean",
"description": "When true the queue is only refilled on an explicit agent action.",
"example": false
}
}
},
"DialerReplaceAssociationsRequest": {
"type": "object",
"description": "Replace-all body for a campaign's associations. Each array is optional and defaults to empty, so an omitted kind clears that kind. Every entry may be given either as an object or as a bare id. Naming the same `(kind, ref_id)` twice in one body is rejected as a conflict.",
"properties": {
"target_tag": {
"type": "array",
"description": "Contact tags that define the campaign's membership. Naming a CRM-connection-owned tag re-ranks it in place; adding or removing such a tag is owned by the CRM connection, not this call.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/DialerAssociationEntry"
},
{
"type": "integer",
"description": "Shorthand for `{ \"ref_id\": }`.",
"minimum": 1
}
]
}
},
"queue_group": {
"type": "array",
"description": "Queue groups the campaign draws its agents from.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/DialerAssociationEntry"
},
{
"type": "integer",
"description": "Shorthand for `{ \"ref_id\": }`.",
"minimum": 1
}
]
}
},
"agent": {
"type": "array",
"description": "Agents (users) assigned to the campaign.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/DialerAssociationEntry"
},
{
"type": "integer",
"description": "Shorthand for `{ \"ref_id\": }`.",
"minimum": 1
}
]
}
}
}
},
"DialerReplaceDispositionButtonsRequest": {
"type": "object",
"description": "Replace-all body for a campaign's disposition buttons. A `color` key on a button is rejected with 400 — presentation always comes from the referenced tag.",
"required": [
"buttons"
],
"properties": {
"buttons": {
"type": "array",
"description": "The complete button set for the campaign. An empty array clears every button.",
"items": {
"$ref": "#/components/schemas/DialerDispositionButtonInput"
}
}
}
},
"DialerReplaceSurveyQuestionsRequest": {
"type": "object",
"required": [
"questions"
],
"description": "Body of the replace-questions call — the desired end state of the survey's question set. An empty array clears the survey.",
"properties": {
"questions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerSurveyQuestionInput"
}
}
}
},
"DialerRetryPolicy": {
"type": "object",
"description": "Re-dial rules bundle. Every knob is optional.",
"properties": {
"max_attempts": {
"type": "integer",
"description": "Maximum dial attempts per contact before it is exhausted.",
"minimum": 0,
"example": 3
},
"interval_hours": {
"type": "number",
"description": "Hours to wait between attempts; 0 retries immediately.",
"minimum": 0,
"example": 24
},
"excluded_dispositions": {
"type": "array",
"description": "Disposition outcomes that stop further retries.",
"items": {
"type": "string"
},
"example": [
"unsuccessful_do_not_call"
]
},
"dnc_tag_ids": {
"type": "array",
"description": "Contact-tag ids that mark a contact as do-not-call.",
"items": {
"type": "integer",
"minimum": 0
},
"example": [
55
]
}
}
},
"DialerSchedulePolicy": {
"type": "object",
"description": "Campaign start-window bundle. Every knob is optional.",
"properties": {
"start_date": {
"type": "string",
"description": "Company-local calendar date the campaign may start dialing. Must be a real calendar date in `YYYY-MM-DD` — any other form, or a date that does not exist such as `2026-02-30`, is rejected with 400 (`schedule_policy.start_date must be a real calendar date in YYYY-MM-DD` in `subErrors`).",
"format": "date",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
"example": "2026-08-10"
},
"start_time": {
"type": "string",
"description": "Company-local wall-clock time on `start_date`. Must be a valid `HH:MM` or `HH:MM:SS` time, components zero-padded and in range — any other form, or an impossible time such as `25:00`, is rejected with 400 (`schedule_policy.start_time must be a valid HH:MM or HH:MM:SS time` in `subErrors`). Omit it for midnight.",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$",
"example": "09:00"
},
"timezone_rule_enabled": {
"type": "boolean",
"description": "When true the start window is applied in the contact's own timezone.",
"example": true
}
}
},
"DialerScript": {
"type": "object",
"description": "A call script agents read while dialing. Ids are BIGINTs serialized as strings.",
"properties": {
"id": {
"type": "string",
"description": "Script ID.",
"example": "17"
},
"name": {
"type": "string",
"description": "Display name.",
"maxLength": 255,
"example": "Summer promo pitch"
},
"body": {
"type": "string",
"description": "Script content; supports `{{merge}}` fields resolved by the agent's phone at call time.",
"example": "Hi {{first_name}}, this is {{agent_name}} from CloudTalk…"
},
"is_archived": {
"type": "boolean",
"description": "Whether the script is archived (soft-deleted).",
"example": false
},
"created_at": {
"type": "string",
"description": "When the script was created (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-07-01T09:00:00.000Z"
},
"updated_at": {
"type": "string",
"description": "When the script last changed (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T11:40:00.000Z"
}
}
},
"DialerScriptList": {
"type": "object",
"description": "One cursor page of call scripts.",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerScript"
}
},
"meta": {
"$ref": "#/components/schemas/DialerCursorMeta"
}
}
},
"DialerStatisticsRange": {
"type": "object",
"nullable": true,
"description": "The resolved statistics window — the field that tells you which basis the counters are on: null on an all-time response, set on a ranged one. `to` is exclusive; a date-only `dateTo` is echoed here already advanced to the following UTC midnight, so the echo may not equal the request literally.",
"properties": {
"from": {
"type": "string",
"description": "Inclusive lower bound (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-07-01T00:00:00.000Z"
},
"to": {
"type": "string",
"description": "Exclusive upper bound (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-01T00:00:00.000Z"
}
}
},
"DialerSurveyDefinition": {
"type": "object",
"description": "A survey with its full ordered question set. Returned by every single-survey call; the list serves summaries instead.",
"properties": {
"id": {
"type": "string",
"description": "Survey ID.",
"example": "8"
},
"name": {
"type": "string",
"description": "Display name.",
"maxLength": 255,
"example": "Post-call qualification"
},
"is_archived": {
"type": "boolean",
"description": "Whether the survey is archived (soft-deleted). Archiving preserves collected answers.",
"example": false
},
"questions": {
"type": "array",
"description": "The survey's questions, ordered by `display_order`.",
"items": {
"$ref": "#/components/schemas/DialerSurveyQuestion"
}
},
"created_at": {
"type": "string",
"description": "When the survey was created (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-07-01T09:00:00.000Z"
},
"updated_at": {
"type": "string",
"description": "When the survey last changed (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T11:40:00.000Z"
}
}
},
"DialerSurveyList": {
"type": "object",
"description": "One cursor page of survey summaries.",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DialerSurveySummary"
}
},
"meta": {
"$ref": "#/components/schemas/DialerCursorMeta"
}
}
},
"DialerSurveyOption": {
"type": "object",
"description": "One choice of a `radio`, `checkbox` or `select` question. Ids are server-generated.",
"properties": {
"id": {
"type": "string",
"description": "Option ID.",
"example": "901"
},
"label": {
"type": "string",
"description": "Choice label shown to the agent.",
"maxLength": 500,
"example": "Yes"
},
"display_order": {
"type": "integer",
"description": "Zero-based position among the question's options.",
"minimum": 0,
"example": 0
}
}
},
"DialerSurveyOptionInput": {
"type": "object",
"required": [
"label"
],
"description": "An option as sent in create/replace requests — no id.",
"properties": {
"label": {
"type": "string",
"description": "Choice label.",
"minLength": 1,
"maxLength": 500,
"example": "Yes"
},
"display_order": {
"type": "integer",
"description": "Zero-based position. Defaults to `0`.",
"minimum": 0,
"default": 0
}
}
},
"DialerSurveyQuestion": {
"type": "object",
"description": "One question of a survey. Ids are server-generated and change on every question replace.",
"properties": {
"id": {
"type": "string",
"description": "Question ID.",
"example": "310"
},
"label": {
"type": "string",
"description": "Question text shown to the agent.",
"maxLength": 1000,
"example": "Was the customer interested?"
},
"type": {
"type": "string",
"description": "Input widget the agent answers with.",
"enum": [
"text",
"textarea",
"radio",
"checkbox",
"select"
],
"example": "radio"
},
"is_required": {
"type": "boolean",
"description": "Whether the agent must answer before submitting.",
"example": true
},
"display_order": {
"type": "integer",
"description": "Zero-based position among the survey's questions.",
"minimum": 0,
"example": 0
},
"options": {
"type": "array",
"description": "Choices for choice-type questions. Accepted and stored for any question type.",
"items": {
"$ref": "#/components/schemas/DialerSurveyOption"
}
}
}
},
"DialerSurveyQuestionInput": {
"type": "object",
"required": [
"label",
"type"
],
"description": "A question as sent in create/replace requests. Never carries ids — they are server-generated.",
"properties": {
"label": {
"type": "string",
"description": "Question text.",
"minLength": 1,
"maxLength": 1000,
"example": "Was the customer interested?"
},
"type": {
"type": "string",
"description": "Input widget.",
"enum": [
"text",
"textarea",
"radio",
"checkbox",
"select"
],
"example": "radio"
},
"is_required": {
"type": "boolean",
"description": "Whether the agent must answer. Defaults to `false`.",
"default": false
},
"display_order": {
"type": "integer",
"description": "Zero-based position. Defaults to `0`.",
"minimum": 0,
"default": 0
},
"options": {
"type": "array",
"description": "Choices for choice-type questions.",
"items": {
"$ref": "#/components/schemas/DialerSurveyOptionInput"
}
}
}
},
"DialerSurveySummary": {
"type": "object",
"description": "List item of the surveys collection — a summary carrying `question_count` instead of the questions themselves.",
"properties": {
"id": {
"type": "string",
"description": "Survey ID.",
"example": "8"
},
"name": {
"type": "string",
"description": "Display name.",
"example": "Post-call qualification"
},
"is_archived": {
"type": "boolean",
"description": "Whether the survey is archived.",
"example": false
},
"question_count": {
"type": "integer",
"description": "Number of questions the survey currently has.",
"example": 1
},
"created_at": {
"type": "string",
"description": "When the survey was created (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-07-01T09:00:00.000Z"
},
"updated_at": {
"type": "string",
"description": "When the survey last changed (ISO 8601, UTC).",
"format": "date-time",
"example": "2026-08-04T11:40:00.000Z"
}
}
},
"DialerTargetTagAssociation": {
"type": "object",
"description": "One target-tag association, with its serving rank and provenance.",
"properties": {
"ref_id": {
"type": "integer",
"description": "Referenced contact-tag id.",
"example": 10
},
"priority": {
"type": "integer",
"description": "Serving rank — the highest priority is served first.",
"example": 10
},
"label": {
"type": "string",
"description": "Human-readable level name; null when unset.",
"nullable": true,
"example": "Hot"
},
"origin": {
"type": "string",
"description": "Read-only provenance. `manual` rows were added through this endpoint; `crm_connection` rows are kept in sync by a campaign CRM connection and can only be re-ranked here, not added or removed.",
"enum": [
"manual",
"crm_connection"
],
"example": "manual"
}
}
},
"DialerTtlPolicy": {
"type": "object",
"description": "Contact-eligibility expiry bundle — drives how long an allocated contact stays held. Every knob is optional.",
"properties": {
"mode": {
"type": "string",
"description": "How the expiry window is derived.",
"example": "campaign"
},
"hours": {
"type": "integer",
"description": "Expiry window in hours while the campaign is running.",
"minimum": 0,
"example": 72
},
"paused_hours": {
"type": "integer",
"description": "Expiry window in hours while the campaign is paused.",
"minimum": 0,
"example": 168
}
}
},
"DialerError": {
"type": "object",
"description": "Error envelope returned by every Dialer API endpoint. Note it differs from the legacy API's error format.",
"properties": {
"statusCode": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"error": {
"type": "string",
"description": "HTTP error name"
},
"correlationId": {
"type": "string",
"description": "Request correlation ID — include it when contacting support",
"example": "YevPQs"
},
"subErrors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Field-level validation messages, present on validation failures",
"example": [
"incorrect email"
]
}
},
"required": [
"statusCode",
"message",
"error",
"correlationId"
]
},
"CollectionVoiceAgentListAttributes": {
"additionalProperties": false,
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/ResourceVoiceAgentListAttributes"
},
"nullable": true,
"type": "array"
},
"pagination": {
"$ref": "#/components/schemas/PublicPagination"
},
"requestId": {
"type": "string"
}
},
"required": [
"data",
"pagination",
"requestId"
],
"type": "object"
},
"PublicPagination": {
"additionalProperties": false,
"properties": {
"limit": {
"format": "int64",
"type": "integer"
},
"next": {
"nullable": true,
"type": "string"
}
},
"required": [
"limit",
"next"
],
"type": "object"
},
"PublicErrorBody": {
"additionalProperties": false,
"properties": {
"error": {
"$ref": "#/components/schemas/PublicErrorObject"
},
"requestId": {
"type": "string"
}
},
"required": [
"error",
"requestId"
],
"type": "object"
},
"PublicErrorDetail": {
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"target": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"PublicErrorObject": {
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"details": {
"items": {
"$ref": "#/components/schemas/PublicErrorDetail"
},
"nullable": true,
"type": "array"
},
"message": {
"type": "string"
},
"target": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"ResourceVoiceAgentAttributes": {
"additionalProperties": false,
"properties": {
"attributes": {
"$ref": "#/components/schemas/VoiceAgentAttributes"
},
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"type",
"attributes"
],
"type": "object"
},
"ResourceVoiceAgentListAttributes": {
"additionalProperties": false,
"properties": {
"attributes": {
"$ref": "#/components/schemas/VoiceAgentListAttributes"
},
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"type",
"attributes"
],
"type": "object"
},
"SingleVoiceAgentAttributes": {
"additionalProperties": false,
"properties": {
"data": {
"$ref": "#/components/schemas/ResourceVoiceAgentAttributes"
},
"requestId": {
"type": "string"
}
},
"required": [
"data",
"requestId"
],
"type": "object"
},
"VoiceAgentAnswerQuestionsSkill": {
"additionalProperties": false,
"nullable": true,
"properties": {
"action": {
"description": "What to do when the agent cannot answer",
"enum": [
"admitUncertainty",
"offerAlternative",
"transferToHuman"
],
"type": "string"
},
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"transferConfig": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentTransferTarget"
}
],
"description": "Destination used when action is transferToHuman"
}
},
"required": [
"isEnabled",
"action"
],
"type": "object"
},
"VoiceAgentAttributes": {
"additionalProperties": false,
"properties": {
"agentName": {
"description": "Name of the agent",
"example": "Receptionist",
"maxLength": 255,
"type": "string"
},
"createdAt": {
"description": "When the agent was created",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"defaultOutboundNumberId": {
"description": "Outbound caller id; null selects Automatic Outbound and then requires failoverOutboundNumberId",
"example": 73836,
"format": "int64",
"nullable": true,
"type": "integer"
},
"dialTimeoutSeconds": {
"description": "Ring timeout; null uses the provider default",
"format": "int64",
"maximum": 120,
"minimum": 5,
"nullable": true,
"type": "integer"
},
"direction": {
"description": "Call direction the agent serves",
"enum": [
"inbound",
"outbound"
],
"example": "inbound",
"type": "string"
},
"elevenLabsSettings": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentElevenLabsSettings"
}
],
"description": "Provider turn-taking and audio tuning"
},
"failoverOutboundNumberId": {
"description": "Number used when Automatic Outbound cannot pick one; required with, and only allowed with, Automatic Outbound (defaultOutboundNumberId null)",
"example": 73836,
"format": "int64",
"nullable": true,
"type": "integer"
},
"goalPrompt": {
"description": "What the agent is supposed to achieve",
"maxLength": 20000,
"type": "string"
},
"greeting": {
"description": "Opening line; required for inbound agents",
"maxLength": 2000,
"type": "string"
},
"guardrails": {
"description": "Topics the agent must avoid",
"items": {
"$ref": "#/components/schemas/VoiceAgentGuardrail"
},
"maxItems": 50,
"nullable": true,
"type": "array"
},
"isAgentSpeakingFirst": {
"description": "Whether the agent speaks first; omitted means true for inbound and false for outbound",
"nullable": true,
"type": "boolean"
},
"knowledgeBaseIds": {
"description": "Knowledge bases the agent answers from",
"items": {
"type": "string"
},
"maxItems": 100,
"nullable": true,
"type": "array"
},
"language": {
"description": "Primary language code; rejected with 422 and the detail code LANGUAGE_NOT_SUPPORTED when no provider serves it or the agent's provider (the sent one, or the stored one on replace) does not",
"example": "en",
"maxLength": 16,
"type": "string"
},
"llm": {
"description": "Model the agent runs on, by canonical id; null on a read when the agent has none set. Omitted on create means the optimized one; omitted on replace keeps the stored value. A model the provider does not offer is rejected with 422 and the detail code LLM_OVERRIDE_NOT_AVAILABLE_FOR_PROVIDER at target llm",
"enum": [
"openai - gpt-4o-mini",
"openai - gpt-4o",
"openai - gpt-4.1",
"openai - gpt-4.1-mini",
"openai - gpt-4.1-nano",
"openai - gpt-5",
"openai - gpt-5-mini",
"openai - gpt-5-nano",
"openai - gpt-5.1",
"openai - gpt-5.2",
"openai - gpt-5.4",
"openai - gpt-5.4-mini",
"openai - gpt-5.4-nano",
"openai - gpt-5.5",
"anthropic - claude-haiku-4-5",
"anthropic - claude-sonnet-4-5",
"anthropic - claude-sonnet-4-6",
"google - gemini-2.5-flash",
"google - gemini-2.5-flash-lite",
"google - gemini-3-flash-preview",
"google - gemini-3.1-flash-lite",
"google - gemini-3.5-flash",
"google - gemini-3.6-flash",
"qwen - qwen36-35b-a3b",
"qwen - qwen35-397b-a17b",
null
],
"example": "openai - gpt-4o-mini",
"maxLength": 100,
"nullable": true,
"type": "string"
},
"llmOverride": {
"deprecated": true,
"description": "Deprecated alias of llm. On a read, the agent's legacy pinned model until its next save moves it into llm, else null. On a write it wins over llm when both are sent",
"enum": [
"openai - gpt-4o-mini",
"openai - gpt-4o",
"openai - gpt-4.1",
"openai - gpt-4.1-mini",
"openai - gpt-4.1-nano",
"openai - gpt-5",
"openai - gpt-5-mini",
"openai - gpt-5-nano",
"openai - gpt-5.1",
"openai - gpt-5.2",
"openai - gpt-5.4",
"openai - gpt-5.4-mini",
"openai - gpt-5.4-nano",
"openai - gpt-5.5",
"anthropic - claude-haiku-4-5",
"anthropic - claude-sonnet-4-5",
"anthropic - claude-sonnet-4-6",
"google - gemini-2.5-flash",
"google - gemini-2.5-flash-lite",
"google - gemini-3-flash-preview",
"google - gemini-3.1-flash-lite",
"google - gemini-3.5-flash",
"google - gemini-3.6-flash",
"qwen - qwen36-35b-a3b",
"qwen - qwen35-397b-a17b",
null
],
"maxLength": 100,
"nullable": true,
"type": "string"
},
"maxCallDurationMinutes": {
"description": "Hard cap on one call",
"example": 30,
"format": "int64",
"maximum": 180,
"minimum": 1,
"type": "integer"
},
"minorVersion": {
"description": "Generation of the agent's tuned defaults. Omitted on create means the latest; omitted on replace keeps the stored value. A create takes 0 to the latest (send the source's value when duplicating an agent); a replace takes the stored value or the latest, and any other value is rejected with 422. Moving it to the latest applies the minorVersion change optimizedSettings lists",
"format": "int64",
"type": "integer"
},
"optimizeStreamingLatency": {
"description": "Latency optimisation level",
"format": "int64",
"maximum": 4,
"minimum": 0,
"type": "integer"
},
"optimizedSettings": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentOptimizedSettings"
}
],
"description": "What applying the platform's optimized values for the agent's current setup would change. The server never applies them on its own; set each change's path to its to value and replace the agent",
"readOnly": true
},
"provider": {
"description": "Speech provider the agent runs on; null on a read when the agent has none set. Omitted on create means the optimized one; omitted on replace keeps the stored value",
"enum": [
"elevenlabs",
"deepgram",
null
],
"example": "elevenlabs",
"nullable": true,
"type": "string"
},
"providerOverride": {
"deprecated": true,
"description": "Deprecated alias of provider. On a read, the agent's legacy pinned provider until its next save moves it into provider, else null. On a write it wins over provider when both are sent",
"enum": [
"elevenlabs",
"deepgram",
null
],
"nullable": true,
"type": "string"
},
"scenarios": {
"description": "Situational instructions",
"items": {
"$ref": "#/components/schemas/VoiceAgentScenario"
},
"maxItems": 50,
"nullable": true,
"type": "array"
},
"secondaryLanguages": {
"description": "Additional languages; the write is rejected with 422 and the detail code LANGUAGE_NOT_SUPPORTED, never trimmed, when the agent's provider does not serve a code, Deepgram included. A blank or repeated code is dropped. A Deepgram agent with secondary languages Deepgram serves is saved, and optimizedSettings then proposes ElevenLabs",
"items": {
"type": "string"
},
"maxItems": 20,
"nullable": true,
"type": "array"
},
"similarity": {
"description": "Voice similarity boost",
"format": "double",
"maximum": 1,
"minimum": 0,
"type": "number"
},
"skills": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentSkills"
}
],
"description": "Capabilities the agent may use"
},
"stability": {
"description": "Voice stability",
"format": "double",
"maximum": 1,
"minimum": 0,
"type": "number"
},
"status": {
"description": "Whether the agent may run; omitted on write means enabled",
"enum": [
"enabled",
"disabled"
],
"example": "enabled",
"type": "string"
},
"temperature": {
"description": "Creativity of the agent's replies",
"format": "double",
"maximum": 1,
"minimum": 0,
"type": "number"
},
"tone": {
"description": "Tone presets the agent blends",
"items": {
"enum": [
"professional",
"friendly",
"casual",
"calm",
"empathetic",
"direct"
],
"type": "string"
},
"maxItems": 6,
"nullable": true,
"type": "array"
},
"updatedAt": {
"description": "When the agent was last saved",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"verbosity": {
"description": "How much the agent elaborates; omitted means standard",
"enum": [
"concise",
"standard",
"thorough"
],
"type": "string"
},
"voiceId": {
"description": "Voice the agent speaks with",
"example": "cgSgspJ2msm6clMCkdW9",
"maxLength": 64,
"type": "string"
}
},
"required": [
"agentName",
"direction",
"defaultOutboundNumberId",
"language",
"maxCallDurationMinutes",
"voiceId",
"temperature",
"stability",
"similarity",
"optimizeStreamingLatency",
"goalPrompt"
],
"type": "object"
},
"VoiceAgentBackgroundSound": {
"additionalProperties": false,
"nullable": true,
"properties": {
"isCrossfadeLoopEnabled": {
"description": "Smooth the seam when the ambience loops",
"nullable": true,
"type": "boolean"
},
"preset": {
"description": "Ambience preset",
"enum": [
"city",
"elevator",
"elevator2",
"elevator3",
"elevator4",
"office",
"office2",
"restaurant",
"typing"
],
"type": "string"
},
"volume": {
"description": "Ambience volume; null uses the provider default",
"format": "double",
"maximum": 1,
"minimum": 0,
"nullable": true,
"type": "number"
}
},
"required": [
"preset"
],
"type": "object"
},
"VoiceAgentBookingSkill": {
"additionalProperties": false,
"nullable": true,
"properties": {
"calendarEventDescription": {
"description": "Body of the created event",
"maxLength": 2000,
"type": "string"
},
"calendarId": {
"description": "Calendar the appointment is created in",
"maxLength": 255,
"type": "string"
},
"durationMinutes": {
"description": "Length of the booked slot",
"format": "int64",
"maximum": 480,
"minimum": 1,
"type": "integer"
},
"eventName": {
"description": "Title of the created event",
"maxLength": 255,
"type": "string"
},
"integrationId": {
"description": "Calendar integration the agent books in",
"maxLength": 100,
"type": "string"
},
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"serviceDescription": {
"description": "What is being booked",
"maxLength": 2000,
"type": "string"
}
},
"required": [
"isEnabled",
"integrationId",
"calendarId",
"eventName",
"durationMinutes"
],
"type": "object"
},
"VoiceAgentContextProperty": {
"additionalProperties": false,
"properties": {
"description": {
"description": "What the agent should put in the property",
"maxLength": 1000,
"type": "string"
},
"name": {
"description": "Property name",
"example": "callerName",
"maxLength": 100,
"type": "string"
},
"type": {
"description": "Value type",
"enum": [
"STRING",
"NUMBER",
"BOOLEAN",
"ARRAY"
],
"example": "STRING",
"type": "string"
}
},
"required": [
"name",
"type",
"description"
],
"type": "object"
},
"VoiceAgentCustomSkill": {
"additionalProperties": false,
"properties": {
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"name": {
"description": "Skill name",
"maxLength": 100,
"type": "string"
},
"prompt": {
"description": "What the agent should do",
"maxLength": 5000,
"type": "string"
}
},
"required": [
"isEnabled",
"name",
"prompt"
],
"type": "object"
},
"VoiceAgentElevenLabsSettings": {
"additionalProperties": false,
"nullable": true,
"properties": {
"asrKeywords": {
"description": "Phrases speech recognition should favour",
"items": {
"type": "string"
},
"maxItems": 100,
"nullable": true,
"type": "array"
},
"backgroundSound": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentBackgroundSound"
}
],
"description": "Ambience played under the conversation"
},
"interruptionIgnoreTermLanguages": {
"description": "Languages the ignored terms are given in",
"items": {
"type": "string"
},
"maxItems": 20,
"nullable": true,
"type": "array"
},
"interruptionIgnoreTerms": {
"description": "Words that must not count as an interruption",
"items": {
"type": "string"
},
"maxItems": 100,
"nullable": true,
"type": "array"
},
"isSpeculativeTurnEnabled": {
"description": "Let the agent prepare a reply before the caller stops speaking",
"nullable": true,
"type": "boolean"
},
"isVadEnabled": {
"description": "Filter background noise with voice activity detection",
"nullable": true,
"type": "boolean"
},
"turnEagerness": {
"description": "How soon the agent takes a turn",
"enum": [
"patient",
"normal",
"eager"
],
"type": "string"
},
"turnModel": {
"description": "Turn-taking model",
"enum": [
"turn_v2",
"turn_v3"
],
"type": "string"
}
},
"type": "object"
},
"VoiceAgentExtractDataSkill": {
"additionalProperties": false,
"nullable": true,
"properties": {
"endpoint": {
"description": "HTTPS webhook the collected values are posted to",
"maxLength": 2000,
"type": "string"
},
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"properties": {
"description": "Values to collect",
"items": {
"$ref": "#/components/schemas/VoiceAgentContextProperty"
},
"maxItems": 50,
"nullable": true,
"type": "array"
}
},
"required": [
"isEnabled",
"properties"
],
"type": "object"
},
"VoiceAgentGuardrail": {
"additionalProperties": false,
"properties": {
"isEnabled": {
"description": "Whether the guardrail is active",
"type": "boolean"
},
"reply": {
"description": "What the agent answers instead",
"maxLength": 2000,
"type": "string"
},
"when": {
"description": "Situation the guardrail covers",
"maxLength": 2000,
"type": "string"
}
},
"required": [
"isEnabled"
],
"type": "object"
},
"VoiceAgentListAttributes": {
"additionalProperties": false,
"properties": {
"agentName": {
"description": "Name of the agent",
"type": "string"
},
"createdAt": {
"description": "When the agent was created",
"format": "date-time",
"type": "string"
},
"direction": {
"description": "Call direction the agent serves",
"enum": [
"inbound",
"outbound"
],
"type": "string"
},
"language": {
"description": "Primary language code",
"type": "string"
},
"status": {
"description": "Whether the agent may run",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"updatedAt": {
"description": "When the agent was last saved",
"format": "date-time",
"type": "string"
},
"voiceId": {
"description": "Voice the agent speaks with",
"type": "string"
}
},
"required": [
"agentName",
"direction",
"status",
"language",
"voiceId",
"createdAt",
"updatedAt"
],
"type": "object"
},
"VoiceAgentOptimizedChange": {
"additionalProperties": false,
"properties": {
"from": {
"description": "The value the agent runs with; null when unset"
},
"path": {
"description": "Attribute path of the setting, as a write body spells it: provider, llm, minorVersion, elevenLabsSettings.isVadEnabled, elevenLabsSettings.turnModel, elevenLabsSettings.isSpeculativeTurnEnabled or elevenLabsSettings.turnEagerness",
"example": "llm",
"type": "string"
},
"to": {
"description": "The optimized value"
}
},
"required": [
"path",
"from",
"to"
],
"type": "object"
},
"VoiceAgentOptimizedSettings": {
"additionalProperties": false,
"nullable": true,
"properties": {
"changes": {
"description": "Attributes that differ from the optimized values; set each path to its to value and replace the agent to apply them",
"items": {
"$ref": "#/components/schemas/VoiceAgentOptimizedChange"
},
"type": "array"
},
"effects": {
"description": "What applying the changes brings that no attribute holds; backupModels: the agent gains the backup model chain",
"items": {
"enum": [
"backupModels"
],
"type": "string"
},
"type": "array"
},
"isAvailable": {
"description": "Whether applying the optimized settings would change anything (changes is not empty)",
"type": "boolean"
}
},
"required": [
"isAvailable",
"changes",
"effects"
],
"type": "object"
},
"VoiceAgentScenario": {
"additionalProperties": false,
"properties": {
"action": {
"description": "Action performed when the scenario fires; null means the scenario only replies",
"enum": [
"toolCall",
"sendSms",
"hangup",
null
],
"nullable": true,
"type": "string"
},
"actionParameters": {
"additionalProperties": {},
"description": "Action inputs; sendSms takes senderNumber and message",
"type": "object"
},
"isEnabled": {
"description": "Whether the scenario is active",
"type": "boolean"
},
"reply": {
"description": "What the agent says when the scenario fires",
"maxLength": 2000,
"type": "string"
},
"toolId": {
"description": "Tool invoked when action is toolCall; must be one of the company's tools",
"maxLength": 64,
"nullable": true,
"type": "string"
},
"triggerType": {
"description": "What activates the scenario; defaults to custom",
"enum": [
"custom",
"booking_confirmed"
],
"type": "string"
},
"when": {
"description": "Trigger text; required and used only when triggerType is custom",
"maxLength": 2000,
"type": "string"
}
},
"required": [
"isEnabled",
"reply"
],
"type": "object"
},
"VoiceAgentSkills": {
"additionalProperties": false,
"properties": {
"answerQuestions": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentAnswerQuestionsSkill"
}
],
"description": "Answer questions from the agent's knowledge"
},
"appointmentBooking": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentBookingSkill"
}
],
"description": "Book a calendar appointment"
},
"custom": {
"description": "Free-form capabilities described by a prompt",
"items": {
"$ref": "#/components/schemas/VoiceAgentCustomSkill"
},
"maxItems": 20,
"nullable": true,
"type": "array"
},
"extractData": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentExtractDataSkill"
}
],
"description": "Collect structured data during the call"
},
"takeMessage": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentTakeMessageSkill"
}
],
"description": "Record a message for the company"
},
"transferToHuman": {
"allOf": [
{
"$ref": "#/components/schemas/VoiceAgentTransferSkill"
}
],
"description": "Hand the call to a human"
}
},
"type": "object"
},
"VoiceAgentTakeMessageSkill": {
"additionalProperties": false,
"nullable": true,
"properties": {
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"prompt": {
"description": "Instructions for taking the message",
"maxLength": 5000,
"type": "string"
}
},
"required": [
"isEnabled"
],
"type": "object"
},
"VoiceAgentTransferRule": {
"additionalProperties": false,
"properties": {
"agentExtension": {
"description": "Target agent extension",
"maxLength": 32,
"nullable": true,
"type": "string"
},
"agentId": {
"description": "Target agent id; required together with agentExtension when destination is agent",
"format": "int64",
"nullable": true,
"type": "integer"
},
"condition": {
"description": "When the call should be transferred",
"maxLength": 1000,
"type": "string"
},
"destination": {
"description": "Kind of transfer target",
"enum": [
"agent",
"group",
"call_flow"
],
"type": "string"
},
"groupExtension": {
"description": "Target group extension",
"maxLength": 32,
"nullable": true,
"type": "string"
},
"groupId": {
"description": "Target group id; required together with groupExtension when destination is group",
"format": "int64",
"nullable": true,
"type": "integer"
}
},
"required": [
"condition",
"destination"
],
"type": "object"
},
"VoiceAgentTransferSkill": {
"additionalProperties": false,
"nullable": true,
"properties": {
"customProperties": {
"description": "Extra context handed to the human agent",
"items": {
"$ref": "#/components/schemas/VoiceAgentContextProperty"
},
"maxItems": 20,
"nullable": true,
"type": "array"
},
"includeProperties": {
"description": "Context handed to the human agent",
"items": {
"enum": [
"callerName",
"summary"
],
"type": "string"
},
"maxItems": 2,
"nullable": true,
"type": "array"
},
"isConfirmationRequired": {
"description": "Ask the caller to confirm before transferring",
"type": "boolean"
},
"isEnabled": {
"description": "Whether the skill is active",
"type": "boolean"
},
"rules": {
"description": "Routing rules, evaluated in order",
"items": {
"$ref": "#/components/schemas/VoiceAgentTransferRule"
},
"maxItems": 50,
"nullable": true,
"type": "array"
}
},
"required": [
"isEnabled",
"rules"
],
"type": "object"
},
"VoiceAgentTransferTarget": {
"additionalProperties": false,
"nullable": true,
"properties": {
"agentExtension": {
"description": "Target agent extension",
"maxLength": 32,
"nullable": true,
"type": "string"
},
"agentId": {
"description": "Target agent id",
"format": "int64",
"nullable": true,
"type": "integer"
},
"destination": {
"description": "Kind of transfer target",
"enum": [
"agent",
"group",
"call_flow"
],
"type": "string"
},
"groupExtension": {
"description": "Target group extension",
"maxLength": 32,
"nullable": true,
"type": "string"
},
"groupId": {
"description": "Target group id",
"format": "int64",
"nullable": true,
"type": "integer"
}
},
"required": [
"destination"
],
"type": "object"
},
"CollectionKnowledgeBaseAttributes": {
"additionalProperties": false,
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/ResourceKnowledgeBaseAttributes"
},
"nullable": true,
"type": "array"
},
"pagination": {
"$ref": "#/components/schemas/PublicPagination"
},
"requestId": {
"type": "string"
}
},
"required": [
"data",
"pagination",
"requestId"
],
"type": "object"
},
"KnowledgeBaseAttributes": {
"additionalProperties": false,
"properties": {
"createdAt": {
"description": "When the knowledge base was created",
"format": "date-time",
"type": "string"
},
"fileExtension": {
"description": "Extension of the stored file: the upload's extension, HTML for a custom source, null for a URL source",
"nullable": true,
"type": "string"
},
"name": {
"description": "Name of the knowledge base; derived from the filename for an uploaded file",
"type": "string"
},
"sourceType": {
"description": "Where the content comes from",
"enum": [
"URL",
"FILE",
"CUSTOM"
],
"type": "string"
},
"sourceUrl": {
"description": "Address the content is read from; null unless sourceType is URL",
"nullable": true,
"type": "string"
},
"status": {
"description": "Whether the content is ready to be used by a voice agent",
"enum": [
"ACTIVE",
"SYNCHRONIZING",
"ERROR"
],
"type": "string"
},
"updatedAt": {
"description": "When the knowledge base was last changed",
"format": "date-time",
"type": "string"
},
"voiceAgentIds": {
"description": "Voice agents the knowledge base is attached to",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"required": [
"name",
"sourceType",
"status",
"sourceUrl",
"fileExtension",
"voiceAgentIds",
"createdAt",
"updatedAt"
],
"type": "object"
},
"KnowledgeBaseCreateAttributes": {
"additionalProperties": false,
"properties": {
"name": {
"description": "Name of the knowledge base",
"example": "returns-policy",
"maxLength": 50,
"minLength": 1,
"type": "string"
},
"sourceType": {
"description": "Where the content comes from; upload a file through POST /knowledge-bases/files",
"enum": [
"URL",
"CUSTOM"
],
"example": "URL",
"type": "string"
},
"text": {
"description": "Content of the knowledge base; required when sourceType is CUSTOM, rejected otherwise",
"example": "We accept returns within 30 days.",
"type": "string"
},
"url": {
"description": "Address to read the content from; required when sourceType is URL, rejected otherwise",
"example": "https://example.com/returns",
"type": "string"
}
},
"required": [
"sourceType",
"name"
],
"type": "object"
},
"ResourceKnowledgeBaseAttributes": {
"additionalProperties": false,
"properties": {
"attributes": {
"$ref": "#/components/schemas/KnowledgeBaseAttributes"
},
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"type",
"attributes"
],
"type": "object"
},
"SingleKnowledgeBaseAttributes": {
"additionalProperties": false,
"properties": {
"data": {
"$ref": "#/components/schemas/ResourceKnowledgeBaseAttributes"
},
"requestId": {
"type": "string"
}
},
"required": [
"data",
"requestId"
],
"type": "object"
},
"WebhookEventType": {
"type": "object",
"required": [
"name",
"description",
"groupName"
],
"properties": {
"name": {
"type": "string",
"example": "call.ended"
},
"description": {
"type": "string"
},
"groupName": {
"type": "string",
"example": "call"
},
"schemas": {
"type": "object",
"description": "Only with `include=schema`: the JSON Schema of the full webhook body, keyed by version.",
"additionalProperties": {
"type": "object"
}
}
}
},
"WebhookEventTypeList": {
"type": "object",
"required": [
"data",
"requestId"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEventType"
}
},
"requestId": {
"type": "string"
}
}
},
"WebhookEndpoint": {
"type": "object",
"required": [
"id",
"url",
"description",
"eventTypes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"example": "ep_2nJ4qKZr8C1tY0dXwV3uFh7bM9s"
},
"url": {
"type": "string",
"description": "As stored; the host may come back lowercased and a bare host with a trailing slash."
},
"description": {
"type": "string"
},
"eventTypes": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Subscribed event types, sorted. `null` means every event type, including ones added later."
},
"status": {
"type": "string",
"enum": [
"enabled",
"disabled",
"failing"
],
"description": "`disabled`: turned off by you (Dashboard or API). `failing`: turned off automatically after repeated delivery failures; it may be re-enabled automatically, or by you."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"secret": {
"type": "string",
"description": "Only in the create response: the signing secret (`whsec_...`). Absent if it could not be read; then use the secret endpoint."
}
}
},
"WebhookEndpointList": {
"type": "object",
"required": [
"data",
"pagination",
"requestId"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
},
"pagination": {
"$ref": "#/components/schemas/PublicPagination"
},
"requestId": {
"type": "string"
}
}
},
"WebhookEndpointCreate": {
"type": "object",
"additionalProperties": false,
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"description": "`https://` URL on a public host whose name ends in a public top-level domain."
},
"description": {
"type": "string",
"maxLength": 500
},
"eventTypes": {
"type": "array",
"nullable": true,
"minItems": 1,
"items": {
"type": "string"
},
"description": "Event types to receive (see List webhook event types). Omit or send null for every event type. An empty list is rejected."
}
}
},
"WebhookEndpointUpdate": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"url": {
"type": "string",
"maxLength": 2048
},
"description": {
"type": "string",
"maxLength": 500
},
"eventTypes": {
"type": "array",
"nullable": true,
"minItems": 1,
"items": {
"type": "string"
},
"description": "Replaces the subscription. `null` subscribes to every event type."
},
"enabled": {
"type": "boolean"
}
}
},
"WebhookSecret": {
"type": "object",
"required": [
"secret"
],
"properties": {
"secret": {
"type": "string",
"example": "whsec_EXAMPLE_SIGNING_SECRET"
}
}
},
"WebhookRotatedSecret": {
"type": "object",
"required": [
"secret",
"previousSecretExpiresAt"
],
"properties": {
"secret": {
"type": "string",
"description": "The new signing secret.",
"example": "whsec_EXAMPLE_NEW_SIGNING_SECRET"
},
"previousSecretExpiresAt": {
"type": "string",
"format": "date-time",
"description": "When the previous secret stops signing deliveries: 24 hours after the rotation. Until then every delivery carries signatures from both secrets.",
"example": "2026-10-15T09:30:12Z"
}
}
},
"WebhookTestRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"eventType"
],
"properties": {
"eventType": {
"type": "string",
"example": "call.ended"
}
}
},
"WebhookAcceptedDelivery": {
"type": "object",
"required": [
"deliveryId"
],
"properties": {
"deliveryId": {
"type": "string",
"example": "msg_2nJ5bQw1pX7cT4aZsY8vHk0dLr3"
}
}
},
"WebhookDelivery": {
"type": "object",
"required": [
"id",
"eventType",
"eventId",
"status",
"nextAttemptAt",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"description": "Delivery id; the same value as the `svix-id` header of the delivered request."
},
"eventType": {
"type": "string"
},
"eventId": {
"type": "string",
"nullable": true,
"description": "The `event_id` of the webhook body, the key to deduplicate on."
},
"status": {
"type": "string",
"enum": [
"succeeded",
"failed",
"retrying",
"pending",
"canceled"
],
"description": "`retrying`: an attempt failed and another is scheduled at `nextAttemptAt`. `failed`: the last attempt failed and no retry is scheduled."
},
"nextAttemptAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
"WebhookDeliveryList": {
"type": "object",
"required": [
"data",
"pagination",
"requestId"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDelivery"
}
},
"pagination": {
"$ref": "#/components/schemas/PublicPagination"
},
"requestId": {
"type": "string"
}
}
},
"WebhookDeliveryAttempt": {
"type": "object",
"required": [
"id",
"createdAt",
"status",
"responseStatusCode",
"responseDurationMs",
"responseBody",
"responseTruncated",
"trigger"
],
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"succeeded",
"failed",
"pending",
"canceled"
]
},
"responseStatusCode": {
"type": "integer",
"description": "HTTP status your server answered; 0 when it could not be reached."
},
"responseDurationMs": {
"type": "integer"
},
"responseBody": {
"type": "string",
"description": "Your server's response body, at most 4 KB. When no HTTP response came back (`responseStatusCode` 0), a fixed message instead."
},
"responseTruncated": {
"type": "boolean"
},
"trigger": {
"type": "string",
"enum": [
"scheduled",
"manual"
],
"description": "`manual` for a retry you requested."
}
}
},
"WebhookDeliveryDetail": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookDelivery"
},
{
"type": "object",
"required": [
"payload",
"attempts"
],
"properties": {
"payload": {
"type": "object",
"nullable": true,
"description": "The body that was sent. `null` after the 30-day payload retention."
},
"attempts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDeliveryAttempt"
}
}
}
}
]
}
},
"parameters": {
"limit": {
"name": "limit",
"in": "query",
"description": "Max. number of items in response data.",
"schema": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
"page": {
"name": "page",
"in": "query",
"description": "Number of page to return.",
"schema": {
"minimum": 1,
"type": "integer"
}
},
"callId": {
"name": "callId",
"in": "path",
"required": true,
"description": "Call ID",
"schema": {
"type": "number"
}
},
"paginationLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of items to return",
"required": false,
"schema": {
"type": "integer",
"minimum": 1
}
},
"paginationOffset": {
"name": "offset",
"in": "query",
"description": "Offset the list of returned items by this amount",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"dialerCampaignContactId": {
"name": "campaignContactId",
"in": "path",
"required": true,
"description": "Campaign-contact (membership) ID — `campaign_contact_id` from the contacts list, not the contact's own id.",
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"example": "5100"
},
"dialerCampaignId": {
"name": "campaignId",
"in": "path",
"required": true,
"description": "Dialer campaign ID.",
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
},
"dialerExportJobId": {
"name": "jobId",
"in": "path",
"required": true,
"description": "Export job ID returned by the export enqueue call.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"dialerScriptId": {
"name": "scriptId",
"in": "path",
"required": true,
"description": "Script ID (BIGINT serialized as string in responses; send the numeric value).",
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"example": "17"
},
"dialerSurveyId": {
"name": "surveyId",
"in": "path",
"required": true,
"description": "Survey ID (BIGINT serialized as string in responses; send the numeric value).",
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"example": "8"
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic",
"description": "HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys)."
}
}
},
"security": [
{
"basicAuth": []
}
]
}