# API reference (/api-reference) Every page below is generated from the same OpenAPI document the API is built from, so parameters, request bodies and responses always match production. Each endpoint lists **every status code it can return**, with an example body, and code samples in several languages. | | | | --- | --- | | **Base URL** | `https://api.callmitra.ai` (paths include `/api/v1`) | | **Authentication** | `X-API-Key: vk_live_…` ([details](/authentication)) | | **Format** | JSON request and response bodies, `camelCase` fields, ISO 8601 UTC timestamps, UUID IDs | | **Errors** | `detail` plus a structured `error` object ([catalogue](/errors)) | | **Limits** | 300 requests per minute per key ([rate limits](/rate-limits)) | | **OpenAPI** | [Download `openapi.json`](/openapi.json) for Postman, Bruno, Insomnia or code generators | # Authentication & API keys (/authentication) Every request to the CallMitra API is authenticated with an API key sent in the `X-API-Key` header. ```bash curl https://api.callmitra.ai/api/v1/leads/?limit=5 \ -H "X-API-Key: vk_live_..." ``` If your HTTP client prefers the standard `Authorization` header, send the same key as a bearer token instead. When both headers are present, `X-API-Key` wins. ```bash curl https://api.callmitra.ai/api/v1/leads/?limit=5 \ -H "Authorization: Bearer vk_live_..." ``` All requests must use HTTPS. Keys work only under `/api/v1`. | Problem | Status | Code | | --- | --- | --- | | No key sent | `401` | [`unauthenticated`](/errors/unauthenticated) | | Unknown or revoked key | `401` | [`invalid_api_key`](/errors/invalid_api_key) | | Key past its expiry date | `401` | [`api_key_expired`](/errors/api_key_expired) | | Endpoint that no key may call | `403` | [`api_key_route_forbidden`](/errors/api_key_route_forbidden) | | Outside the key's access or resources | `403` | [`api_key_scope_denied`](/errors/api_key_scope_denied) | | Too many requests for this key | `429` | [`rate_limit_exceeded`](/errors/rate_limit_exceeded) | ## Create a key [#create-a-key] 1. In the console, open **Settings → Developers**. 2. Choose **Create key**, name it after the integration that will use it, and choose its access and expiry. 3. Copy the secret. It starts with `vk_live_` and is shown **once**; CallMitra stores only a hash. The console keeps the first characters (the key prefix) so you can recognise the key later. Only workspace **managers** can create and revoke keys. Other team members see only the keys they created. Keys cannot be created, listed or revoked through the API, and a key cannot be created while you are working inside an agency client workspace: create it in your own workspace instead ([Agencies](/guides/agencies)). Revoking a key in the console stops it on the very next request. A workspace can hold a limited number of unexpired keys (20 by default). Creating another fails with [`api_key_limit_reached`](/errors/api_key_limit_reached); revoke a key you no longer use first. ## Keys belong to the workspace [#keys-belong-to-the-workspace] A key belongs to your **workspace**, not to the person who created it. It sees that workspace's data, and the console shows who created it. - While its creator is still an active member of the workspace, the key acts as that person with their **current** role. It gets the same data access and shows the same name in the audit log. If a manager is later made a lead, their keys act as a lead from the next request. A key never has more access than its creator. - If the creator is deleted, suspended or blocked, or moves to another workspace, the key **keeps working**. It then acts as the workspace's primary manager, the earliest-created active manager. Each switch like this is written to the audit log as `api_key.actor_fallback`, at most once per key per UTC day. Revoke the key in **Settings → Developers** when an integration should stop. - If the workspace has no active manager left, the key answers `401` `invalid_api_key`. - If the workspace itself is suspended, keys stop working until it is active again. - Keys created by CallMitra platform staff accounts are refused with `403`; staff work in the admin console with multi-factor authentication. ## Limit what a key can do [#limit-what-a-key-can-do] When you create a key you choose: | Option | Values | Effect | | --- | --- | --- | | Access | **Full** or **Read only** | A read-only key can only send `GET` (and `HEAD`/`OPTIONS`) requests. Anything that changes data answers `403` [`api_key_scope_denied`](/errors/api_key_scope_denied) with the message `This API key is read-only.` | | Can access | All resources, or a list | A key limited to resources answers `403` [`api_key_scope_denied`](/errors/api_key_scope_denied) on every endpoint outside them. | | Expiry | 30 days, 90 days (the default), 1 year, or does not expire | After expiry the key answers `401` [`api_key_expired`](/errors/api_key_expired). Create a new key and revoke the old one. | Resources and the endpoints they cover: | Resource | Covers | | --- | --- | | Leads | Leads, lead notes, do-not-call, lead sources, fields, segments, lead integrations, search | | Campaigns | Campaigns, dialing controls, instant calls, callbacks and reminder rules, inbound routing, handoff | | Calls | Call history, results and recordings | | Agents | Agents, voices, tools, templates, background sounds, MCP servers | | Numbers | Phone numbers and SIP trunks | | WhatsApp | WhatsApp messaging and engagement | | Tickets | Tickets | | Webhooks | Webhook endpoints, deliveries and event types, an agent's post-call webhook, CRM webhooks and integrations | A limited key fails closed: if an endpoint does not belong to one of its resources, the request is refused. An agent's post-call webhook can be managed by a key with either **Agents** or **Webhooks**. [`GET /workspace`](/api-reference/workspace/getWorkspace) and [`GET /usage`](/api-reference/workspace/getUsage) are readable by every key, whatever its resources. Use a separate key per system, with the smallest access it needs and an expiry. If one leaks, revoke just that key. ## Which endpoints a key can call [#which-endpoints-a-key-can-call] A key can call only the endpoints listed in the [API reference](/api-reference), under `/api/v1`. Every other route answers `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden), whatever the key's access. That includes `/platform/v1` paths and console-only routes such as: - everything under `/auth`: sign-in, sessions, passwords, multi-factor authentication, and the signed-in user's profile (`GET /auth/me`); - creating, listing or revoking API keys (`/api-keys`); - team members, roles and suspensions; - deleting or exporting the whole workspace; - platform administration and platform runtime settings; - billing changes and agency client-workspace changes. A key's access settings narrow this list further; they can never open a route that is not in the reference. When an endpoint is added to the reference, keys can call it from then on. `GET /auth/me` is a console endpoint, so keys get `403` there. Call [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace) instead: it returns the workspace the key works in and details of the key itself. See [Workspace and usage](/guides/workspace-usage). ## Rate limits [#rate-limits] Each key has its own budget of 300 requests per minute, separate from other keys and from your team's console sessions. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. See [Rate limits](/rate-limits). ## Keep keys safe [#keep-keys-safe] - Keep keys on your server. Never ship them in a web page, mobile app or public repository. - Store them in a secret manager or environment variable, not in source code. - Rotate: create the new key, deploy it, then revoke the old one. - If a key may have leaked, revoke it immediately in **Settings → Developers**. ## Related [#related] - [Agencies](/guides/agencies): one key for every client workspace with `X-Workspace-Id`. - [Rate limits](/rate-limits): each key has its own per-minute budget. - [Errors](/errors): every `401` and `403` code with how to fix it. # Changelog (/changelog) Each entry lists breaking changes first, then additions. From now on, v1 only receives additive changes ([Versioning](/versioning)). ## 2026-11-16 [#2026-11-16] ### Breaking changes [#breaking-changes] - [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients) now requires the agency add-on on the calling workspace. Without it the call returns `403` [`permission_denied`](/errors/permission_denied). See [Agencies](/guides/agencies#finding-a-clients-workspace-id). - The workspace CRM webhook is retired. `getWorkspaceWebhook` and `setWorkspaceWebhook` (`GET` and `PUT /api/v1/merchant/crm-webhook`) are removed, and **Settings → Developers → CRM webhook** is gone from the console. [Webhook endpoints](/webhooks/endpoints) are now the only workspace-wide webhook. - Each saved workspace CRM URL was moved to a [webhook endpoint](/webhooks/endpoints) with the description "Migrated from CRM webhook", subscribed to `call.completed` and `call.escalated`, plus the `ticket.*` events if ticket sync was on. The endpoint has a **new** signing secret: it does not reuse your old CRM secret. To see or replace it, [rotate the secret](/webhooks/endpoints#rotate-the-signing-secret) in **Settings → Developers → Webhooks**, then update your receiver. - Those deliveries now use the endpoint envelope (`id`, `type`, `apiVersion`, `createdAt`, `data`) and are signed with [Standard Webhooks](/webhooks/verify-signatures) headers. `X-Signature-SHA256` is still sent, but it is keyed with the new `whsec_…` secret. - Ticket events (`ticket.*`) now go only to webhook endpoints. They are no longer sent to a ticket's campaign or agent webhook URL, to a user's saved URL or to the workspace URL, and the `ticketWebhookSyncEnabled` setting is removed. Subscribe an endpoint to `ticket.*` to keep receiving them. - A call without a campaign or agent webhook URL is no longer sent to a URL saved by the user who created the call or the lead. See [Campaign and agent webhooks](/webhooks/campaign-agent-webhooks). ## 2026-11-15 [#2026-11-15] This release was the last one before general availability, and it includes breaking changes. Read **Breaking changes** before you upgrade an existing integration. ### Breaking changes [#breaking-changes-1] **API keys and authentication** - API keys get `403` on every `/auth/*` route, including `GET /auth/me`. To find out which workspace a key belongs to, call [`GET /api/v1/workspace`](/guides/workspace-usage). - API keys only work on the endpoints listed in the [API reference](/api-reference), under `/api/v1`. Any other route, including console-only routes and the `/platform/v1` alias, refuses keys with `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden). See [Authentication](/authentication). - A key acts with its creator's **current** role, so a manager who is made a lead now has keys that act as a lead. If the creator is deleted, suspended or blocked, or moves to another workspace, the key falls back to the workspace's primary manager. Each fallback is written to the audit log ([Keys belong to the workspace](/authentication#keys-belong-to-the-workspace)). **Status codes and error codes** Errors now carry a dedicated `error.code`, and some status codes changed: | Situation | Before | Now | | --- | --- | --- | | Number is on the do-not-call list | `400` | `409` [`number_on_dnc`](/errors/number_on_dnc) | | Campaign is not running (`callNow`, `callLeadNow`, `createCall`, resume) | `400` | `409` [`campaign_not_running`](/errors/campaign_not_running) | | Calling minutes used up | `400` | `402` [`payment_required`](/errors/payment_required) | | Campaign's daily call cap reached | `429` `rate_limit_exceeded` | `429` [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) | Other calling refusals now have their own codes: [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) (429), [`carrier_capacity_reached`](/errors/carrier_capacity_reached) (409), [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) (409), [`campaign_dial_busy`](/errors/campaign_dial_busy) (409), [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) (409), [`campaign_leads_need_confirmation`](/errors/campaign_leads_need_confirmation) (409), [`campaign_not_ready`](/errors/campaign_not_ready) (422), [`lead_has_no_campaign`](/errors/lead_has_no_campaign) (422), [`dial_rejected`](/errors/dial_rejected) (400) and [`dial_failed`](/errors/dial_failed) (502). Errors for a missing resource now name it, for example [`campaign_not_found`](/errors/campaign_not_found) or [`lead_not_found`](/errors/lead_not_found), where they used to return `resource_not_found`. [All error codes](/errors#all-error-codes) lists every code. **Response shapes** - `callNow` and `callLeadNow` now wrap the new call in a `call` object. Read `call.id` and `call.status`. - `createLead` and `updateLead` normalise phone numbers to E.164 and refuse numbers they cannot parse with `422` [`invalid_phone_number`](/errors/invalid_phone_number) ([Phone numbers](/guides/leads#phone-numbers)). - The do-not-call list returns at most 500 entries per request, with `hasMore` ([Pagination](/pagination)). **Validation** - Agent `config` values are validated. A known key with a bad value returns `422` [`parameter_invalid`](/errors/parameter_invalid) with `param` set to the config path. Unknown keys are dropped, not refused ([Agents](/guides/agents#config-reference)). - `POST /calls` refuses unknown body fields with `422`. - Agent `config` is limited to 512 KB (`413` [`payload_too_large`](/errors/payload_too_large)) and 16 levels of nesting. This applies to create, update and import. - Agent saves now refuse, with `422` `parameter_invalid`: - tool URLs and `post_call_webhook.url` that are not public `http(s)` addresses; - a `tools[].config.tool_id` that is not a tool in your workspace; - a `config.stt` provider that is not available. Import drops such values with a warning instead ([Import agents](/migrate/import-agents)). - During a call, an inline `api_request` tool only accepts a relative path under its saved `base_url` ([Inline tools](/guides/agents#inline-tools)). - The `agent_not_published` code was removed. Go-live publishes a pending draft first and refuses with [`agent_state_blocked`](/errors/agent_state_blocked). **Calls and idempotency** - `POST /calls` dials once. It does not redial a call that was not answered, was busy or timed out, and a refused dial is not queued. A callback the agent books during the call is still placed ([One request, one dial](/guides/direct-calls#one-request-one-dial)). - Responses that contain a one-time secret (webhook endpoint create and secret rotation) are never stored. Replaying the same `Idempotency-Key` returns `409` [`idempotency_key_reused`](/errors/idempotency_key_reused), not the secret again. - A request body over 1 MB skips idempotency and runs normally ([Idempotency](/idempotency)). **Webhooks** - [`lead.created`](/webhooks/events#leadcreated-and-leadupdated) is sent only for leads added one at a time: `createLead`, the console form and lead sources. Spreadsheet imports, campaign uploads and leads made automatically do not send it. - Test events and redeliveries are limited to 10 per endpoint per minute (`429` `rate_limit_exceeded`). **WhatsApp** - The public WhatsApp endpoints now live under `/api/v1/whatsapp`, and their request and response fields are camelCase. Update the base path and field names if you used the earlier WhatsApp API ([WhatsApp](/guides/whatsapp)). ### Added [#added] - **Error envelope:** every error returns `detail` plus an `error` object with `type`, `code`, `message`, `param`, `docUrl` and `requestId` ([Errors](/errors)). - **Webhooks v2:** signed webhook endpoints per workspace, an event catalogue, test events, a delivery log, redelivery and secret rotation ([Webhooks](/webhooks)). - **Direct calls:** `POST /calls` places one call without building a campaign. It only dials your workspace's home country and has a daily limit per workspace ([`destination_not_allowed`](/errors/destination_not_allowed), [`daily_call_limit_reached`](/errors/daily_call_limit_reached)). Also new: call transcript, recording, performance and daily counts ([Place and read calls](/guides/direct-calls)). - **Agents:** create, update a draft, publish, start, pause, test calls, voices and tools, plus [agent import](/migrate/import-agents) from Vapi, Retell and Bland ([Agents](/guides/agents)). - **Workspace and usage:** `GET /workspace` and `GET /usage` work with every key ([Workspace and usage](/guides/workspace-usage)). - **Tickets:** list, create, update, notes, customer replies, categories and teams ([Tickets](/guides/tickets)). - **WhatsApp:** send messages, read a message and list templates ([WhatsApp](/guides/whatsapp)). - **Leads:** a lead fields catalogue and a callbacks list ([Leads](/guides/leads)). - **Cursor pagination:** `listLeads` and `listCalls` accept a `cursor`. Page responses gain `nextCursor`, `hasMore` and `totalCapped` ([Pagination](/pagination)). - **Idempotency:** create endpoints accept an `Idempotency-Key` header ([Idempotency](/idempotency)). - **Rate-limit headers:** each key has its own limit, reported in `RateLimit-*` headers ([Rate limits](/rate-limits)). - **API key limit:** a workspace can hold 20 unexpired keys by default ([`api_key_limit_reached`](/errors/api_key_limit_reached)). - **Agency client list:** [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients) lists an agency's client workspaces. Any agency key can call it if the key acts as a manager ([Agencies](/guides/agencies#finding-a-clients-workspace-id)). - **Disabled-endpoint alert:** when a webhook endpoint is disabled automatically, the workspace gets one alert: in the console, plus email or WhatsApp if those alerts are on ([Automatic disabling](/webhooks#automatic-disabling)). - **Developer hub in the console:** **Settings → Developers** manages API keys, webhook endpoints (including test events, the delivery log and redelivery) and the CRM webhook. - Stopping a campaign that is already stopped now succeeds. # agent_not_found (/errors/agent_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `agent_not_found` | ## What it means [#what-it-means] No agent with this id exists in your workspace, or it was deleted. List your agents with `GET /agents` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Agent not found.", "error": { "type": "not_found_error", "code": "agent_not_found", "message": "Agent not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `PATCH /api/v1/agents/{agent_id}` — Update an agent # agent_state_blocked (/errors/agent_state_blocked) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `agent_state_blocked` | ## What it means [#what-it-means] The agent's current settings or state do not allow this step: for example the script is over its length limit, the voice is not available for the language, the language model has no usable key, the agent has no phone number, or it is archived. The message says which rule failed; fix it and retry. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `PATCH /api/v1/agents/{agent_id}` — Update an agent # agent_test_call_failed (/errors/agent_test_call_failed) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `agent_test_call_failed` | ## What it means [#what-it-means] The test call was refused before dialing: for example the agent is missing required values, the number cannot place calls, or the free test-call allowance is used up. The message says why. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The test call could not be placed.", "error": { "type": "invalid_request_error", "code": "agent_test_call_failed", "message": "The test call could not be placed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/agent_test_call_failed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call # api_key_expired (/errors/api_key_expired) | HTTP status | Type | Code | | --- | --- | --- | | 401 | `authentication_error` | `api_key_expired` | ## What it means [#what-it-means] The API key passed its expiry date. Create a new key in the developer settings and replace the old one in your integration. ## How to handle it [#how-to-handle-it] Check that the `X-API-Key` header carries a current key. Create a new key in the console (**Settings → Developers**) if this one was revoked or expired. Do not retry in a loop. ## Example response [#example-response] ```json { "detail": "The API key has expired.", "error": { "type": "authentication_error", "code": "api_key_expired", "message": "The API key has expired.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # api_key_limit_reached (/errors/api_key_limit_reached) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `api_key_limit_reached` | ## What it means [#what-it-means] Each workspace can hold a limited number of unexpired API keys. Revoke a key you no longer use in the console (Settings → Developers), then create the new one. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This workspace already has the maximum number of active API keys.", "error": { "type": "conflict_error", "code": "api_key_limit_reached", "message": "This workspace already has the maximum number of active API keys.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/api_key_limit_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] Any endpoint can return this code. # api_key_route_forbidden (/errors/api_key_route_forbidden) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `api_key_route_forbidden` | ## What it means [#what-it-means] Some endpoints (for example account, billing, and key management) are only available from a signed-in dashboard session. Use the dashboard for this action. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "This endpoint cannot be called with an API key.", "error": { "type": "permission_error", "code": "api_key_route_forbidden", "message": "This endpoint cannot be called with an API key.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/api_key_route_forbidden", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] Any endpoint can return this code. # api_key_scope_denied (/errors/api_key_scope_denied) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `api_key_scope_denied` | ## What it means [#what-it-means] The key is missing the scope this endpoint needs (for example `calls:write`). Create a key with the required scope or add the scope to the existing key. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "The API key does not have the scope required for this request.", "error": { "type": "permission_error", "code": "api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # bad_request (/errors/bad_request) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `bad_request` | ## What it means [#what-it-means] The request was malformed or asked for something the resource does not allow in its current state. Read the message, correct the request, and try again. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The request could not be processed.", "error": { "type": "invalid_request_error", "code": "bad_request", "message": "The request could not be processed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/bad_request", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/leads/bulk` — Act on many leads - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `POST /api/v1/tickets/` — Create a ticket - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `POST /api/v1/agents/import` — Import an agent from another platform - `GET /api/v1/campaigns/` — List campaigns - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `PUT /api/v1/leads/{lead_id}` — Update a lead # call_not_found (/errors/call_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `call_not_found` | ## What it means [#what-it-means] No call with this id exists in your workspace, or it was deleted. List calls with `GET /calls` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Call not found.", "error": { "type": "not_found_error", "code": "call_not_found", "message": "Call not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/call_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript # call_recording_deleted (/errors/call_recording_deleted) | HTTP status | Type | Code | | --- | --- | --- | | 410 | `not_found_error` | `call_recording_deleted` | ## What it means [#what-it-means] Your workspace's data retention policy removed this recording. It cannot be restored; the transcript and summary stay on the call until they expire too. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "This recording was deleted under the data retention policy.", "error": { "type": "not_found_error", "code": "call_recording_deleted", "message": "This recording was deleted under the data retention policy.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/call_recording_deleted", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/calls/{call_id}/recording` — Download a call recording # call_recording_not_found (/errors/call_recording_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `call_recording_not_found` | ## What it means [#what-it-means] The call was not answered, recording was off, or the audio is still being saved. `hasRecording` on the call says when a recording exists; retry a minute after the call ends. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "No recording is available for this call.", "error": { "type": "not_found_error", "code": "call_recording_not_found", "message": "No recording is available for this call.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/call_recording_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/calls/{call_id}/recording` — Download a call recording # campaign_call_limit_reached (/errors/campaign_call_limit_reached) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_call_limit_reached` | ## What it means [#what-it-means] The campaign is already running as many calls as its phone numbers and its concurrency setting allow. The response includes `activeCallId`; retry when that call ends. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Campaign already has an active call in progress.", "error": { "type": "conflict_error", "code": "campaign_call_limit_reached", "message": "Campaign already has an active call in progress.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_call_limit_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # campaign_daily_cap_reached (/errors/campaign_daily_cap_reached) | HTTP status | Type | Code | | --- | --- | --- | | 429 | `rate_limit_error` | `campaign_daily_cap_reached` | ## What it means [#what-it-means] The campaign placed as many calls today as its daily limit allows. Raise the limit in the campaign settings or retry tomorrow. ## How to handle it [#how-to-handle-it] Wait for the number of seconds in the `Retry-After` header, then retry with exponential backoff and jitter. Spread bulk work over time. ## Example response [#example-response] ```json { "detail": "Daily call limit reached for this campaign.", "error": { "type": "rate_limit_error", "code": "campaign_daily_cap_reached", "message": "Daily call limit reached for this campaign.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_daily_cap_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # campaign_default_inbound_exists (/errors/campaign_default_inbound_exists) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_default_inbound_exists` | ## What it means [#what-it-means] A phone number has at most one default inbound campaign, which answers callers no other campaign claims. Send `isDefaultInbound: false`, or first turn it off on the other campaign with `PUT /campaigns/{campaignId}`. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Another default inbound campaign already exists for this phone number.", "error": { "type": "conflict_error", "code": "campaign_default_inbound_exists", "message": "Another default inbound campaign already exists for this phone number.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_default_inbound_exists", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign # campaign_dial_busy (/errors/campaign_dial_busy) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_dial_busy` | ## What it means [#what-it-means] Another call for this campaign is being placed at this moment. Wait a second and retry. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Campaign dial in progress.", "error": { "type": "conflict_error", "code": "campaign_dial_busy", "message": "Campaign dial in progress.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_dial_busy", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # campaign_has_no_agent (/errors/campaign_has_no_agent) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `campaign_has_no_agent` | ## What it means [#what-it-means] Calls need an agent to speak. Set `agentId` on the campaign with `PUT /campaigns/{campaignId}`, then retry. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "Campaign has no agent assigned.", "error": { "type": "invalid_request_error", "code": "campaign_has_no_agent", "message": "Campaign has no agent assigned.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_has_no_agent", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # campaign_leads_need_confirmation (/errors/campaign_leads_need_confirmation) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_leads_need_confirmation` | ## What it means [#what-it-means] Removing a lead that was already called archives it from the dial queue (its call history stays). `detail.leadIds` lists those leads; resend the request with `confirmRemovedContacted: true` to remove them anyway. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Some leads were already contacted in this campaign.", "error": { "type": "conflict_error", "code": "campaign_leads_need_confirmation", "message": "Some leads were already contacted in this campaign.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_leads_need_confirmation", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads # campaign_no_eligible_leads (/errors/campaign_no_eligible_leads) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_no_eligible_leads` | ## What it means [#what-it-means] Every lead on the campaign is already called, scheduled for a retry later, or blocked by the do-not-call list. `details` gives the total and eligible counts. Add leads with `PUT /campaigns/{campaignId}/leads`. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "No leads available for calling.", "error": { "type": "conflict_error", "code": "campaign_no_eligible_leads", "message": "No leads available for calling.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_no_eligible_leads", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # campaign_not_found (/errors/campaign_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `campaign_not_found` | ## What it means [#what-it-means] No campaign with this id exists in your workspace, or it was deleted. List your campaigns with `GET /campaigns` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Campaign not found.", "error": { "type": "not_found_error", "code": "campaign_not_found", "message": "Campaign not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/leads/` — Create a lead - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads # campaign_not_ready (/errors/campaign_not_ready) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `campaign_not_ready` | ## What it means [#what-it-means] The message lists what to fix first: the campaign has no agent, the agent's prompt uses placeholders the leads cannot fill, an IVR survey is missing its clips, or an inbound campaign has no callers or lead sources assigned. Fix it with `PUT /campaigns/{campaignId}` (or on the agent), then start again. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "campaign_not_ready", "message": "The campaign is not ready to start.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_ready", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign # campaign_not_running (/errors/campaign_not_running) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `campaign_not_running` | ## What it means [#what-it-means] The campaign is stopped, so it cannot place or resume calls. Start it with `POST /campaigns/{campaignId}/start`, then retry. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Campaign is not active.", "error": { "type": "conflict_error", "code": "campaign_not_running", "message": "Campaign is not active.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign # carrier_capacity_reached (/errors/carrier_capacity_reached) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `carrier_capacity_reached` | ## What it means [#what-it-means] The calling number or its carrier account is at its simultaneous or new-call limit. Nothing was charged; retry in a moment. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The phone number or carrier account is at its call limit.", "error": { "type": "conflict_error", "code": "carrier_capacity_reached", "message": "The phone number or carrier account is at its call limit.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/carrier_capacity_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # concurrent_call_limit_reached (/errors/concurrent_call_limit_reached) | HTTP status | Type | Code | | --- | --- | --- | | 429 | `rate_limit_error` | `concurrent_call_limit_reached` | ## What it means [#what-it-means] Your plan's limit on simultaneous calls is in use. Retry when a call ends, or upgrade the plan for more parallel calls. ## How to handle it [#how-to-handle-it] Wait for the number of seconds in the `Retry-After` header, then retry with exponential backoff and jitter. Spread bulk work over time. ## Example response [#example-response] ```json { "detail": "Merchant concurrent call limit reached.", "error": { "type": "rate_limit_error", "code": "concurrent_call_limit_reached", "message": "Merchant concurrent call limit reached.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/concurrent_call_limit_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # conflict (/errors/conflict) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `conflict` | ## What it means [#what-it-means] Another change already happened (for example a duplicate or a state that no longer allows this action). Fetch the resource again and retry if it still makes sense. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The request conflicts with the current state of the resource.", "error": { "type": "conflict_error", "code": "conflict", "message": "The request conflicts with the current state of the resource.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/conflict", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] Any endpoint can return this code. # daily_call_limit_reached (/errors/daily_call_limit_reached) | HTTP status | Type | Code | | --- | --- | --- | | 429 | `rate_limit_error` | `daily_call_limit_reached` | ## What it means [#what-it-means] The limit resets at 00:00 UTC; the `Retry-After` header gives the seconds until then. Use a campaign for large volumes, or contact support to raise the limit. ## How to handle it [#how-to-handle-it] Wait for the number of seconds in the `Retry-After` header, then retry with exponential backoff and jitter. Spread bulk work over time. ## Example response [#example-response] ```json { "detail": "Your workspace reached its daily limit for calls placed through the API.", "error": { "type": "rate_limit_error", "code": "daily_call_limit_reached", "message": "Your workspace reached its daily limit for calls placed through the API.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/daily_call_limit_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call # destination_not_allowed (/errors/destination_not_allowed) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `destination_not_allowed` | ## What it means [#what-it-means] `POST /calls` dials your workspace's home country (from your billing address; India when none is set). Contact support to enable more countries. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "destination_not_allowed", "message": "Calls to this country are not enabled for your workspace.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/destination_not_allowed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call # dial_failed (/errors/dial_failed) | HTTP status | Type | Code | | --- | --- | --- | | 502 | `api_error` | `dial_failed` | ## What it means [#what-it-means] The carrier could not be reached or returned an error. The failed call is recorded (`detail.call.id`); retry, and check the number's carrier credentials if it keeps failing. ## How to handle it [#how-to-handle-it] Retry with exponential backoff. If it keeps failing, contact support and include the `requestId` from the response. ## Example response [#example-response] ```json { "detail": "Failed to place outbound call.", "error": { "type": "api_error", "code": "dial_failed", "message": "Failed to place outbound call.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/dial_failed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # dial_rejected (/errors/dial_rejected) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `dial_rejected` | ## What it means [#what-it-means] The carrier refused the dial before it rang, usually because the destination or caller number is not valid for it. The message has the carrier's reason; the failed call is recorded and its id is in `detail.call.id`. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The carrier rejected the call.", "error": { "type": "invalid_request_error", "code": "dial_rejected", "message": "The carrier rejected the call.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/dial_rejected", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # dnc_no_valid_numbers (/errors/dnc_no_valid_numbers) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `dnc_no_valid_numbers` | ## What it means [#what-it-means] None of the numbers in `phones` is a valid Indian mobile number. Send 10-digit mobiles or +91 numbers, one per line or separated by commas. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "dnc_no_valid_numbers", "message": "Add at least one Indian mobile number.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/dnc_no_valid_numbers", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/dnc` — Add numbers to do-not-call # idempotency_key_reused (/errors/idempotency_key_reused) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `idempotency_error` | `idempotency_key_reused` | ## What it means [#what-it-means] An Idempotency-Key can only be reused with exactly the same method, path, and body within 24 hours. Generate a new key for a new request. It is also returned when the key already completed a request whose response held a one-time secret (such as a webhook signing secret): that response is never stored, so look the resource up instead. ## How to handle it [#how-to-handle-it] Send a new `Idempotency-Key` for a different request body, or wait for the first request with this key to finish and retry. ## Example response [#example-response] ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "type": "idempotency_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/leads/bulk` — Act on many leads - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `POST /api/v1/tickets/` — Create a ticket - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `POST /api/v1/agents/import` — Import an agent from another platform - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # idempotency_request_in_progress (/errors/idempotency_request_in_progress) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `idempotency_error` | `idempotency_request_in_progress` | ## What it means [#what-it-means] An earlier request with the same key has not finished yet. Wait a moment and retry with the same key to receive its result. ## How to handle it [#how-to-handle-it] Send a new `Idempotency-Key` for a different request body, or wait for the first request with this key to finish and retry. ## Example response [#example-response] ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "type": "idempotency_error", "code": "idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/leads/bulk` — Act on many leads - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `POST /api/v1/tickets/` — Create a ticket - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `POST /api/v1/agents/import` — Import an agent from another platform - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # Errors (/errors) Every error response uses an HTTP status code and the same JSON body: ```json { "detail": "Lead not found", "error": { "type": "not_found_error", "code": "lead_not_found", "message": "Lead not found", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` | Field | Meaning | | --- | --- | | `error.type` | The broad category (table below). Use it for generic handling. | | `error.code` | A specific, stable code such as `campaign_not_running`. **Branch on this.** Codes are never renamed once published. | | `error.message` | A human-readable explanation. Show or log it, but do not parse it; the wording can change. | | `error.param` | The request field that caused the error, when there is one (for example `phone`). Otherwise `null`. | | `error.docUrl` | Link to this code's page in these docs. | | `error.requestId` | The request's ID, also sent as the `X-Request-ID` header. Quote it when you contact support ([Request IDs](/request-ids)). | | `detail` | The earlier error format, kept for existing integrations: a message string, an object, or for `422` the list of field errors. New code should read `error`. | ## Error types [#error-types] | Type | Typical status | What to do | | --- | --- | --- | | `invalid_request_error` | 400, 405, 413, 422 | Fix the request. Retrying it unchanged fails the same way. | | `authentication_error` | 401 | Check the `X-API-Key` (or `Authorization: Bearer`) header; the key may be wrong, revoked or expired. | | `billing_error` | 402 | Top up or change the plan in the console. | | `permission_error` | 403 | The key or its user may not do this. Check the key's access and resources. | | `not_found_error` | 404 | The ID does not exist or belongs to another workspace. | | `conflict_error` | 409 | The resource is in a state that does not allow this. Fetch it again, then decide. | | `idempotency_error` | 409 | An `Idempotency-Key` was reused with a different body, or the first request is still running ([Idempotency](/idempotency)). | | `rate_limit_error` | 429 | Wait for `Retry-After` seconds, then retry ([Rate limits](/rate-limits)). | | `api_error` | 500, 503 | Something went wrong on our side. Retry with backoff. | ## Validation errors [#validation-errors] A `422` means a field is missing or invalid. `error.code` is `parameter_invalid`, `error.param` names the first offending field, and `detail` lists every problem: ```json { "detail": [ { "type": "missing", "loc": ["body", "phone"], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` ## Handling errors well [#handling-errors-well] - **Branch on `error.code`, then `error.type`, then the status.** Unknown codes can appear as the API grows; fall back to the type. - **Retry only what can succeed later:** `429`, `500`, `503`, `409` [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) (with the same `Idempotency-Key`), and network timeouts. Use exponential backoff with jitter. For `POST` requests, send an [`Idempotency-Key`](/idempotency) where the endpoint supports it so a retry cannot act twice. - **Do not retry `4xx` errors** other than `429` without changing the request. - **Honour `Retry-After`** when a response carries it. - **Log `requestId`** with every failure. ```bash curl -sS https://api.callmitra.ai/api/v1/leads/00000000-0000-0000-0000-000000000000 \ -H "X-API-Key: $CALLMITRA_API_KEY" | jq '.error' ``` ```js const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }); if (!res.ok) { const { error } = await res.json(); if (res.status === 429 || res.status >= 500) { // retry later with backoff; honour Retry-After when present } throw new Error(`${error.code}: ${error.message} (request ${error.requestId})`); } ``` ```python res = requests.get(url, headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30) if not res.ok: error = res.json()["error"] if res.status_code == 429 or res.status_code >= 500: pass # retry later with backoff; honour Retry-After when present raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})") ``` ## Calling refusals [#calling-refusals] [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow), [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) and [`POST /api/v1/calls/`](/api-reference/calls/createCall) are refused for business reasons as well as technical ones. Each refusal has its own code. `error.message` is safe to show to a person, and `detail` keeps the earlier message format. | Status | Code | When | | --- | --- | --- | | `400` | [`campaign_has_no_agent`](/errors/campaign_has_no_agent) | The campaign has no agent. Set `agentId` on the campaign. | | `400` | [`dial_rejected`](/errors/dial_rejected) | The carrier refused the call before it rang. The failed call is in `detail.call.id`. | | `400` | [`bad_request`](/errors/bad_request) | Any other refusal. Read the message. | | `402` | [`payment_required`](/errors/payment_required) | The workspace is out of balance or has no plan. | | `404` | [`campaign_not_found`](/errors/campaign_not_found) | No such campaign in your workspace. | | `404` | [`lead_not_found`](/errors/lead_not_found) | No such lead in your workspace. | | `404` | [`lead_not_on_campaign`](/errors/lead_not_on_campaign) | The lead is not an active member of the campaign. | | `404` | [`phone_number_not_found`](/errors/phone_number_not_found) | `createCall`: the phone number is not connected to your workspace. | | `409` | [`campaign_not_running`](/errors/campaign_not_running) | The campaign is stopped. Start it, then retry. Resuming a stopped campaign returns it too. | | `409` | [`number_on_dnc`](/errors/number_on_dnc) | The number is on your do-not-call list. | | `409` | [`lead_call_in_progress`](/errors/lead_call_in_progress) | A call to this lead is still ringing or connected. | | `409` | [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) | The campaign is running as many calls as it allows. `activeCallId` names the call in progress. | | `409` | [`campaign_dial_busy`](/errors/campaign_dial_busy) | Another call for this campaign is being placed at this moment. | | `409` | [`carrier_capacity_reached`](/errors/carrier_capacity_reached) | The calling number or carrier account is at its call limit. Nothing was charged. | | `409` | [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) | No lead on the campaign can be called now. | | `422` | [`lead_has_no_campaign`](/errors/lead_has_no_campaign) | `callLeadNow`: the lead is on no outbound campaign. | | `422` | [`invalid_phone_number`](/errors/invalid_phone_number) | `createCall`: the number to call is not valid. | | `429` | [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) | Your plan's simultaneous call limit is in use. | | `429` | [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) | The campaign reached its daily call limit. | | `502` | [`dial_failed`](/errors/dial_failed) | The carrier could not be reached. The failed call is in `detail.call.id`. | `lead_call_in_progress`, `campaign_call_limit_reached`, `campaign_dial_busy`, `carrier_capacity_reached` and `concurrent_call_limit_reached` clear on their own, so retrying after a short wait can succeed. Retry `dial_failed` with backoff. New codes may be added; handle an unknown code by falling back to `error.type`. See [Calling in India](/guides/india-calling) for calling windows and do-not-call rules. ## All error codes [#all-error-codes] Each endpoint in the [API reference](/api-reference) lists the codes it can return under its responses. The full catalogue: # internal_error (/errors/internal_error) | HTTP status | Type | Code | | --- | --- | --- | | 500 | `api_error` | `internal_error` | ## What it means [#what-it-means] An unexpected error occurred. Retry the request; if it keeps failing, contact support with the `requestId` from the error. ## How to handle it [#how-to-handle-it] Retry with exponential backoff. If it keeps failing, contact support and include the `requestId` from the response. ## Example response [#example-response] ```json { "detail": "Something went wrong on our side.", "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/internal_error", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # invalid_api_key (/errors/invalid_api_key) | HTTP status | Type | Code | | --- | --- | --- | | 401 | `authentication_error` | `invalid_api_key` | ## What it means [#what-it-means] The API key was not recognised. Check that you copied the full key, that it has not been revoked, and that you are calling the right environment. ## How to handle it [#how-to-handle-it] Check that the `X-API-Key` header carries a current key. Create a new key in the console (**Settings → Developers**) if this one was revoked or expired. Do not retry in a loop. ## Example response [#example-response] ```json { "detail": "The API key is invalid or has been revoked.", "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # invalid_phone_number (/errors/invalid_phone_number) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `invalid_phone_number` | ## What it means [#what-it-means] Send the number in E.164 format: a leading `+`, the country code, then the number, for example `+919812345678`. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "invalid_phone_number", "message": "The phone number is not valid.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call - `POST /api/v1/leads/` — Create a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead # lead_call_in_progress (/errors/lead_call_in_progress) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `lead_call_in_progress` | ## What it means [#what-it-means] A call to this lead is still ringing or connected. Retry after it ends. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Lead already has an active call.", "error": { "type": "conflict_error", "code": "lead_call_in_progress", "message": "Lead already has an active call.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads # lead_changed (/errors/lead_changed) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `lead_changed` | ## What it means [#what-it-means] You sent `If-Match` with the lead's `updatedAt`, and someone changed the lead after that. Read it again with `GET /leads/{leadId}`, reapply your change, and retry with the new `updatedAt`. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This lead changed since you opened it.", "error": { "type": "conflict_error", "code": "lead_changed", "message": "This lead changed since you opened it.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_changed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `PUT /api/v1/leads/{lead_id}` — Update a lead # lead_has_no_campaign (/errors/lead_has_no_campaign) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `lead_has_no_campaign` | ## What it means [#what-it-means] Calling a lead uses the settings of its campaign. Add the lead to an outbound campaign first. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "lead_has_no_campaign", "message": "Lead is not on a campaign.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/lead_has_no_campaign", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now # lead_not_found (/errors/lead_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `lead_not_found` | ## What it means [#what-it-means] No lead with this id exists in your workspace, or it was deleted. Find leads with `GET /leads` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Lead not found.", "error": { "type": "not_found_error", "code": "lead_not_found", "message": "Lead not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `GET /api/v1/leads/{lead_id}` — Get a lead - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `PUT /api/v1/leads/{lead_id}` — Update a lead - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note # lead_not_on_campaign (/errors/lead_not_on_campaign) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `lead_not_on_campaign` | ## What it means [#what-it-means] The lead is not an active member of this campaign. Add it with `PUT /campaigns/{campaignId}/leads` or pick a lead from `GET /campaigns/{campaignId}/leads`. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Lead is not on this campaign.", "error": { "type": "not_found_error", "code": "lead_not_on_campaign", "message": "Lead is not on this campaign.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_not_on_campaign", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # lead_note_changed (/errors/lead_note_changed) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `lead_note_changed` | ## What it means [#what-it-means] The `version` you sent is not the note's current version. `detail.note` holds the current note; reapply your edit to it and retry with its `version`. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This note was changed by someone else.", "error": { "type": "conflict_error", "code": "lead_note_changed", "message": "This note was changed by someone else.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_note_changed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note # lead_note_not_found (/errors/lead_note_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `lead_note_not_found` | ## What it means [#what-it-means] No note with this id exists on the lead, or it was deleted. List the lead's notes with `GET /leads/{leadId}/notes`. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Note not found.", "error": { "type": "not_found_error", "code": "lead_note_not_found", "message": "Note not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_note_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note # lead_note_pin_limit (/errors/lead_note_pin_limit) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `lead_note_pin_limit` | ## What it means [#what-it-means] Unpin another note with `DELETE /leads/{leadId}/notes/{noteId}/pin`, then pin this one. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "A lead can have at most 3 pinned notes.", "error": { "type": "conflict_error", "code": "lead_note_pin_limit", "message": "A lead can have at most 3 pinned notes.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/lead_note_pin_limit", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note # method_not_allowed (/errors/method_not_allowed) | HTTP status | Type | Code | | --- | --- | --- | | 405 | `invalid_request_error` | `method_not_allowed` | ## What it means [#what-it-means] The endpoint exists but does not accept this HTTP method. Check the API reference for the methods it supports. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "This HTTP method is not allowed on this endpoint.", "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "This HTTP method is not allowed on this endpoint.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/method_not_allowed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] Any endpoint can return this code. # number_on_dnc (/errors/number_on_dnc) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `number_on_dnc` | ## What it means [#what-it-means] The lead opted out or its number is on your do-not-call list. Remove it with `DELETE /leads/dnc/{leadId}` only if the person agreed to be called again. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This number is on the DNC list and will not be dialed.", "error": { "type": "conflict_error", "code": "number_on_dnc", "message": "This number is on the DNC list and will not be dialed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/number_on_dnc", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/calls/` — Place a call # parameter_invalid (/errors/parameter_invalid) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `parameter_invalid` | ## What it means [#what-it-means] A field is missing, has the wrong type, or has a value outside the allowed range. `error.param` names the first offending field and `detail` lists every problem. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/leads/bulk` — Act on many leads - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `POST /api/v1/tickets/` — Create a ticket - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/agents/{agent_id}` — Get an agent - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/leads/{lead_id}` — Get a lead - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `POST /api/v1/agents/import` — Import an agent from another platform - `GET /api/v1/agents/` — List agents - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `GET /api/v1/campaigns/` — List campaigns - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `GET /api/v1/leads/` — List leads - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/` — List tickets - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `PUT /api/v1/leads/{lead_id}` — Update a lead - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint # payload_too_large (/errors/payload_too_large) | HTTP status | Type | Code | | --- | --- | --- | | 413 | `invalid_request_error` | `payload_too_large` | ## What it means [#what-it-means] The body or uploaded file is larger than this endpoint accepts. Send a smaller payload or split it into several requests. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The request body is too large.", "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The request body is too large.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/payload_too_large", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `PATCH /api/v1/agents/{agent_id}` — Update an agent # payment_required (/errors/payment_required) | HTTP status | Type | Code | | --- | --- | --- | | 402 | `billing_error` | `payment_required` | ## What it means [#what-it-means] The workspace is out of credit or its plan does not cover this action. Top up the balance or upgrade the plan, then retry. ## How to handle it [#how-to-handle-it] Top up the workspace balance or change the plan in the console, then retry. ## Example response [#example-response] ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "type": "billing_error", "code": "payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/payment_required", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/calls/` — Place a call - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/agents/import` — Import an agent from another platform - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign # permission_denied (/errors/permission_denied) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `permission_denied` | ## What it means [#what-it-means] The credentials are valid but the user or key is not allowed to do this, or the resource belongs to another workspace. Ask a workspace admin for access. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "You do not have permission to perform this action.", "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to perform this action.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # phone_number_not_dialable (/errors/phone_number_not_dialable) | HTTP status | Type | Code | | --- | --- | --- | | 422 | `invalid_request_error` | `phone_number_not_dialable` | ## What it means [#what-it-means] The number is inactive, has no E.164 number, or is missing its carrier credentials or SIP trunk. The message says which; fix the number in the console and retry. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": [ { "type": "missing", "loc": [ "body", "phone" ], "msg": "Field required" } ], "error": { "type": "invalid_request_error", "code": "phone_number_not_dialable", "message": "This phone number cannot place calls.", "param": "phone", "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_dialable", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call # phone_number_not_found (/errors/phone_number_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `phone_number_not_found` | ## What it means [#what-it-means] No phone number with this id is connected to your workspace. List your numbers with `GET /phone-numbers` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Phone number not found.", "error": { "type": "not_found_error", "code": "phone_number_not_found", "message": "Phone number not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call # rate_limit_exceeded (/errors/rate_limit_exceeded) | HTTP status | Type | Code | | --- | --- | --- | | 429 | `rate_limit_error` | `rate_limit_exceeded` | ## What it means [#what-it-means] You sent more requests than your limit allows. Wait for the number of seconds in the `Retry-After` header; the `RateLimit-*` headers show your current budget. ## How to handle it [#how-to-handle-it] Wait for the number of seconds in the `Retry-After` header, then retry with exponential backoff and jitter. Spread bulk work over time. ## Example response [#example-response] ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # resource_not_found (/errors/resource_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `resource_not_found` | ## What it means [#what-it-means] The URL or the id in it does not match anything your workspace can see. Check the id and the endpoint path. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "The requested resource was not found.", "error": { "type": "not_found_error", "code": "resource_not_found", "message": "The requested resource was not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket # service_unavailable (/errors/service_unavailable) | HTTP status | Type | Code | | --- | --- | --- | | 503 | `api_error` | `service_unavailable` | ## What it means [#what-it-means] A dependency is down or the service is overloaded. Retry after a short wait, with backoff. ## How to handle it [#how-to-handle-it] Retry with exponential backoff. If it keeps failing, contact support and include the `requestId` from the response. ## Example response [#example-response] ```json { "detail": "The service is temporarily unavailable.", "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/service_unavailable", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/calls/` — Place a call # sip_trunk_not_found (/errors/sip_trunk_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `sip_trunk_not_found` | ## What it means [#what-it-means] No SIP trunk with this id exists in your workspace. List trunks with `GET /sip-trunks`. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "SIP trunk not found.", "error": { "type": "not_found_error", "code": "sip_trunk_not_found", "message": "SIP trunk not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/sip_trunk_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk # ticket_attachment_unavailable (/errors/ticket_attachment_unavailable) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `ticket_attachment_unavailable` | ## What it means [#what-it-means] One of the `attachmentIds` was attached to another note or reply, or removed, while this request ran (for example a double submit). Nothing was saved. Fetch the ticket again and resend without that attachment. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "An attachment was already sent or removed.", "error": { "type": "conflict_error", "code": "ticket_attachment_unavailable", "message": "An attachment was already sent or removed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_attachment_unavailable", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer # ticket_edit_forbidden (/errors/ticket_edit_forbidden) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `ticket_edit_forbidden` | ## What it means [#what-it-means] The user that owns this API key is an agent, and the ticket is assigned to someone else. Use a key created by a manager, or assign the ticket to the key's user first. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "You can only update tickets assigned to you or unassigned.", "error": { "type": "permission_error", "code": "ticket_edit_forbidden", "message": "You can only update tickets assigned to you or unassigned.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_edit_forbidden", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket # ticket_merged (/errors/ticket_merged) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `ticket_merged` | ## What it means [#what-it-means] A merged ticket is read-only; its history continues on the ticket it was merged into. The message names that ticket; send the update there instead. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The ticket was merged into another ticket.", "error": { "type": "conflict_error", "code": "ticket_merged", "message": "The ticket was merged into another ticket.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_merged", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket # ticket_reopen_forbidden (/errors/ticket_reopen_forbidden) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `ticket_reopen_forbidden` | ## What it means [#what-it-means] Moving a closed ticket back to an open status needs a manager. Use a key created by a manager, or create a new ticket for the new request. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "Only a manager can reopen a closed ticket.", "error": { "type": "permission_error", "code": "ticket_reopen_forbidden", "message": "Only a manager can reopen a closed ticket.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_reopen_forbidden", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket # ticket_reply_blocked (/errors/ticket_reply_blocked) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `ticket_reply_blocked` | ## What it means [#what-it-means] Nothing was sent. `detail.code` says why: `replies_off` (customer replies are turned off in ticket settings), `no_number` or `number_offline` (no connected WhatsApp number to reply from), `no_phone` (the lead has no valid phone number), `dnc` (the customer is on do-not-contact), `opted_out` (the customer opted out of WhatsApp), `window_closed` (the 24-hour window is closed: send `templateEvent` instead of text), or another reason in `detail.message`. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The reply cannot be sent to the customer.", "error": { "type": "conflict_error", "code": "ticket_reply_blocked", "message": "The reply cannot be sent to the customer.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_reply_blocked", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer # ticket_version_conflict (/errors/ticket_version_conflict) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `ticket_version_conflict` | ## What it means [#what-it-means] You sent `version`, and someone else updated the ticket after that version. Fetch the ticket again with `GET /tickets/{ticket_id}`, re-apply your change and send the new `version`. Leave `version` out to skip this check. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The ticket was changed since you read it.", "error": { "type": "conflict_error", "code": "ticket_version_conflict", "message": "The ticket was changed since you read it.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/ticket_version_conflict", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket # tool_not_found (/errors/tool_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `tool_not_found` | ## What it means [#what-it-means] No tool with this id exists in your workspace. List your tools with `GET /tools`. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Tool not found.", "error": { "type": "not_found_error", "code": "tool_not_found", "message": "Tool not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/tool_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/tools/{tool_id}` — Get a tool # unauthenticated (/errors/unauthenticated) | HTTP status | Type | Code | | --- | --- | --- | | 401 | `authentication_error` | `unauthenticated` | ## What it means [#what-it-means] No valid credentials were sent. Send your API key in the `Authorization: Bearer ` header (or sign in again if you are using a browser session). ## How to handle it [#how-to-handle-it] Check that the `X-API-Key` header carries a current key. Create a new key in the console (**Settings → Developers**) if this one was revoked or expired. Do not retry in a loop. ## Example response [#example-response] ```json { "detail": "Authentication required.", "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Authentication required.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/agency/clients` — List client workspaces - `GET /api/v1/agents/` — List agents - `POST /api/v1/agents/` — Create an agent - `POST /api/v1/agents/import` — Import an agent from another platform - `DELETE /api/v1/agents/{agent_id}` — Delete an agent - `GET /api/v1/agents/{agent_id}` — Get an agent - `PATCH /api/v1/agents/{agent_id}` — Update an agent - `POST /api/v1/agents/{agent_id}/go-live` — Start taking calls - `POST /api/v1/agents/{agent_id}/pause` — Stop taking calls - `PUT /api/v1/agents/{agent_id}/post-call-webhook` — Set an agent's post-call webhook - `POST /api/v1/agents/{agent_id}/publish` — Publish the agent's draft - `POST /api/v1/agents/{agent_id}/test-call` — Place a test call - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/calls/` — List calls - `POST /api/v1/calls/` — Place a call - `GET /api/v1/calls/daily-counts` — Calls per day - `GET /api/v1/calls/performance` — Call performance - `GET /api/v1/calls/{call_id}` — Get a call - `GET /api/v1/calls/{call_id}/recording` — Download a call recording - `GET /api/v1/calls/{call_id}/transcript` — Get a call transcript - `GET /api/v1/campaigns/` — List campaigns - `POST /api/v1/campaigns/` — Create an empty campaign - `POST /api/v1/campaigns/create-with-leads` — Create a campaign with its leads - `DELETE /api/v1/campaigns/{campaign_id}` — Delete a campaign - `GET /api/v1/campaigns/{campaign_id}` — Get a campaign - `PUT /api/v1/campaigns/{campaign_id}` — Update a campaign - `GET /api/v1/campaigns/{campaign_id}/dial-status` — Dialing status - `GET /api/v1/campaigns/{campaign_id}/leads` — List a campaign's leads - `PUT /api/v1/campaigns/{campaign_id}/leads` — Add or remove leads - `POST /api/v1/campaigns/{campaign_id}/pause-dialing` — Pause automatic dialing - `POST /api/v1/campaigns/{campaign_id}/resume-dialing` — Resume automatic dialing - `POST /api/v1/campaigns/{campaign_id}/start` — Start a campaign - `POST /api/v1/campaigns/{campaign_id}/stop` — Stop a campaign - `POST /api/v1/instant/call-now` — Call a lead in a campaign now - `GET /api/v1/lead-fields/catalog` — List custom lead fields - `GET /api/v1/leads/` — List leads - `POST /api/v1/leads/` — Create a lead - `POST /api/v1/leads/bulk` — Act on many leads - `GET /api/v1/leads/dnc` — List do-not-call numbers - `POST /api/v1/leads/dnc` — Add numbers to do-not-call - `DELETE /api/v1/leads/dnc/{lead_id}` — Remove a number from do-not-call - `DELETE /api/v1/leads/{lead_id}` — Delete a lead - `GET /api/v1/leads/{lead_id}` — Get a lead - `PUT /api/v1/leads/{lead_id}` — Update a lead - `POST /api/v1/leads/{lead_id}/call-now` — Call a lead now - `GET /api/v1/leads/{lead_id}/notes` — List a lead's notes - `POST /api/v1/leads/{lead_id}/notes` — Add a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}` — Delete a note - `PATCH /api/v1/leads/{lead_id}/notes/{note_id}` — Edit a note - `DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Unpin a note - `POST /api/v1/leads/{lead_id}/notes/{note_id}/pin` — Pin a note - `GET /api/v1/leads/{lead_id}/timeline` — Lead timeline - `GET /api/v1/phone-numbers/` — List phone numbers - `GET /api/v1/phone-numbers/{phone_id}` — Get a phone number - `GET /api/v1/sip-trunks` — List SIP trunks - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/tickets/` — List tickets - `POST /api/v1/tickets/` — Create a ticket - `GET /api/v1/tickets/categories` — List ticket categories - `GET /api/v1/tickets/teams` — List ticket teams - `GET /api/v1/tickets/{ticket_id}` — Get a ticket - `PATCH /api/v1/tickets/{ticket_id}` — Update a ticket - `GET /api/v1/tickets/{ticket_id}/activities` — List ticket activities - `POST /api/v1/tickets/{ticket_id}/activities` — Add a note to a ticket - `POST /api/v1/tickets/{ticket_id}/replies` — Reply to the customer - `GET /api/v1/tools/` — List tools - `GET /api/v1/tools/{tool_id}` — Get a tool - `GET /api/v1/usage` — Get usage and balance - `GET /api/v1/voices/` — List voices - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `GET /api/v1/webhook-endpoints/` — List webhook endpoints - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `GET /api/v1/webhook-event-types/` — List event types - `GET /api/v1/whatsapp/message-templates` — List WhatsApp templates - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message - `GET /api/v1/whatsapp/messages/{message_id}` — Get a WhatsApp message - `GET /api/v1/workspace` — Check an API key # webhook_delivery_not_found (/errors/webhook_delivery_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `webhook_delivery_not_found` | ## What it means [#what-it-means] No delivery with this id exists in your workspace. Deliveries are kept for 30 days; list recent ones with `GET /webhook-deliveries`. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Webhook delivery not found.", "error": { "type": "not_found_error", "code": "webhook_delivery_not_found", "message": "Webhook delivery not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_delivery_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/webhook-deliveries/{delivery_id}` — Get a webhook delivery - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event # webhook_endpoint_disabled (/errors/webhook_endpoint_disabled) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `webhook_endpoint_disabled` | ## What it means [#what-it-means] Deliveries are not sent to a disabled endpoint. Enable it with `PATCH /webhook-endpoints/{id}` and `"enabled": true`, then try again. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The webhook endpoint is disabled.", "error": { "type": "conflict_error", "code": "webhook_endpoint_disabled", "message": "The webhook endpoint is disabled.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_disabled", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` — Redeliver an event - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event # webhook_endpoint_limit_reached (/errors/webhook_endpoint_limit_reached) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `webhook_endpoint_limit_reached` | ## What it means [#what-it-means] A workspace can have up to 20 webhook endpoints. Delete one you no longer use, or subscribe an existing endpoint to more event types. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This workspace already has the maximum number of webhook endpoints.", "error": { "type": "conflict_error", "code": "webhook_endpoint_limit_reached", "message": "This workspace already has the maximum number of webhook endpoints.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_limit_reached", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint # webhook_endpoint_not_found (/errors/webhook_endpoint_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `webhook_endpoint_not_found` | ## What it means [#what-it-means] No webhook endpoint with this id exists in your workspace, or it was deleted. List endpoints with `GET /webhook-endpoints` and use one of the returned ids. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Webhook endpoint not found.", "error": { "type": "not_found_error", "code": "webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `DELETE /api/v1/webhook-endpoints/{endpoint_id}` — Delete a webhook endpoint - `GET /api/v1/webhook-endpoints/{endpoint_id}` — Get a webhook endpoint - `GET /api/v1/webhook-deliveries/` — List webhook deliveries - `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` — Rotate an endpoint's signing secret - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint # webhook_event_type_unknown (/errors/webhook_event_type_unknown) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `webhook_event_type_unknown` | ## What it means [#what-it-means] Every entry in `events` must be an event type from `GET /webhook-event-types`. Send an empty list to receive every event type. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "One or more event types are not recognised.", "error": { "type": "invalid_request_error", "code": "webhook_event_type_unknown", "message": "One or more event types are not recognised.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_event_type_unknown", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint # webhook_https_required (/errors/webhook_https_required) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `webhook_https_required` | ## What it means [#what-it-means] Webhook payloads carry customer data, so endpoints must use TLS. Change the URL to start with `https://`. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The webhook URL must use https.", "error": { "type": "invalid_request_error", "code": "webhook_https_required", "message": "The webhook URL must use https.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_https_required", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint # webhook_url_invalid (/errors/webhook_url_invalid) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `webhook_url_invalid` | ## What it means [#what-it-means] Use an absolute `https://` URL whose host resolves to a public internet address. Private, loopback and link-local addresses are refused, as are URLs with a username or password. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "The webhook URL is not a valid public URL.", "error": { "type": "invalid_request_error", "code": "webhook_url_invalid", "message": "The webhook URL is not a valid public URL.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_url_invalid", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `PATCH /api/v1/webhook-endpoints/{endpoint_id}` — Update a webhook endpoint # webhook_workspace_required (/errors/webhook_workspace_required) | HTTP status | Type | Code | | --- | --- | --- | | 403 | `permission_error` | `webhook_workspace_required` | ## What it means [#what-it-means] Webhook settings belong to one workspace. Sign in as a member of that workspace, or use an API key created in it. ## How to handle it [#how-to-handle-it] The key or user is valid but not allowed to do this. Check the key’s access level and resources (read-only keys can only send `GET`), or ask a workspace manager. ## Example response [#example-response] ```json { "detail": "Webhooks are managed inside a workspace.", "error": { "type": "permission_error", "code": "webhook_workspace_required", "message": "Webhooks are managed inside a workspace.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/webhook_workspace_required", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/webhook-endpoints/` — Create a webhook endpoint - `POST /api/v1/webhook-endpoints/{endpoint_id}/test` — Send a test event # whatsapp_client_message_id_reused (/errors/whatsapp_client_message_id_reused) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_client_message_id_reused` | ## What it means [#what-it-means] The `Idempotency-Key` (or the message id of a retried send) already belongs to a message sent to another customer or from another number, so nothing was sent. Use a new key for each new message. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "This message id was already used for a different conversation.", "error": { "type": "conflict_error", "code": "whatsapp_client_message_id_reused", "message": "This message id was already used for a different conversation.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_client_message_id_reused", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_marketing_opted_out (/errors/whatsapp_marketing_opted_out) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_marketing_opted_out` | ## What it means [#what-it-means] The customer turned off promotional messages from your business in WhatsApp. Marketing templates are refused; utility and authentication templates still go through. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The recipient stopped marketing messages.", "error": { "type": "conflict_error", "code": "whatsapp_marketing_opted_out", "message": "The recipient stopped marketing messages.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_marketing_opted_out", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_number_not_connected (/errors/whatsapp_number_not_connected) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_number_not_connected` | ## What it means [#what-it-means] Your workspace has no WhatsApp Business number that can send, or the `phoneId` you sent is not one of your connected numbers. Finish connecting a number in the console (WhatsApp → Numbers), or leave `phoneId` out to send from your default number. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "No connected WhatsApp number.", "error": { "type": "conflict_error", "code": "whatsapp_number_not_connected", "message": "No connected WhatsApp number.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_number_not_connected", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_opt_in_required (/errors/whatsapp_opt_in_required) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_opt_in_required` | ## What it means [#what-it-means] The recipient has not opted in to WhatsApp messages from you. Collect consent first and send it in `optIn` (`source`, and the consent `text` the customer agreed to) with the message, or use a utility or authentication template. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "Marketing templates need a recorded opt-in.", "error": { "type": "conflict_error", "code": "whatsapp_opt_in_required", "message": "Marketing templates need a recorded opt-in.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_opt_in_required", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_recipient_opted_out (/errors/whatsapp_recipient_opted_out) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_recipient_opted_out` | ## What it means [#what-it-means] The customer asked to stop receiving WhatsApp messages from you, so nothing was sent. Do not retry; the opt-out is cleared only when the customer opts in again. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The recipient opted out of WhatsApp messages.", "error": { "type": "conflict_error", "code": "whatsapp_recipient_opted_out", "message": "The recipient opted out of WhatsApp messages.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_recipient_opted_out", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_template_not_approved (/errors/whatsapp_template_not_approved) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_template_not_approved` | ## What it means [#what-it-means] Only templates WhatsApp has approved can be sent. The message says the current status (for example PENDING, REJECTED or PAUSED). Wait for approval or fix the template, then retry. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The template is not approved.", "error": { "type": "conflict_error", "code": "whatsapp_template_not_approved", "message": "The template is not approved.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_approved", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_template_not_found (/errors/whatsapp_template_not_found) | HTTP status | Type | Code | | --- | --- | --- | | 404 | `not_found_error` | `whatsapp_template_not_found` | ## What it means [#what-it-means] No template with this name and language exists on the WhatsApp Business account of the sending number. Check the exact name and language code with `GET /whatsapp/message-templates`; a template created in WhatsApp Manager appears there after a template sync in the console. ## How to handle it [#how-to-handle-it] Check the ID in the path. It may be wrong, deleted, or belong to another workspace; the API answers 404 rather than revealing other workspaces’ data. ## Example response [#example-response] ```json { "detail": "Template not found.", "error": { "type": "not_found_error", "code": "whatsapp_template_not_found", "message": "Template not found.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_found", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_upstream_throttled (/errors/whatsapp_upstream_throttled) | HTTP status | Type | Code | | --- | --- | --- | | 429 | `rate_limit_error` | `whatsapp_upstream_throttled` | ## What it means [#what-it-means] WhatsApp refused the message because of a sending limit and nothing was delivered. Wait for the number of seconds in the `Retry-After` header and retry with the same `Idempotency-Key`. ## How to handle it [#how-to-handle-it] Wait for the number of seconds in the `Retry-After` header, then retry with exponential backoff and jitter. Spread bulk work over time. ## Example response [#example-response] ```json { "detail": "WhatsApp is limiting messages from this number right now.", "error": { "type": "rate_limit_error", "code": "whatsapp_upstream_throttled", "message": "WhatsApp is limiting messages from this number right now.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_throttled", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_upstream_unavailable (/errors/whatsapp_upstream_unavailable) | HTTP status | Type | Code | | --- | --- | --- | | 503 | `api_error` | `whatsapp_upstream_unavailable` | ## What it means [#what-it-means] WhatsApp had a temporary problem and did not accept the message, so nothing was delivered. Retry after the `Retry-After` header with the same `Idempotency-Key`. ## How to handle it [#how-to-handle-it] Retry with exponential backoff. If it keeps failing, contact support and include the `requestId` from the response. ## Example response [#example-response] ```json { "detail": "WhatsApp could not take the message right now.", "error": { "type": "api_error", "code": "whatsapp_upstream_unavailable", "message": "WhatsApp could not take the message right now.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_unavailable", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # whatsapp_window_closed (/errors/whatsapp_window_closed) | HTTP status | Type | Code | | --- | --- | --- | | 409 | `conflict_error` | `whatsapp_window_closed` | ## What it means [#what-it-means] Free-form messages (text, media, interactive, location, contacts) can only be sent within 24 hours of the customer's last message. Send an approved template instead; the window opens again when the customer replies. ## How to handle it [#how-to-handle-it] Fetch the resource again to see its current state, then decide whether to retry. ## Example response [#example-response] ```json { "detail": "The 24-hour customer service window is closed.", "error": { "type": "conflict_error", "code": "whatsapp_window_closed", "message": "The 24-hour customer service window is closed.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/whatsapp_window_closed", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `POST /api/v1/whatsapp/messages` — Send a WhatsApp message # workspace_required (/errors/workspace_required) | HTTP status | Type | Code | | --- | --- | --- | | 400 | `invalid_request_error` | `workspace_required` | ## What it means [#what-it-means] This endpoint works on one workspace's data, and the caller is not acting inside a workspace (for example a platform admin session). Use an API key or sign in to a workspace. ## How to handle it [#how-to-handle-it] Fix the request before sending it again; retrying the same request returns the same error. `error.param` names the offending field when there is one. ## Example response [#example-response] ```json { "detail": "Merchant workspace required", "error": { "type": "invalid_request_error", "code": "workspace_required", "message": "Merchant workspace required", "param": null, "docUrl": "https://docs.callmitra.ai/errors/workspace_required", "requestId": "req_3f9c2a7d1b8e4c6a9f0e2d4b6a8c0e1f" } } ``` Branch on `error.code`; it never changes once published. The `message` text can change. See [Errors](/errors) for the envelope. ## Returned by [#returned-by] - `GET /api/v1/sip-trunks/{trunk_id}` — Get a SIP trunk - `GET /api/v1/callbacks` — List scheduled callbacks - `GET /api/v1/sip-trunks` — List SIP trunks # Agencies & client workspaces (/guides/agencies) An agency runs CallMitra for several businesses. Each business gets its own **client workspace** under the agency, and the agency's integration reaches all of them with one API key. ## The model [#the-model] - An **agency** workspace can own **client workspaces**. There is one level only: agency → client. A client workspace cannot have clients of its own. - Each client workspace has its own leads, campaigns, agents, numbers, webhooks and usage. Data never mixes between clients, or between a client and the agency. - Agency managers create, suspend, resume, detach and delete client workspaces in the console under **Settings → Workspaces**. These changes are console-only. - Working inside a client workspace, in the console or through the API, opens an audited **acting session**. It is recorded in both the agency's and the client's audit logs. ## One key, many workspaces [#one-key-many-workspaces] Create the key in the **agency** workspace ([Authentication](/authentication)). To act in a client workspace, send the client's workspace ID in the `X-Workspace-Id` header: ```bash curl https://api.callmitra.ai/api/v1/campaigns/ \ -H "X-API-Key: $AGENCY_API_KEY" \ -H "X-Workspace-Id: 3f2b6c1e-8a4d-4f7e-9b2a-1c5d7e9f0a12" ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/', { headers: { 'X-API-Key': process.env.CALLMITRA_AGENCY_KEY, 'X-Workspace-Id': clientWorkspaceId, }, }); ``` ```python res = requests.get( "https://api.callmitra.ai/api/v1/campaigns/", headers={ "X-API-Key": os.environ["CALLMITRA_AGENCY_KEY"], "X-Workspace-Id": client_workspace_id, }, timeout=30, ) ``` The request then runs exactly as if it were made inside the client workspace: it reads and writes only that client's data, and anything it creates belongs to the client. | `X-Workspace-Id` | Result | | --- | --- | | Not sent, empty, or the agency's own ID | The key works in the agency workspace. | | A live client workspace of this agency | The request runs inside that client workspace. | | Anything else: another agency's client, an unrelated workspace, a deleted or detached client, not a UUID | `403` [`permission_denied`](/errors/permission_denied), message `This API key cannot work in that workspace.` | | A client workspace that is suspended | `409` [`conflict`](/errors/conflict), message `This client workspace is not active`. | The API never answers `404` for a workspace it refuses, so a key cannot be used to discover which workspace IDs exist. ```json { "detail": "This API key cannot work in that workspace.", "error": { "type": "permission_error", "code": "permission_denied", "message": "This API key cannot work in that workspace.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` ## Finding a client's workspace ID [#finding-a-clients-workspace-id] Client workspace IDs are UUIDs. List them with [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients): ```bash curl https://api.callmitra.ai/api/v1/agency/clients \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```json { "success": true, "agency": { "id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01", "name": "Acme Agency" }, "clients": [ { "id": "3f2e1d0c-9b8a-4765-8432-1f0e9d8c7b6a", "name": "Sunrise Dental", "status": "active", "createdAt": "2026-03-02T09:15:00+00:00" } ] } ``` - `clients` holds every client workspace, oldest first. Send a client's `id` as `X-Workspace-Id`. - `status` is `active`, `suspended` or `blocked`. Only `active` clients accept requests. - The list has identity fields only. Spend, caps and allowance stay in the console (**Settings → Workspaces**). - Any key of the agency can call it, whatever resources the key is limited to. A read-only key can call it too. - The key must act as a workspace **manager** ([which user a key acts as](/authentication#keys-belong-to-the-workspace)). Otherwise you get `403` [`permission_denied`](/errors/permission_denied). A client workspace's key gets `permission_denied` too, because a client cannot have clients. - The workspace must have the **agency add-on** (on its plan, or switched on for the workspace). Without it you get `403` [`permission_denied`](/errors/permission_denied). To check a single client, call [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace) with `X-Workspace-Id`. It returns that client's `id` and `name`. ## Rules that still apply [#rules-that-still-apply] - **The key's own limits travel with it.** A read-only key stays read-only inside every client, and a key limited to some resources is limited the same way in every client. - **The rate limit is per key, not per workspace.** One agency key shares its 300 requests per minute across all clients. Give large clients their own key if they need their own budget ([Rate limits](/rate-limits)). - **Webhooks are per workspace.** Each client workspace has its own webhook settings and receives events only for its own calls. Configure them while acting in that workspace. - **Idempotency keys are per key**, so the same `Idempotency-Key` sent to two clients with the same key and path is treated as the same request. Include the client in your idempotency key ([Idempotency](/idempotency)). ## What an agency key cannot do [#what-an-agency-key-cannot-do] - Create, edit, suspend, resume, detach or delete client workspaces, or open acting sessions for the console. Every `/agency` route except [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients) answers `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden). That includes the agency usage report. Use the console for these. - Create API keys, through the API or while acting in a client workspace in the console. Keys are always created in the agency's own workspace. - Act in a workspace that is not one of its own live clients, or in a client of a client. - Any endpoint that is not in the API reference, including the console-only routes listed in [Authentication](/authentication#which-endpoints-a-key-can-call). ## Audit trail [#audit-trail] When an agency key first acts in a client workspace, CallMitra opens an acting session and writes an `agency.act.start` entry, marked as made through an API key, to the audit logs of **both** the agency and the client. The session is reused for that key and client for up to 8 hours (the default limit), so every request does not create a new entry. Changes made during the session are attributed to the key's user, acting for the agency. ## Related [#related] - [Authentication & API keys](/authentication) - [Errors](/errors) # Build agents with the API (/guides/agents) An **agent** is the voice AI that talks on your calls. It holds the script, the knowledge, the voice, the language and the call rules. This guide shows how to build one end to end with the API. | Step | Endpoint | | --- | --- | | List agents | [`GET /api/v1/agents/`](/api-reference/agents/listAgents) | | Create an agent | [`POST /api/v1/agents/`](/api-reference/agents/createAgent) | | Import from another platform | [`POST /api/v1/agents/import`](/api-reference/agents/importAgent) | | Read one agent | [`GET /api/v1/agents/{agent_id}`](/api-reference/agents/getAgent) | | Save draft changes | [`PATCH /api/v1/agents/{agent_id}`](/api-reference/agents/updateAgent) | | Publish the draft | [`POST /api/v1/agents/{agent_id}/publish`](/api-reference/agents/publishAgent) | | Start taking calls | [`POST /api/v1/agents/{agent_id}/go-live`](/api-reference/agents/startAgent) | | Stop taking calls | [`POST /api/v1/agents/{agent_id}/pause`](/api-reference/agents/pauseAgent) | | Place a test call | [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) | | Set the post-call webhook | [`PUT /api/v1/agents/{agent_id}/post-call-webhook`](/api-reference/webhooks/setAgentPostCallWebhook) | | Delete an agent | [`DELETE /api/v1/agents/{agent_id}`](/api-reference/agents/deleteAgent) | | List voices | [`GET /api/v1/voices/`](/api-reference/agents/listVoices) | | List tools | [`GET /api/v1/tools/`](/api-reference/agents/listTools) | All agent endpoints need an API key with the **Agents** resource ([Authentication](/authentication)). A read-only key can list and read agents, but cannot create or change them. ## Versions and lifecycle [#versions-and-lifecycle] Every agent has two copies of its settings: - **`config`** is the **published** version. Live calls, campaigns and test calls use it. - **`draftConfig`** is the **working copy**. `PATCH` writes here. When there is no pending draft, `draftConfig` equals `config`. `unpublishedChanges` is `true` while a draft is waiting to be published. Secrets inside the config (such as webhook signing secrets) are never returned. Three fields describe where the agent is: | Field | Values | Meaning | | --- | --- | --- | | `status` | `draft`, `published`, `archived` | `draft` until the first publish. | | `takingCalls` | `true`, `false` | Set by go-live and pause. | | `rosterState` | see below | One badge that combines the two, plus whether a number is assigned. | | `rosterState` | When | | --- | --- | | `in_training` | The agent has never been published. | | `paused` | Published, but `takingCalls` is `false`. | | `ready` | Taking calls, but no phone number is assigned. | | `live` | Published, taking calls, and a phone number is assigned. | | `archived` | The agent is archived. | The usual flow is: **Create** the agent. It starts as a draft (`rosterState` is `in_training`). **Edit** it with `PATCH`. Each change lands in `draftConfig`. **Publish** it. The draft becomes `config`. **Test** it with a test call to your own phone. **Go live** once a phone number is assigned. **Pause** it to stop new calls. ## Create an agent [#create-an-agent] Send a `name` and a `config`. Every field is optional, so `{}` creates an empty draft with default settings. In practice you send at least a language, a voice, a system prompt and a greeting: ```bash curl -X POST https://api.callmitra.ai/api/v1/agents/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: create-agent-priya-001" \ -d '{ "name": "Priya", "config": { "language": "hi-IN", "stt": "sarvam", "tts": "sarvam", "voice": "priya", "llm_model": "gpt-4o-mini", "template_payload": { "system_prompt": "You are Priya from Acme Realty. Qualify the lead'\''s budget and preferred area.", "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon." } } }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/agents/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': 'create-agent-priya-001', }, body: JSON.stringify({ name: 'Priya', config: { language: 'hi-IN', stt: 'sarvam', tts: 'sarvam', voice: 'priya', llm_model: 'gpt-4o-mini', template_payload: { system_prompt: "You are Priya from Acme Realty. Qualify the lead's budget and preferred area.", greeting_message: 'Namaste, main Acme Realty se Priya bol rahi hoon.', }, }, }), }); const { agent } = await res.json(); ``` ```python import os import requests res = requests.post( "https://api.callmitra.ai/api/v1/agents/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "create-agent-priya-001", }, json={ "name": "Priya", "config": { "language": "hi-IN", "stt": "sarvam", "tts": "sarvam", "voice": "priya", "llm_model": "gpt-4o-mini", "template_payload": { "system_prompt": "You are Priya from Acme Realty. Qualify the lead's budget and preferred area.", "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon.", }, }, }, timeout=30, ) agent = res.json()["agent"] ``` The response holds the new agent (shortened here): ```json { "success": true, "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Priya", "status": "draft", "rosterState": "in_training", "takingCalls": false, "unpublishedChanges": false, "language": "hi-IN", "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "tts": "sarvam", "voice": "priya" } } } ``` Body fields: | Field | Type | Default | Notes | | --- | --- | --- | --- | | `name` | string | `""` | Display name, up to 255 characters. | | `config` | object | defaults | The agent settings. See [Config reference](#config-reference). | | `status` | `draft` or `published` | `draft` | Send `published` to publish on create. The language model check then runs too. | | `sourceTemplateId`, `sourceTemplateSlug`, `sourceTemplateVersion` | string / integer | none | Optional record of the template you started from. | On create and update, CallMitra checks that: - `config` is at most **512 KB** as JSON (UTF-8) and nested at most 16 levels deep. A bigger config returns `413` [`payload_too_large`](/errors/payload_too_large); a deeper one returns `422` [`parameter_invalid`](/errors/parameter_invalid); - every value is the right type and within its range or list of choices; - `config.language` is an active language; - `config.stt` is a speech-to-text provider that is available; - `config.voice` exists for the `config.tts` provider and supports `config.language`; - every tool URL (`base_url`, `url`, `server_url`, `endpoint`, or an absolute `path`) and `post_call_webhook.url` is a public `http(s)` address. Private, internal and loopback addresses are refused at save time; - every `tools[].config.tool_id` is a tool in your workspace; - the language model is ready to use (only when `status` is `published`, or when you publish). A failed check returns `422` [`parameter_invalid`](/errors/parameter_invalid), with `param` set to the config path, for example `config.voice` or `config.tools.0.config.base_url`. If your plan has no room for another agent, you get [`payment_required`](/errors/payment_required). `createAgent` accepts an `Idempotency-Key` header, so a retry does not create a second agent ([Idempotency](/idempotency)). ## Config reference [#config-reference] Config keys are **snake_case** by design, unlike the camelCase used in the rest of the API. `config` uses the same shape CallMitra stores, and [agent import](/migrate/import-agents) produces that shape too, so the keys stay as they are. The tables list the fields the API accepts, with types, defaults and allowed values. A config key CallMitra does not know is ignored and not stored. You do not get an error for it. Check the spelling of every key, and read the agent back to confirm what was saved. Only a known key with a bad value returns `422`. ### Script and knowledge [#script-and-knowledge] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `template_payload.system_prompt` | string | `""` | The instructions the agent follows. | | `template_payload.greeting_message` | string | `""` | The first thing the agent says. | | `template_payload.knowledge_base` | string | `""` | Free-text knowledge. | | `system_prompt` | string | — | Write shortcut. Fills `template_payload.system_prompt` only when that is empty. | | `greeting_message` | string | — | Write shortcut. Fills `template_payload.greeting_message` only when that is empty. | | `script.opening` | string | `""` | Structured script: how the call opens. | | `script.goal` | string | `""` | What the call should achieve. | | `script.steps` | array of `{name, instruction}` | `[]` | Ordered call steps. | | `script.end_rules` | array of strings | `[]` | When to end the call. | | `script.closing` | string | `""` | How the call closes. | | `script.strictness` | `flexible`, `balanced`, `strict` | `balanced` | How closely the agent follows the steps. | | `script.ask_first_question_in_greeting` | boolean | — | Ask the first question in the greeting. | | `knowledge.details` | array of `{key, label, value}` | `[]` | Business facts, such as hours or address. | | `knowledge.items` | array of `{kind, q, text}` | `[]` | `kind` is `fact`, `qa`, `rule` or `objection`. | | `knowledge.notes` | string | `""` | Extra notes. | | `agent_mode` | `announcement`, `awareness`, `conversation`, `ivr_survey`, `survey` | `conversation` | The kind of call. | | `job_role` | string | `""` | Up to 200 characters. | | `success_criteria` | string | `""` | What a successful call looks like. Up to 4,000 characters. | | `required_fields` | array of `{key, label, type}` | `[]` | Data to collect on the call. Up to 32. `type` is `string`, `number`, `email`, `phone`, `date` or `bool`. | The script and knowledge together can hold up to **48,000 characters**. Older agents that use only a system prompt can hold up to 40,000. Over the limit, saving and publishing fail with [`agent_state_blocked`](/errors/agent_state_blocked). ### Voice [#voice] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `tts` | string | `sarvam` | Text-to-speech provider. Use a `provider` value from [listVoices](#pick-a-voice). | | `voice` | string | `""` | A `voiceId` from listVoices for the `tts` provider. | | `agent_gender` | `female`, `male`, `any` | `any` | | | `tone` | string | `natural` | | | `caller_name` | string | `""` | The name the agent uses. Up to 120 characters. | | `tts_speed` | number | `1.0` | From `0.5` to `1.5`. | | `tts_volume` | number | `1.0` | From `0.2` to `1.0`. | | `background_sound.enabled` | boolean | `false` | Play a background sound. | | `background_sound.preset` | string | `off` | Sound name, for example `office`. | | `background_sound.volume` | number | `0.5` | From `0.02` to `1.0`. | ### Language and speech-to-text [#language-and-speech-to-text] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `language` | string | `en-IN` | Main language. Must be an active language from listVoices `languages`. | | `extra_language` | string | `""` | A second language. | | `auto_adapt_language` | boolean | `false` | Switch language to match the caller. | | `stt` | `deepgram`, `openai`, `sarvam`, `soniox` | `deepgram` | Speech-to-text provider. | | `noise_reduction` | `off`, `standard`, `strong` | `standard` | | ### Language model [#language-model] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `llm_model` | string | `gpt-4o-mini` | The model that writes replies. | | `temperature` | number | `0.55` | From `0` to `2`. | | `max_tokens` | integer | `250` | From `1` to `32000`. Longest reply per turn. | | `reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | `minimal` | For reasoning models. | | `voice_engine` | `pipeline`, `gemini_live`, `openai_realtime`, `elevenlabs_agents` | `pipeline` | `pipeline` chains speech-to-text, the model and text-to-speech. | | `realtime_model`, `realtime_voice` | string | — | Used with a realtime `voice_engine`. | ### Turn-taking [#turn-taking] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `interrupt_mode` | `time`, `words` | `time` | How the caller interrupts the agent. | | `interrupt_min_speech_ms` | integer | `220` | From `100` to `2000`. Speech needed to interrupt, in `time` mode. | | `interrupt_word_count` | integer | `2` | From `1` to `3`. Words needed to interrupt, in `words` mode. | | `interruption_sensitivity` | `low`, `medium`, `high` | `medium` | | | `conversation_engine` | `v1`, `v2` | `v1` | | ### Compliance [#compliance] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `ai_disclosure` | boolean | `true` | The agent says it is an AI. | | `recording_notice` | boolean | `true` | The agent says the call is recorded. | | `call_recording` | boolean | `true` | Record the call. | ### Limits and calling [#limits-and-calling] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `call_time_limit_seconds` | integer | `600` | From `10` to `3600`. The call ends at this limit. | | `calling_mode` | `""`, `instant`, `bulk` | `""` | | ### Inline tools [#inline-tools] | Field | Type | Default | Notes | | --- | --- | --- | --- | | `tools` | array | `[]` | Inline tools. Up to 32. See [Tools](#tools). | | `tools[].kind` | string | — | `end_call`, `transfer_call`, `api_request`, `function`, `mcp`, `lookup_open_tickets`, `create_ticket`, `add_ticket_note`, `schedule_callback` or `send_whatsapp`. | | `tools[].name` | string | — | Up to 128 characters. | | `tools[].description` | string | — | Up to 2,000 characters. Tells the model when to use the tool. | | `tools[].enabled` | boolean | `true` | | | `tools[].config` | object | `{}` | Kind-specific settings. For example `{"phone_number": "+919800000000"}` for `transfer_call`, or `{"base_url": "https://api.example.com", "path": "/orders", "method": "POST"}` for `api_request`. | For an inline `api_request` tool, the host and method always come from the saved config: - `base_url` must be a public `http(s)` address. An absolute `path` is used as the base only when `base_url` is empty. - During a call, the model may only add a **relative** path under `base_url`, plus a JSON body. A path with a scheme, `//`, `..` segments, encoded slashes or control characters is refused. - `method` is `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. The default is `POST`. - Requests go only to public addresses and do not follow redirects. ### Post-call [#post-call] | Field | Type | Notes | | --- | --- | --- | | `post_call_webhook` | object `{url, trigger}` | Prefer the [post-call webhook endpoint](#post-call-webhook). It applies at once and stores the signing secret safely. | ## Pick a voice [#pick-a-voice] [`GET /api/v1/voices/`](/api-reference/agents/listVoices) lists the voices, providers and languages you can use. Filter with `provider` and `language`: ```bash curl "https://api.callmitra.ai/api/v1/voices/?provider=sarvam&language=hi-IN" \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` The response has three lists. The filters narrow `voices` only: ```json { "success": true, "providers": [ { "id": "sarvam", "name": "Sarvam", "count": 12, "previewSupported": true } ], "voices": [ { "provider": "sarvam", "providerName": "Sarvam", "voiceId": "priya", "name": "Priya", "gender": "female", "languageCodes": ["hi-IN", "en-IN"], "sortOrder": 1, "previewSupported": true } ], "languages": [{ "id": "hi-IN", "name": "Hindi" }] } ``` Copy three values into the config: - `config.tts` = the voice's `provider`; - `config.voice` = its `voiceId`; - `config.language` = a language `id` that appears in the voice's `languageCodes`. If the voice does not exist for that provider, or does not support the language, create and update return `422` [`parameter_invalid`](/errors/parameter_invalid) with `param` `config.voice`. ## Update an agent [#update-an-agent] [`PATCH /api/v1/agents/{agent_id}`](/api-reference/agents/updateAgent) takes `name` and `config`, both optional. - **Config changes go to the draft.** `config` (the published version) does not change until you publish. Live calls keep using the published version. - **Only the top-level keys you send change.** Keys you leave out keep their draft values. - **Nested objects are replaced, not merged.** If you send `script`, send the whole `script` object. Any `script` field you leave out is cleared. - **`name` applies at once.** It changes the display name immediately and also sets `caller_name` in the draft. ```bash curl -X PATCH https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10 \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "config": { "tts_speed": 1.1, "call_time_limit_seconds": 300 } }' ``` After this call, `unpublishedChanges` is `true` and `draftConfig` holds the new values. `PATCH` returns: - [`parameter_invalid`](/errors/parameter_invalid) for a bad value, voice or language; - [`agent_state_blocked`](/errors/agent_state_blocked) when the script and knowledge are over the size limit, when the text uses an unknown `@` token, or when a webhook or `api_request` tool URL is not a public address. ## Publish [#publish] [`POST /api/v1/agents/{agent_id}/publish`](/api-reference/agents/publishAgent) copies the draft into `config`, clears the draft and sets `status` to `published`. It takes no body. ```bash curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/publish \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const agentId = '3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10'; const res = await fetch( `https://api.callmitra.ai/api/v1/agents/${agentId}/publish`, { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }, ); const { agent } = await res.json(); ``` ```python agent_id = "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10" res = requests.post( f"https://api.callmitra.ai/api/v1/agents/{agent_id}/publish", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30, ) agent = res.json()["agent"] ``` Before it publishes, CallMitra checks the content size limit, `@` tokens, public URLs, the voice, and that the language model is ready. If a check fails, nothing is published and you get `422` [`agent_state_blocked`](/errors/agent_state_blocked). The `message` says what to fix. Publishing does not change `takingCalls`. A live agent stays live and starts using the new version. ## Go live and pause [#go-live-and-pause] [`POST /api/v1/agents/{agent_id}/go-live`](/api-reference/agents/startAgent) sets `takingCalls` to `true`. - The agent needs a **phone number assigned**. Assign numbers in the console. You can see them in `assignedPhoneNumbers` and with [listPhoneNumbers](/api-reference/phone-numbers/listPhoneNumbers). - An archived agent cannot go live. - If the agent has never been published, or has a pending draft, go-live **publishes the draft first**. The same publish checks run. If go-live is refused, you get [`agent_state_blocked`](/errors/agent_state_blocked). [`POST /api/v1/agents/{agent_id}/pause`](/api-reference/agents/pauseAgent) sets `takingCalls` to `false`. The settings and the published version stay as they are. Call go-live again to resume. ## Test call [#test-call] [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) calls a phone you choose, using one of your numbers as caller ID. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `phoneNumberId` | string | yes | The ID of one of your phone numbers, from [listPhoneNumbers](/api-reference/phone-numbers/listPhoneNumbers). | | `destination` | string | yes | The phone to call. E.164 (`+919812345678`) or a local number. | | `dynamicValues` | object | no | Values for placeholders in the script, for example `{"customer_name": "Asha"}`. | ```bash curl -X POST https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/test-call \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phoneNumberId": "8d1e4b2a-0c3f-4a5e-9b7d-6f2a1c3e5d70", "destination": "+919812345678", "dynamicValues": { "customer_name": "Asha" } }' ``` ```json { "success": true, "callId": "c2b7e9d4-1a3f-4e6b-8c5d-7f9a0b1c2d3e", "phoneNumber": "+919812345678", "message": "Test call initiated" } ``` Read the result with [getCall](/api-reference/calls/getCall) using `callId`. A test call runs `config`, not `draftConfig`. Publish your changes before you test them. Test calls are not billed. Free plans have a cap on test calls. Errors: | Code | When | | --- | --- | | [`resource_not_found`](/errors/resource_not_found) | `phoneNumberId` is not one of your numbers (`param` is `phoneNumberId`). | | [`agent_test_call_failed`](/errors/agent_test_call_failed) | The call could not be placed, for example the free test-call cap is reached or the carrier refused it. | | [`payment_required`](/errors/payment_required) | Your plan does not include this. | ## Post-call webhook [#post-call-webhook] [`PUT /api/v1/agents/{agent_id}/post-call-webhook`](/api-reference/webhooks/setAgentPostCallWebhook) sets where CallMitra posts the result after each call this agent handles. It applies to the live agent at once, with no publish needed. A key with the **Agents** or **Webhooks** resource can call it. | Field | Type | Default | Notes | | --- | --- | --- | --- | | `url` | string | — | A public address, up to 2,000 characters. Send `""` to remove the webhook. | | `secret` | string | — | Signing secret, up to 500 characters. Leave it out to keep the current secret. | | `trigger` | `every`, `completed`, `voicemail` | `every` | Which calls send the webhook. | ```bash curl -X PUT https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/post-call-webhook \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/callmitra", "secret": "whsec_example", "trigger": "completed" }' ``` The response holds the agent and `webhook: {url, trigger, hasSecret}`. The secret itself is never returned. A campaign that has its own webhook uses that one instead. A URL that is not a public address returns [`agent_state_blocked`](/errors/agent_state_blocked). For the payload and signature, see [Per-agent webhooks](/webhooks/campaign-agent-webhooks). For workspace-wide events, see [Webhooks](/webhooks). ## Tools [#tools] Tools let the agent act during a call: end it, transfer it, call your API, create a ticket, and more. - **Inline tools** live in `config.tools`. Add, change or remove them with `PATCH`, then publish. See [Inline tools](#inline-tools) in the config reference. The end-call tool is added for you. - **Workspace tools** are shared tools you build in the console. The API can read them with [listTools](/api-reference/agents/listTools) and [getTool](/api-reference/agents/getTool), but cannot create them or attach them to an agent. Do both in the console. A tool's credentials are never returned. `authSecretSet` tells you whether one is stored. An unknown tool ID returns [`tool_not_found`](/errors/tool_not_found). ## Delete an agent [#delete-an-agent] [`DELETE /api/v1/agents/{agent_id}`](/api-reference/agents/deleteAgent) removes the agent permanently. - Past calls keep their records. - Campaigns that used the agent lose it. Starting such a campaign fails with [`campaign_has_no_agent`](/errors/campaign_has_no_agent) until you set a new agent. To stop an agent without losing it, [pause](#go-live-and-pause) it instead. ## Errors [#errors] Errors use the standard envelope ([Errors](/errors)): ```json { "detail": "config.tts_speed must be a number from 0.5 to 1.5", "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "config.tts_speed must be a number from 0.5 to 1.5", "param": "config.tts_speed", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` | Code | Status | When | | --- | --- | --- | | [`parameter_invalid`](/errors/parameter_invalid) | 422 | A config value is the wrong type or out of range; the voice, language or speech-to-text provider is not available; a tool or webhook URL is not public; or a `tool_id` is not in your workspace. | | [`payload_too_large`](/errors/payload_too_large) | 413 | `config` is larger than 512 KB. | | [`agent_state_blocked`](/errors/agent_state_blocked) | 422 | Publish or go-live is refused, content is over the limit, or a URL is not public. | | [`agent_not_found`](/errors/agent_not_found) | 404 | The agent ID does not exist in this workspace. | | [`agent_test_call_failed`](/errors/agent_test_call_failed) | 400 | The test call could not be placed. | | [`tool_not_found`](/errors/tool_not_found) | 404 | The tool ID does not exist. | | [`payment_required`](/errors/payment_required) | 402 | Your plan's agent limit is reached, or the feature is not in your plan. | | [`permission_denied`](/errors/permission_denied) | 403 | The key cannot write agents. | ## Related [#related] - [Import agents](/migrate/import-agents) from Vapi, Retell or Bland - [Run campaigns](/guides/campaigns) with your agent - [Per-agent webhooks](/webhooks/campaign-agent-webhooks) - [Idempotency](/idempotency) - [Errors](/errors) # Campaigns & bulk calling (/guides/campaigns) A **campaign** pairs an [agent](/api-reference/agents/listAgents) with a list of leads, a caller ID and a calling schedule. Once started, CallMitra dials each lead inside the schedule, retries unanswered calls, and reports every result to your webhook. ## 1. Create the campaign [#1-create-the-campaign] [`POST /api/v1/campaigns/create-with-leads`](/api-reference/campaigns/createCampaignWithLeads) creates the campaign and attaches its leads in one request. Choose the lead source with `leadSourceType`: | `leadSourceType` | Send | Use when | | --- | --- | --- | | `bulk_upload` | `uploadedLeads`: an array of leads (`name`, `phone` in E.164, optional `email`, `company`, `title`, `notes`, `externalId`, `attributes`) | The leads come from your system. | | `existing_leads` | `selectedLeadIds` and/or `selectedLeadSourceIds` | The leads already exist in CallMitra (created with [`POST /api/v1/leads/`](/api-reference/leads/createLead) or a lead intake webhook). | ```json { "campaignData": { "name": "November renewals", "agentId": "AGENT_ID", "phoneNumberId": "PHONE_NUMBER_ID", "crmWebhookUrl": "https://example.com/webhooks/callmitra", "crmWebhookSecret": "a-long-random-secret", "settings": { "dialWindowStart": "10:00", "dialWindowEnd": "18:00", "dialTimezone": "Asia/Kolkata", "dialDaysOfWeek": [0, 1, 2, 3, 4, 5], "maxCallsPerDay": 200, "retryAttempts": 3 } }, "leadSourceType": "bulk_upload", "uploadedLeads": [ { "name": "Asha Rao", "phone": "+919876543210", "externalId": "crm-1042", "attributes": { "plan": "Gold" } } ] } ``` The response returns `campaignId` and `processedLeads`. `attributes` and `externalId` stay on the lead, so your agent can use them in the conversation and you can match results back to your records. Use `copySettingsFromCampaignId` to reuse the schedule of an earlier campaign. `crmWebhookUrl` and `crmWebhookSecret` set an optional [campaign webhook](/webhooks/campaign-agent-webhooks) for this campaign's calls. For new integrations, register a [webhook endpoint](/webhooks/endpoints) once instead: it receives events from every campaign. For inbound campaigns, a phone number can have only one default inbound campaign (`isDefaultInbound: true`), which answers callers that no other campaign claims. Asking for a second one on the same number returns `409` [`campaign_default_inbound_exists`](/errors/campaign_default_inbound_exists). To create an empty campaign and add leads later, use [`POST /api/v1/campaigns/`](/api-reference/campaigns/createCampaign) and then [`PUT /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/updateCampaignLeads) with `added` and `removed` lists of lead IDs. A removed lead keeps its call history, and adding it again revives it rather than duplicating it. Removing a lead that was already called returns `409` [`campaign_leads_need_confirmation`](/errors/campaign_leads_need_confirmation) with those IDs in `detail.leadIds`; resend with `confirmRemovedContacted: true` to remove them anyway. See [Leads and callbacks](/guides/leads) for lead fields, attributes and phone number rules. ## 2. Calling schedule [#2-calling-schedule] All schedule fields live in `campaignData.settings` and have defaults: | Field | Default | Meaning | | --- | --- | --- | | `dialWindowStart` / `dialWindowEnd` | `10:00` / `17:00` | Local `HH:MM` window. Calls are placed only inside it. | | `dialTimezone` | `Asia/Kolkata` | Time zone of the window. | | `dialDaysOfWeek` | every day | `0` = Monday … `6` = Sunday. | | `maxCallsPerDay` | `50` | Calls placed per day. | | `retryAttempts` | `3` | Attempts per lead. | | `retryIntervalBusyMs` | `1800000` (30 min) | Wait before retrying a busy line. | | `retryIntervalNoAnswerMs` | — | Wait before retrying an unanswered call. | | `callInterval` | `7200000` (2 h) | Minimum gap between attempts to the same lead. | | `autoDialEnabled` | `true` | Dial automatically while the campaign is running. | Numbers on your [do-not-call list](/api-reference/do-not-call/listDoNotCall) are never dialed. ## 3. Start, pause, resume, stop [#3-start-pause-resume-stop] | Action | Endpoint | Effect | | --- | --- | --- | | Start | [`POST …/{campaign_id}/start`](/api-reference/campaigns/startCampaign) | Begins dialing inside the window, up to the daily limit. | | Pause | [`POST …/{campaign_id}/pause-dialing`](/api-reference/campaigns/pauseCampaignDialing) | No new calls. The campaign stays active. | | Resume | [`POST …/{campaign_id}/resume-dialing`](/api-reference/campaigns/resumeCampaignDialing) | Continues where it left off. | | Stop | [`POST …/{campaign_id}/stop`](/api-reference/campaigns/stopCampaign) | Cancels calls waiting to be placed. A call in progress finishes. | Stop is safe to repeat. Start and resume can be refused: | Status | Code | When | | --- | --- | --- | | `422` | [`campaign_not_ready`](/errors/campaign_not_ready) | Start: the campaign cannot dial yet. The message lists what to fix: no agent, placeholders in the prompt that no lead can fill, missing IVR clips, or an inbound campaign with no callers. Also returned by `create-with-leads` and campaign update. | | `402` | [`payment_required`](/errors/payment_required) | Start: the workspace has no balance or plan. | | `400` | [`bad_request`](/errors/bad_request) | Start: the campaign's phone number cannot place calls (`param: "phoneNumberId"`). | | `409` | [`campaign_not_running`](/errors/campaign_not_running) | Resume: the campaign is stopped. Start it first. | | `404` | [`campaign_not_found`](/errors/campaign_not_found) | The campaign does not exist in your workspace. | ## 4. Check progress [#4-check-progress] [`GET /api/v1/campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus) explains whether the campaign is placing calls right now and, if not, why: - `dialingAllowed`, `inDialWindow`, `skipReason` — whether calls go out now, and the reason when they do not. - `callsToday` / `maxCallsPerDay`, `pendingJobCount` — today's volume and the queue. - `nextWindowOpenAt`, `nextEligibleDialAt` — when dialing resumes. - `lastErrorCode`, `lastErrorMessage`, `lastErrorAt` — the most recent dialing error. List the calls themselves with [`GET /api/v1/calls/?campaignId=…`](/api-reference/calls/listCalls), and the campaign's leads with [`GET /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/listCampaignLeads). ## 5. Get results [#5-get-results] Each finished call sends a [`call.completed`](/webhooks/events) event to the campaign's `crmWebhookUrl` and to every [webhook endpoint](/webhooks/endpoints) subscribed to it. It contains the status, duration, transcript, summary, outcome and the fields your agent extracted. You can also fetch any call with [`GET /api/v1/calls/{call_id}`](/api-reference/calls/getCall). ## Call one lead now [#call-one-lead-now] To call a lead immediately, outside the schedule, use [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow) with `leadId` and a running `campaignId`, or [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) to use the first running outbound campaign the lead belongs to. The response wraps the call in `call`: read `call.id` and `call.status` (usually `initiated` or `queued`). ```json { "success": true, "call": { "id": "7c0e5a2b-1d3f-4e6a-9b8c-2f1e0d9c8b7a", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "campaignId": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "status": "initiated" } } ``` Common refusals: - `409` [`campaign_not_running`](/errors/campaign_not_running): the campaign is not running. For `callLeadNow`, the lead is on campaigns but none is running. - `422` [`lead_has_no_campaign`](/errors/lead_has_no_campaign): `callLeadNow` only; the lead is on no outbound campaign with an agent. - `409` [`number_on_dnc`](/errors/number_on_dnc), `409` [`lead_call_in_progress`](/errors/lead_call_in_progress), `402` [`payment_required`](/errors/payment_required). - `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached), [`campaign_dial_busy`](/errors/campaign_dial_busy) or [`carrier_capacity_reached`](/errors/carrier_capacity_reached), and `429` [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached): a capacity limit. Retry after a short wait. The full list is under [Calling refusals](/errors#calling-refusals). ## Callbacks [#callbacks] When a caller asks to be called later, an agent with the schedule-callback tool books a callback, and CallMitra dials it inside the campaign's calling window. Each campaign limits callback attempts (2 by default). List booked callbacks with [`GET /api/v1/callbacks?campaignId=…`](/api-reference/campaigns/listCallbacks) and see [Leads and callbacks](/guides/leads#callbacks) for how they work. # Place and read calls (/guides/direct-calls) This guide covers the two halves of the Calls API: **placing** a single call with [`POST /api/v1/calls/`](/api-reference/calls/createCall), and **reading** calls, transcripts, recordings and reports afterwards. ## Pick the right way to call [#pick-the-right-way-to-call] | You want to | Use | | --- | --- | | Call one number now with an agent, no campaign set up | [`POST /api/v1/calls/`](/api-reference/calls/createCall) (this page) | | Call many leads on a schedule, with a calling window, retries and a daily limit | A campaign ([Campaigns](/guides/campaigns)) | | Call a lead that is already on a running campaign, right now | [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow) with `leadId` and `campaignId` | | Call a lead through the first running campaign it belongs to | [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) | | Try an agent before going live | [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) | The two call-now endpoints use the campaign's agent and phone numbers and answer `200` with the same body as `POST /calls`. They do not accept `Idempotency-Key`. ## Place a call [#place-a-call] `POST /api/v1/calls/` calls `to` now with the agent. You need a key with **full** access that can reach **Calls** ([Authentication](/authentication)). ```bash curl -X POST https://api.callmitra.ai/api/v1/calls/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Idempotency-Key: order-A-1042-delivery-call" \ -H "Content-Type: application/json" \ -d '{ "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "to": "+919812345678", "name": "Asha Verma", "variables": { "order_id": "A-1042", "delivery_date": "Friday" }, "metadata": { "crmId": "0065g00000XyZ" } }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/calls/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Idempotency-Key': 'order-A-1042-delivery-call', 'Content-Type': 'application/json', }, body: JSON.stringify({ agentId: '4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23', to: '+919812345678', name: 'Asha Verma', variables: { order_id: 'A-1042', delivery_date: 'Friday' }, metadata: { crmId: '0065g00000XyZ' }, }), }); const body = await res.json(); if (res.status !== 201) throw new Error(`${body.error.code}: ${body.error.message}`); console.log(body.call.id); ``` ```python import os import requests res = requests.post( "https://api.callmitra.ai/api/v1/calls/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "order-A-1042-delivery-call", }, json={ "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "to": "+919812345678", "name": "Asha Verma", "variables": {"order_id": "A-1042", "delivery_date": "Friday"}, "metadata": {"crmId": "0065g00000XyZ"}, }, timeout=30, ) body = res.json() if res.status_code != 201: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") print(body["call"]["id"]) ``` ### Request body [#request-body] | Field | Type | Required | Notes | | --- | --- | --- | --- | | `agentId` | string | yes | Agent that speaks on the call ([`GET /agents`](/api-reference/agents/listAgents)). An archived agent answers `422` [`agent_state_blocked`](/errors/agent_state_blocked). | | `to` | string | yes | Number to call, E.164, up to 32 characters. Spaces, dashes, dots and brackets are removed first; the rest must be `+` and 7 to 15 digits, not starting with `0`. Otherwise `422` [`invalid_phone_number`](/errors/invalid_phone_number). | | `fromNumberId` | string | no | ID of your phone number to call from ([`GET /phone-numbers`](/api-reference/phone-numbers/listPhoneNumbers)). Omitted: a free number from the agent's phone numbers. | | `leadId` | string | no | Lead this call belongs to. Its phone must match `to`. | | `name` | string | no | Name for a new lead, up to 255 characters. Ignored when the lead already exists. | | `variables` | object | no | Up to 50 values the agent's script can use as `{{name}}`. Values are strings, numbers or booleans. Keys use letters, digits and underscores, do not start with a digit, and are at most 64 characters. | | `metadata` | object | no | Your own data, at most 4096 bytes of JSON. Never spoken. Returned unchanged as `metadata` on the call. | Any other field is rejected with `422` [`parameter_invalid`](/errors/parameter_invalid). There is no per-call webhook URL: results go to your workspace's [webhooks](/webhooks). ### Which lead the call belongs to [#which-lead-the-call-belongs-to] Every call belongs to a lead, so the call shows up in your reports and lead history: 1. With `leadId`, that lead is used. A lead from another workspace answers `404` [`lead_not_found`](/errors/lead_not_found); a lead whose phone does not match `to` answers `422` [`parameter_invalid`](/errors/parameter_invalid) with `param: "leadId"`. 2. Without `leadId`, CallMitra uses the newest lead in your workspace with exactly this number. 3. If there is none, it creates a lead with `source: "api"`, named `name` (or the number itself when you send no `name`). ### Caller ID [#caller-id] The call runs on the agent's **instant campaign**: a campaign CallMitra creates for the agent the first time it is needed, named after the agent with ` Instant` at the end. Its numbers are the agent's numbers. - Without `fromNumberId`, CallMitra picks a free number from that pool. - With `fromNumberId`, only that number is used. A number not in your workspace answers `404` [`phone_number_not_found`](/errors/phone_number_not_found). A number that is inactive or has no outbound carrier credentials answers `422` [`phone_number_not_dialable`](/errors/phone_number_not_dialable). ### Response [#response] `201 Created` means the carrier accepted the dial. It does not mean the call was answered. Follow the call with [`GET /calls/{call_id}`](/api-reference/calls/getCall) or the [`call.completed`](/webhooks/events) webhook. ```json title="201 Created" { "success": true, "call": { "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "Delivery desk Instant", "providerCallId": "CA5f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c", "status": "queued", "phoneNumber": "+919812345678", "phoneNumberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" } } ``` | Field | Meaning | | --- | --- | | `call.id` | Call ID. Use it with every read endpoint below. | | `call.leadId`, `call.leadName` | The lead that was used or created. | | `call.campaignId`, `call.campaignName` | The agent's instant campaign. | | `call.providerCallId` | The carrier's call ID. | | `call.status` | Carrier status at dial time, usually `initiated` or `queued`. | | `call.phoneNumber` | The number being dialed. | | `call.phoneNumberId` | Your phone number the call is placed from. | | `sipResponse` | The carrier's raw answer to the dial request, when present. Fields vary by carrier; do not depend on them. | ### One request, one dial [#one-request-one-dial] Each `POST /calls` dials once. - A call that is not answered, is busy or times out is **not** redialed. - A refused dial is **not** queued to try later. The lead does not stay queued on the agent's instant campaign. - For a second attempt, place another call. Use a new `Idempotency-Key`, or the first result is replayed. - One exception: the callee may ask to be called back, and the agent may book that callback during the call. The booked callback is placed at the agreed time. ## Retry safely with Idempotency-Key [#retry-safely-with-idempotency-key] A timeout does not tell you whether the call was placed. Send an `Idempotency-Key` header (1 to 255 characters) and reuse it when you retry the same request. Within 24 hours, the same key with the same body returns the first result with `Idempotent-Replayed: true` instead of calling again. The full rules are in [Idempotency](/idempotency). Client errors (`4xx`) are stored like successes, except `401`, `403`, `404` and `429`. If a call was refused with `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) and you retry later with the **same** key, you get the same `409` back. Once the refusal is resolved, try again with a **new** key. `5xx`, `401`, `403`, `404` and `429` responses are not stored, so a retry with the same key runs again. ## Limits and refusals [#limits-and-refusals] These limits apply to every direct call. Each refusal has its own code, and the error body follows the usual [error format](/errors). | What | Status and code | What to do | | --- | --- | --- | | `to` is outside your workspace's home country. The home country comes from your billing address (India when none is set); support can enable more countries. | `422` [`destination_not_allowed`](/errors/destination_not_allowed), `param: "to"` | The message lists the allowed codes, for example `+91`. Contact support to call other countries. | | Your workspace placed its daily number of calls through `POST /calls`. The count runs per UTC day. | `429` [`daily_call_limit_reached`](/errors/daily_call_limit_reached) | Wait for `Retry-After` (seconds until 00:00 UTC). Use a [campaign](/guides/campaigns) for large volumes, or ask support to raise the limit. | | The daily call counter is briefly unavailable. Direct calls fail closed. | `503` [`service_unavailable`](/errors/service_unavailable) | Retry shortly. | | The number is on your do-not-call list. Any lead in your workspace with this number (same number, or same last 10 digits) that opted out blocks the call. | `409` [`number_on_dnc`](/errors/number_on_dnc) | Do not call. Remove the number from do-not-call only if the person agreed to be called again. | | The agent's instant campaign already has a call in progress. By default it runs one call at a time, so one agent places one direct call at a time. | `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) | `detail.activeCallId` is the call in progress. Retry when it ends. | | Another call for the same agent is being placed at this moment. | `409` [`campaign_dial_busy`](/errors/campaign_dial_busy) | Wait a second and retry. | | This lead already has a call ringing or connected. | `409` [`lead_call_in_progress`](/errors/lead_call_in_progress) | Retry after it ends. | | Your plan's limit on simultaneous calls is in use. | `429` [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) | Retry when a call ends. | | The workspace is out of balance or has no plan that covers calls. | `402` [`payment_required`](/errors/payment_required) | Top up or change the plan. | | The calling number or its carrier account is at its call limit. | `409` [`carrier_capacity_reached`](/errors/carrier_capacity_reached) | Retry in a moment. | | The agent's instant campaign is stopped. | `409` [`campaign_not_running`](/errors/campaign_not_running) | Start it with [`POST /campaigns/{campaign_id}/start`](/api-reference/campaigns/startCampaign). | | The carrier refused the dial before it rang. | `400` [`dial_rejected`](/errors/dial_rejected) | Read the message. The failed call is recorded; its ID is in `detail.call.id`. | | The carrier could not be reached. | `502` [`dial_failed`](/errors/dial_failed) | Retry. The failed call is recorded in `detail.call.id`. | | The agent has no usable phone number, or another request problem. | `400` [`bad_request`](/errors/bad_request) | Read the message and fix the setup. | The [API reference](/api-reference/calls/createCall) lists every code this endpoint can return. Your key's [rate limit](/rate-limits) also applies. A direct call is placed the moment you ask, at any hour. CallMitra does **not** check a calling window or time-of-day rules for `POST /calls`, `POST /instant/call-now` or `POST /leads/{lead_id}/call-now`. The do-not-call list is still checked. You are responsible for consent and for calling only at hours the rules allow, including TRAI rules for Indian numbers. See [Calling in India](/guides/india-calling). ## Read calls [#read-calls] All read endpoints work with a read-only key that can reach **Calls**. ### List calls [#list-calls] [`GET /api/v1/calls/`](/api-reference/calls/listCalls) returns calls newest first. | Parameter | Default | Notes | | --- | --- | --- | | `cursor` | | Send it empty for the first page, then the `nextCursor` from the previous response. Cursor pages skip the total count and stay fast on long lists. | | `page` | `1` | Page number, from 1. Ignored when `cursor` is sent. | | `limit` | `25` | Items per page, 1 to 200. | | `search` | | Matches the phone number, customer name or phone, summary, or call name. | | `agentId`, `leadId`, `campaignId` | | Only calls of this agent, lead or campaign. | | `outcome` | | `qualified`, `interested`, `callback`, `not_interested`, `no_response`, `no_answer`, `busy`, `call_failed` or `voicemail`. | | `sentiment` | | `positive`, `neutral` or `negative`. | | `channel` | | `inbound`, `browser` (test calls), or `instant` / `bulk` (calls by agents in that calling mode). | | `hasRecording` | | `true` or `false`. | | `dateFilter` | `all` | `today` (since 00:00 UTC), `week` (last 7 days), `month` (last 30 days) or `all`. | | `includeTests` | `true` | Set `false` to leave out test calls. | There are two ways to page: - **Cursor mode** (recommended for syncing): pass `cursor=` on the first request. Each response has top-level `nextCursor` and `hasMore`. `nextCursor` is `null` on the last page. The `pagination` object only has `itemsPerPage`, `hasNextPage` and `nextCursor`. - **Page mode**: omit `cursor`. `pagination` has `currentPage`, `totalPages`, `totalItems`, `itemsPerPage`, `hasNextPage` and `hasPreviousPage`. Matches are counted up to 10,000; above that `totalCapped` is `true` and `totalItems` is only a lower bound. An unreadable cursor answers `422` [`parameter_invalid`](/errors/parameter_invalid). See [Pagination](/pagination). ```bash curl -G https://api.callmitra.ai/api/v1/calls/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ --data-urlencode "cursor=" \ --data-urlencode "limit=100" \ --data-urlencode "includeTests=false" ``` ```js let cursor = ''; do { const url = new URL('https://api.callmitra.ai/api/v1/calls/'); url.search = new URLSearchParams({ cursor, limit: '100', includeTests: 'false' }); const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }); const page = await res.json(); for (const call of page.calls) console.log(call.id, call.status); cursor = page.nextCursor; } while (cursor); ``` ```python cursor = "" while cursor is not None: page = requests.get( "https://api.callmitra.ai/api/v1/calls/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params={"cursor": cursor, "limit": 100, "includeTests": "false"}, timeout=30, ).json() for call in page["calls"]: print(call["id"], call["status"]) cursor = page["nextCursor"] ``` ### Get one call [#get-one-call] [`GET /api/v1/calls/{call_id}`](/api-reference/calls/getCall) returns `{ "success": true, "call": { ... } }`. An unknown ID, or a call in another workspace, answers `404` [`call_not_found`](/errors/call_not_found). The fields you will use most: | Field | Meaning | | --- | --- | | `status` | `initiated`, `ringing`, `answered`, `completed`, `no_answer`, `busy` or `failed`. | | `callType` | `manual` for direct and call-now calls; also `campaign`, `inbound` or `browser`. | | `startTime`, `endTime`, `duration` | ISO 8601 times and talk time in seconds. | | `outcome`, `outcomeCategory`, `merchantOutcome` | `successful` or `failed`; the detailed disposition; the outcome shown in the console. | | `endedReason`, `failureReason` | Why the call ended, and why it failed when it did. | | `summary`, `sentiment`, `callAnalysis` | AI summary, sentiment, and post-call analysis when the agent has it on. | | `extractedFields` | Details the agent collected, keyed by your capture fields. | | `transcript` | `User:` / `Assistant:` lines. Use the transcript endpoint for parsed turns. | | `hasRecording` | Whether a recording can be downloaded. | | `billableMinutes`, `billedInr` | Minutes charged, and the amount in rupees. | | `metadata` | The `metadata` you sent with `POST /calls`, unchanged. | | `fromNumber`, `phoneNumber`, `phoneNumberId` | Caller ID used, the other party's number, and your number's ID. | ### Transcript [#transcript] [`GET /api/v1/calls/{call_id}/transcript`](/api-reference/calls/getCallTranscript) returns the conversation as text and as ordered turns, plus the tools the agent called. `role` is `user` (the other party) or `assistant` (your agent). The transcript is empty while nothing has been said, and final once the call has ended. ```json { "success": true, "callId": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "status": "completed", "transcript": "Assistant: Hi, this is Asha from Acme.\nUser: Hi, yes.", "turns": [ { "role": "assistant", "text": "Hi, this is Asha from Acme." }, { "role": "user", "text": "Hi, yes." } ], "toolInvocations": [] } ``` ### Recording [#recording] [`GET /api/v1/calls/{call_id}/recording`](/api-reference/calls/getCallRecording) returns the audio file itself, authenticated with your key like any other request. Check `hasRecording` on the call first. - Format: stereo MP3 (`audio/mpeg`). An older call that has not been converted yet is served as WAV (`audio/wav`). Read the `Content-Type` header. - `404` [`call_recording_not_found`](/errors/call_recording_not_found): the call was not answered, recording was off, or the audio is still being saved. Retry a minute after the call ends. - `410` [`call_recording_deleted`](/errors/call_recording_deleted): your data retention policy removed the recording. It cannot be restored. ```bash curl https://api.callmitra.ai/api/v1/calls/8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65/recording \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -o call.mp3 ``` ## Reports [#reports] Both report endpoints use **India Standard Time** (`Asia/Kolkata`) to decide where a day or an hour starts. ### Calls per day [#calls-per-day] [`GET /api/v1/calls/daily-counts`](/api-reference/calls/getCallDailyCounts) takes `days` (1 to 90, default 30), ending today. Values outside that range are clamped to it. You get one entry per day, oldest first, with zeros for days without calls, plus totals. `avgDurationSeconds` is the average length of completed calls. ```json { "success": true, "days": 2, "timezone": "Asia/Kolkata", "totals": { "total": 12, "completed": 9, "failed": 1, "noAnswer": 2, "avgDurationSeconds": 74.2 }, "daily": [ { "date": "2026-11-14", "total": 5, "completed": 4, "failed": 0, "noAnswer": 1, "avgDurationSeconds": 80.0 }, { "date": "2026-11-15", "total": 7, "completed": 5, "failed": 1, "noAnswer": 1, "avgDurationSeconds": 69.6 } ] } ``` ### Performance [#performance] [`GET /api/v1/calls/performance`](/api-reference/calls/getCallPerformance) returns totals, connect rate, conversion, the outcome and channel split, calls per hour and an agent leaderboard, with the range before it for comparison. | Parameter | Default | Notes | | --- | --- | --- | | `rangeDays` | `30` | `7`, `30` or `90`, ending today. Any other value means 30. | | `agentId` | | Only calls of this agent. | | `channel` | | `instant`, `bulk`, `inbound` or `browser`. | | `includeTests` | `false` | Also count test calls placed from the console. | Rates (`connectRate`, `conversion`, `successRate`) are between 0 and 1. `byHour` keys are hours `0` to `23` in IST; empty hours are left out. `recent.today` counts calls since midnight IST. ## Related [#related] - [Campaigns](/guides/campaigns) - [Calling in India](/guides/india-calling) - [Webhook events](/webhooks/events) - [Idempotency](/idempotency) - [Workspace and usage](/guides/workspace-usage) # Calling in India (/guides/india-calling) This page explains the rules CallMitra applies when it dials Indian numbers, and what stays **your** responsibility. Read it before you launch a campaign. CallMitra enforces the calling window and do-not-call list you configure. It does **not** check the TRAI NCPR (DND) registry or DLT registrations for you. You are responsible for consent, for scrubbing your lists against the registry where the rules require it, and for setting hours that follow TRAI rules. ## Phone number formats [#phone-number-formats] Store and send numbers in **E.164**: `+` followed by the country code and the number, with no spaces, for example `+919876543210`. | Where | What CallMitra does | | --- | --- | | Leads created or updated with the API | Normalised to E.164: a bare 10-digit number becomes `+91…`; a number CallMitra cannot read is refused with `422` [`invalid_phone_number`](/errors/invalid_phone_number). See [Leads](/guides/leads#phone-numbers). | | CSV and bulk lead imports | Numbers without a country code are treated as Indian (`+91`). A leading `0` or `00`, spaces and Excel's `.0` are cleaned up. | | Dialing a lead | Separators are removed, then: 11 digits starting with `0` lose the `0`; 12 digits starting with `91` get a `+`; **10 digits starting with 6–9 become `+91…`**; anything else gets a `+` in front. | | Your own phone numbers (caller IDs) | Must be E.164. CallMitra adds the `+` but never adds `+91` for you. | | Do-not-call list | Accepts Indian mobile numbers only. | Because a bare 10-digit number starting with 6–9 is dialed as an Indian mobile, always include the country code for numbers outside India. CallMitra matches a caller or a do-not-call entry to your leads by the **last 10 digits** of the number, so `+91 98765 43210` and `09876543210` are the same person. ## Calling window [#calling-window] Every campaign has its own calling window. Outside it, CallMitra does not start new automatic calls. | Setting (in `settings`) | Default | Meaning | | --- | --- | --- | | `dialTimezone` | `Asia/Kolkata` | IANA time zone for the window and the daily limit. An unknown name falls back to UTC. | | `dialWindowStart` | `10:00` | First minute calls may start (`HH:MM`, inclusive). | | `dialWindowEnd` | `17:00` | Calls stop starting at this time (`HH:MM`, exclusive). `23:59` or `24:00` means midnight. | | `dialDaysOfWeek` | every day | Days calls may start: `0` = Monday … `6` = Sunday. | Send them in `settings` when you [create a campaign](/api-reference/campaigns/createCampaign) or [update it](/api-reference/campaigns/updateCampaign) (inside `campaignData.settings` with [create-with-leads](/api-reference/campaigns/createCampaignWithLeads)): ```json { "name": "EMI reminders, November", "agentId": "AGENT_ID", "settings": { "dialTimezone": "Asia/Kolkata", "dialWindowStart": "10:00", "dialWindowEnd": "19:00", "dialDaysOfWeek": [0, 1, 2, 3, 4, 5] } } ``` - A window can cross midnight (for example `22:00`–`06:00`), so double-check the values you send. - A lead whose turn comes outside the window **waits**: CallMitra schedules it for the next time the window opens. It is never skipped because of the window. - Callbacks a caller asks for are moved into the window too. - There is no holiday calendar. Remove dates you should not call with `dialDaysOfWeek` or pause the campaign. CallMitra does not force a 9:00–21:00 window. The console warns you when a window starts before 9:00 or ends after 21:00, but the campaign follows the hours you set. Keep commercial calls inside the hours the rules allow. **Calls that ignore the window.** A manual call runs immediately, whatever the window says: a [direct call](/api-reference/calls/createCall), [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow), [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) and the console's "Call now". Do-not-call is still enforced. Use them only for calls the person expects, such as an immediate callback request. Check where a campaign stands with [`GET /campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus): `inDialWindow`, `nextWindowOpenAt`, `skipReason` (`outside_window`, `outside_date_range`, `daily_cap`, `auto_dial_paused`, `first_call_delay`, `no_eligible_leads`, `inactive`) and a readable `lastErrorMessage`. ## Do-not-call [#do-not-call] A lead on the do-not-call list (`dncOptOut: true`) is never dialed automatically. **How a number gets on the list:** - You add it: [`POST /api/v1/leads/dnc`](/api-reference/do-not-call/addDoNotCall) with `phones` (comma- or newline-separated Indian mobiles) and an optional `reason`, or bulk-update leads with [`POST /api/v1/leads/bulk`](/api-reference/leads/bulkLeadAction) and `action: "dnc"`. A number without a lead gets a new lead so the block sticks. - The person asks during a call: if the caller says phrases such as "do not call", "stop calling", "remove me", "unsubscribe" or "opt out", or the post-call analysis classifies the call as an opt-out, the lead is marked do-not-call automatically. - The carrier reports the number does not exist (marked with reason `invalid_number`; editing the lead's phone clears it). - A data-erasure request. The AI agent can add a number to the list but can never remove one. Remove a number yourself with `DELETE /api/v1/leads/dnc/{lead_id}`; read the list with `GET /api/v1/leads/dnc`. Adding and removing need a key whose user is a workspace manager. **What it blocks:** - Automatic dialing skips every lead whose number matches a do-not-call entry anywhere in your workspace (last 10 digits). - A manual or direct call to a do-not-call number answers `409` [`number_on_dnc`](/errors/number_on_dnc). - Pending callbacks for the lead are cancelled, and new ones are refused. - Retries stop for calls that ended as an opt-out or a wrong number. ## Retries and daily limits [#retries-and-daily-limits] | Setting (in `settings`) | Default | Meaning | | --- | --- | --- | | `retryAttempts` | `3` | Maximum attempts per lead, 0–10 (`0` means a single attempt). | | `callInterval` | `7200000` (2 h) | Milliseconds between attempts, and the wait after no answer. | | `retryIntervalNoAnswerMs` | not set | Wait after no answer, if different from `callInterval`. | | `retryIntervalBusyMs` | `1800000` (30 min) | Wait after a busy line. | | `maxCallsPerDay` | `50` | Calls this campaign may start per day in its time zone. | | `maxConcurrentCalls` | 2 × the campaign's numbers | Live calls at once for this campaign (1–500). Accepted by the API but not yet listed in the reference schema. | | `pacingSeconds` | `5` | Pause between dialing rounds. Accepted by the API but not yet listed in the reference schema. | The daily limit is per campaign; a manual call on that campaign once it is reached answers `429` [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached). Each phone number also has its own limit of simultaneous calls (by default 50 for Plivo numbers and 2 for others; see [Indian carriers](/guides/indian-carriers#limits)). See [Run a campaign](/guides/campaigns). ## Caller ID series [#caller-id-series] Indian regulations reserve number series for commercial calling (140 for promotional and 1600 for service and transactional calls). When a campaign starts with a caller ID outside these series, the start response includes a warning. CallMitra never blocks the call for it: choosing the right numbers for your use case is up to you and your carrier. See [Indian carriers](/guides/indian-carriers). ## Recording notice and AI disclosure [#recording-notice-and-ai-disclosure] These are agent settings, on by default: - **Call recording** with a **recording notice**: the agent says a short notice in the call's language (for example "This call is being recorded.") before its greeting. The notice plays only when recording is on. - **AI disclosure**: if the caller seems to believe they are talking to a person, the agent says once that it is an AI assistant. Asked directly, it always answers honestly. CallMitra does not record consent for outbound calls. Keep your own record of how each person agreed to be called. # Indian carriers (/guides/indian-carriers) CallMitra does not sell phone numbers. You bring numbers from a carrier account you own, connect them once in the console, and every agent, campaign and API call can use them. ## Pick a carrier [#pick-a-carrier] | | Plivo | Vobiz | Twilio | Your own SIP trunk | | --- | --- | --- | --- | --- | | What you enter | Auth ID + auth token | SIP username, password, domain, outbound proxy, auth token | Account SID + auth token | Host, port, transport, auth (digest or IP) | | Inbound setup | **Connect automatically** | Paste two addresses in the Vobiz console | **Connect automatically** | In your PBX or trunk | | Simultaneous calls per number (default) | 50 | 2 | 2 | 10 | | New calls per second (account) | 2 | 2 | 1 | — | | Call transfer | Yes, with whisper | Yes, with whisper | Yes, with whisper | Yes, no whisper | Your own SIP trunk (Tata, Airtel, Jio, Exotel, Telnyx, DIDWW, FreePBX, 3CX and others) is available only when your CallMitra server has the SIP gateway turned on. Otherwise the console answers `SIP trunk calling is not enabled on this server yet`. ## Connect a number [#connect-a-number] In the console, open **Calls → Phone numbers → Add number**, choose the carrier, and fill in: 1. In [console.plivo.com](https://console.plivo.com), copy the **Auth ID** (starts with `MA` or `SA`) and **Auth token** from the account overview. 2. In CallMitra, enter the number in E.164 (`+91…`), the Auth ID and the auth token. 3. Click **Test connection**. 4. Under **Receive calls**, click **Connect automatically**. CallMitra creates a Plivo application named `call-mitra-inbound` and attaches your number to it. Trial Plivo accounts can only call and receive calls from numbers you have verified in Plivo. 1. From your Vobiz account, copy the SIP username, SIP password, SIP domain (`*.sip.vobiz.ai`) and the auth token. 2. In CallMitra, enter the number in E.164 and those values. The outbound proxy defaults to `13.233.44.61:5060`; change it only if Vobiz gives you another one. 3. Click **Test connection**. It checks that the SIP domain resolves and the proxy accepts a connection. 4. Vobiz is set up by hand: copy the answer and status addresses CallMitra shows under **Receive calls** into your Vobiz number's settings. 1. In [console.twilio.com](https://console.twilio.com), copy the **Account SID** (starts with `AC`) and **Auth token** from Account Info. 2. In CallMitra, enter the number in E.164, the Account SID and the auth token. Enter both: outbound calls need them. 3. Click **Test connection**. 4. Under **Receive calls**, click **Connect automatically**. CallMitra points the number's voice webhook at itself. Carrier secrets are stored encrypted and never returned. The API shows only whether each one is set. Then call yourself from the agent page (**Call my phone**, or [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent)) to check the number end to end. ### Inbound addresses [#inbound-addresses] If you set up a carrier by hand, these are the addresses on your CallMitra API host: | Carrier | Answer URL | Status / hangup URL | | --- | --- | --- | | Plivo | `/sip-assistant/voice/plivo/incoming` | `/api/webhooks/call-events?vp_provider=plivo` | | Vobiz | `/sip-assistant/voice/vobiz/incoming` | `/api/webhooks/call-events?vp_provider=vobiz` | | Twilio | `/sip-assistant/voice/incoming` | set by CallMitra | CallMitra checks the carrier's signature on these requests and answers `403` when it does not match, so the auth token you entered must be the one for the account that owns the number. ## Outbound calls [#outbound-calls] **Which number calls out.** CallMitra uses the first of: 1. the phone number you pass on the request (for example `phoneNumberId`); 2. the campaign's phone number; 3. the number assigned to the agent. When a campaign or agent has a pool of numbers, each call goes out on the least busy one. **Ringing and results.** An unanswered call rings for about 40 seconds. Every call ends as `completed`, `busy`, `no_answer` or `failed`, and the [`call.completed`](/webhooks/events) webhook carries the result. Voicemail is detected after the call, from the conversation, and shows up in the call analysis. **Recording.** When the agent's call recording setting is on, CallMitra records the call itself (stereo MP3). Fetch it with [`GET /api/v1/calls/{call_id}/recording`](/api-reference/calls/getCallRecording). ## Inbound calls [#inbound-calls] When someone calls one of your numbers, CallMitra picks the agent in this order: 1. the caller rules of the number's inbound campaign; 2. the agent the caller last spoke to, within 30 days, when the line is set to call back to the last agent; 3. the number's default inbound campaign; 4. the agent the number is assigned to. If none applies, the caller hears that the number is not taking calls right now. An inbound line can also have operating hours (with an after-hours message) and a limit on simultaneous inbound calls (10 by default). ## Limits [#limits] Calls are refused with a `409` when a limit is reached and resume as soon as a call ends: | Limit | Default | | --- | --- | | Simultaneous calls per phone number | 50 for Plivo, 2 for the others, at most 200. The console fills in 50 when you add a number; change it under the number's settings. | | Plivo account | 50 live calls, 2 new calls per second | | Twilio account | 1 new call per second | | Vobiz account | 2 new calls per second | | Simultaneous calls per workspace | 500 | | Simultaneous calls per campaign | `maxConcurrentCalls`, 1–500 | Set the per-number limit to what your carrier plan allows. A number above its carrier's real channel count produces failed calls rather than a CallMitra refusal. ## Caller ID series [#caller-id-series] Numbers in the 140 series are for promotional calls and the 1600 series for service and transactional calls. CallMitra warns when a campaign starts on a number outside these series but does not block it; the right series for your traffic is between you and your carrier. See [Calling in India](/guides/india-calling) for calling windows and do-not-call rules. ## Through the API [#through-the-api] [`GET /api/v1/phone-numbers/`](/api-reference/phone-numbers/listPhoneNumbers) lists your connected numbers and their IDs, which you pass as `phoneNumberId` on campaigns and calls. Adding, editing and connecting numbers is done in the console for now. # Leads and callbacks (/guides/leads) A **lead** is one person your agents can call. Campaigns dial leads, calls are logged against them, and the details you store on a lead become variables your agent can speak. ## The lead model [#the-lead-model] [`GET /api/v1/leads/{lead_id}`](/api-reference/leads/getLead) returns the full lead. The fields you will use most: | Field | Meaning | | --- | --- | | `id` | CallMitra lead ID. | | `name`, `phone`, `email`, `company`, `title` | Core contact fields. `phone` is stored in E.164 (see [Phone numbers](#phone-numbers)). | | `status` | Pipeline stage. One of your workspace's pipeline keys; `new` by default. | | `source`, `leadSourceId` | Where the lead came from, and the lead source it belongs to. | | `externalId` | Your own ID for the lead, up to 64 characters. Unique inside a lead source. | | `attributes` | Your own fields, as an object of key and value. | | `attributeIssues` | Values that did not fit their field type: `{ key: { raw, reason, at } }`. | | `tags` | Free-form labels. | | `assignedToUserId`, `assigneeName` | Teammate who owns the lead. | | `campaignIds`, `campaignNames` | Campaigns the lead is on. | | `callStatus`, `callAttempts`, `lastCallAttempt`, `lastContactDate` | Calling history at a glance. | | `nextCallScheduled` | Time of the lead's next booked callback, if any. | | `dncOptOut`, `dncReason`, `dncUpdatedAt` | Do-not-call state. | | `notesCount`, `pinnedNotePreview` | Notes summary. `notes` is deprecated; use [notes](#notes-and-timeline). | | `createdAt`, `updatedAt` | Timestamps. | ### Create a lead [#create-a-lead] [`POST /api/v1/leads/`](/api-reference/leads/createLead) takes `name`, `phone`, `email`, `company`, `title`, `status`, `source`, `leadSourceId`, `campaignIds`, `attributes`, and `notes` (saved as the lead's first note). Send an [`Idempotency-Key`](/idempotency) header so a retried request does not create the lead twice. ```bash curl -X POST https://api.callmitra.ai/api/v1/leads/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: crm-1042-create" \ -d '{ "name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com", "attributes": { "plan": "Gold", "renewal_date": "2026-12-01" } }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/leads/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': 'crm-1042-create', }, body: JSON.stringify({ name: 'Asha Rao', phone: '9876543210', email: 'asha@example.com', attributes: { plan: 'Gold', renewal_date: '2026-12-01' }, }), }); const body = await res.json(); ``` ```python import os, requests res = requests.post( "https://api.callmitra.ai/api/v1/leads/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "crm-1042-create", }, json={ "name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com", "attributes": {"plan": "Gold", "renewal_date": "2026-12-01"}, }, timeout=30, ) body = res.json() ``` The phone above is saved as `+919876543210`. An unknown `status` is saved as `new` and reported in the response's `warnings`. CallMitra sends a [`lead.created`](/api-reference/webhooks/onLeadCreated) webhook. `createLead` always creates a new lead. It does not match on phone, and it does not accept `externalId`. To keep one lead per record in your system, store our `id`, or set `externalId` with an update and look the lead up before creating. The [lead intake webhook](#push-leads-from-forms) does deduplicate. ### Update a lead [#update-a-lead] [`PUT /api/v1/leads/{lead_id}`](/api-reference/leads/updateLead) is a partial update: send only the fields you change. - `externalId` accepts a string or a number. It is trimmed and limited to 64 characters. - `tags` and `campaignIds` replace the current lists. Campaigns you cannot access are skipped. - `attributes` merges into the current object. Set a key to `null` to clear it. - `timezone` takes an IANA name such as `Asia/Kolkata`; an invalid name returns `422`. - `additionalData` is refused with `422`. Send `attributes` instead. To avoid overwriting someone else's edit, send the lead's `updatedAt` in an `If-Match` header. If the lead changed since you read it, you get `409` [`lead_changed`](/errors/lead_changed). CallMitra sends a [`lead.updated`](/api-reference/webhooks/onLeadUpdated) webhook after each update. [`DELETE /api/v1/leads/{lead_id}`](/api-reference/leads/deleteLead) removes the lead permanently. Its calls stay in your call history. [`POST /api/v1/leads/bulk`](/api-reference/leads/bulkLeadAction) applies one action (`status`, `assign`, `tag`, `untag`, `dnc`, `undnc`, `delete`) to 1 to 500 lead IDs at once. List leads with [`GET /api/v1/leads/`](/api-reference/leads/listLeads). See [Pagination](/pagination) for page and cursor options. ## Lead fields and attributes [#lead-fields-and-attributes] Your workspace keeps a catalogue of lead fields. [`GET /api/v1/lead-fields/catalog`](/api-reference/leads/listLeadFields) returns it, sorted by label: ```json { "fields": [ { "id": "6f1c…", "key": "plan", "label": "Plan", "valueType": "text" }, { "id": "8a2d…", "key": "renewal_date", "label": "Renewal date", "valueType": "date" } ] } ``` Each field's `key` is the key you use in a lead's `attributes`. `valueType` is one of `text`, `number`, `boolean`, `list`, `date` or `datetime`. ```bash curl https://api.callmitra.ai/api/v1/lead-fields/catalog \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/lead-fields/catalog', { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }); const { fields } = await res.json(); ``` ```python res = requests.get( "https://api.callmitra.ai/api/v1/lead-fields/catalog", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30, ) fields = res.json()["fields"] ``` How `attributes` are written: - Keys are turned into lowercase `snake_case` (letters, digits and `_`). `Renewal Date` becomes `renewal_date`. - `name`, `phone`, `email`, `company` and `title` fill the matching core field when that field is empty. - Reserved keys are ignored: `agent_name`, `caller_name`, `campaign_name`, `callback_number`, `timestamp`, `source`, `id`, `row`, `notes`. - A key that is not in the catalogue creates a new `text` field, flagged for review in the console. - A value that does not fit its field type is never rejected. It is kept in `attributeIssues` and reported in `warnings`, so you can fix it later. ### Agent variables [#agent-variables] Your agent's prompt and first message can use `{{variable}}` placeholders. On every call, CallMitra fills them from the lead: - Core fields: `{{lead_name}}` (also `{{customer_name}}`), `{{lead_first_name}}`, `{{lead_last_name}}`, `{{lead_phone}}`, `{{lead_email}}`, `{{lead_company}}`. - Context: `{{campaign_name}}`, `{{agent_name}}`. - Every attribute key: `plan` becomes `{{plan}}`. Fields marked sensitive or archived are never sent to the agent. - Answers your agent captured on earlier calls with the same lead. A campaign whose agent uses a placeholder that no lead can fill does not start: you get `422` [`campaign_not_ready`](/errors/campaign_not_ready) listing the unresolved placeholders. ## Phone numbers [#phone-numbers] `createLead` and `updateLead` normalise `phone` to E.164 before saving. An empty phone is allowed. 1. If the value holds several numbers separated by `,` `/` `|` or `;`, the first one is used. A trailing `.0` (from spreadsheets) is removed, and spaces, dashes and brackets are ignored. 2. A number that starts with `+` or `00` is international. After dropping leading zeros, a 10-digit number starting with 6 to 9 becomes `+91…`; any other 8 to 15 digit number is kept as `+` and its digits. 3. Without `+` or `00`, leading zeros are dropped. A 10-digit number becomes `+91…`. A number starting with `91` followed by 7 to 11 digits is kept as `+91…`. 4. Anything else is refused with `422` [`invalid_phone_number`](/errors/invalid_phone_number) on `param: "phone"`. | You send | Saved as | | --- | --- | | `9876543210` | `+919876543210` | | `09876543210` | `+919876543210` | | `919876543210` | `+919876543210` | | `+44 20 7946 0958` | `+442079460958` | | `12345` | `422 invalid_phone_number` | Send numbers from other countries with `+` or `00` and the country code. Without it, a 10-digit number is read as an Indian mobile. ## Do-not-call [#do-not-call] Leads on your do-not-call list are never dialed. Add numbers with [`POST /api/v1/leads/dnc`](/api-reference/do-not-call/addDoNotCall) (`phones` as a newline- or comma-separated string, optional `reason`), list them with [`GET /api/v1/leads/dnc`](/api-reference/do-not-call/listDoNotCall), and remove one with [`DELETE /api/v1/leads/dnc/{lead_id}`](/api-reference/do-not-call/removeDoNotCall). Only Indian mobile numbers are accepted; if none are valid you get `422` [`dnc_no_valid_numbers`](/errors/dnc_no_valid_numbers). Calling a number on the list returns `409` [`number_on_dnc`](/errors/number_on_dnc). See [Calling in India](/guides/india-calling) for the rules. ## Notes and timeline [#notes-and-timeline] - **Notes.** [`GET /api/v1/leads/{lead_id}/notes`](/api-reference/lead-notes/listLeadNotes) lists a lead's notes, with pinned notes on the first page. Create, edit, pin and delete notes with the other [lead notes](/api-reference/lead-notes/createLeadNote) endpoints. An edit must send the note's `version`; if it changed, you get `409` [`lead_note_changed`](/errors/lead_note_changed). A lead can have at most 3 pinned notes ([`lead_note_pin_limit`](/errors/lead_note_pin_limit)). - **Timeline.** [`GET /api/v1/leads/{lead_id}/timeline`](/api-reference/leads/getLeadTimeline) returns one feed of calls, WhatsApp messages, tickets, notes, changes and callbacks. Filter with `types`. The first page also lists upcoming callbacks. Both are cursor lists; see [Pagination](/pagination). ## Callbacks [#callbacks] A **callback** is a call CallMitra places to a lead at a set time. Callbacks are booked: - by your agent during a call, when the agent has the schedule-callback tool turned on and the caller asks to be called later (`source` is `ai_tool`); - from the call analysis after a call; - by your team in the console, or from a CSV import; - by reminder rules (`kind` is `reminder`, `source` is `rule`). Rules a callback follows: - A lead has at most one active callback. A newer one replaces a pending one. - Callbacks can be booked up to 60 days ahead. If the time falls outside the campaign's calling window, `dialAt` moves to the next allowed time and `shifted` is `true`. - A callback that is not answered is retried after 30 minutes, up to the campaign's callback attempt limit (2 by default, 1 to 5). - While a lead has a callback booked (`nextCallScheduled`), bulk campaign dialing skips it. ### List callbacks [#list-callbacks] [`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) lists callbacks, soonest `dialAt` first. | Parameter | Meaning | | --- | --- | | `status` | Comma-separated statuses, or `all`. Default `pending,queued,dialing` (still to happen). | | `kind` | `callback` or `reminder`. | | `leadId`, `campaignId`, `agentId` | Only callbacks for this lead, campaign or agent. Must be UUIDs. | | `dateFrom`, `dateTo` | ISO 8601 bounds on `dialAt`. A time without an offset is read as UTC. | | `limit`, `offset` | Page size (default `50`, 1 to 200) and items to skip. | Statuses: `pending`, `queued`, `dialing`, `done`, `failed`, `cancelled`, `expired`. An unknown status or a bad UUID or date returns `422` [`parameter_invalid`](/errors/parameter_invalid). ```bash curl "https://api.callmitra.ai/api/v1/callbacks?leadId=LEAD_ID&status=all" \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const url = new URL('https://api.callmitra.ai/api/v1/callbacks'); url.searchParams.set('leadId', leadId); url.searchParams.set('status', 'all'); const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }); const { callbacks, total } = await res.json(); ``` ```python res = requests.get( "https://api.callmitra.ai/api/v1/callbacks", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params={"leadId": lead_id, "status": "all"}, timeout=30, ) data = res.json() callbacks, total = data["callbacks"], data["total"] ``` Each item carries `id`, `leadId`, `leadName`, `leadPhone`, `campaignId`, `campaignName`, `agentId`, `kind`, `channel`, `purpose`, `note`, `source`, `status`, `dueAt` (the time asked for), `dialAt` (the time it will be dialed), `dialAtLocal`, `shifted`, `timezone`, `attempts`, `maxAttempts`, `lastOutcome`, `callId` (the callback call), `originCallId` (the call that booked it) and `createdAt`. `total` counts every match. To hear about callbacks as they happen, subscribe to [`callback.scheduled`](/api-reference/webhooks/onCallbackScheduled), [`callback.completed`](/api-reference/webhooks/onCallbackCompleted) and [`callback.failed`](/api-reference/webhooks/onCallbackFailed). See [Webhook events](/webhooks/events). ## Push leads from forms [#push-leads-from-forms] A lead intake webhook lets a form, ad platform or your own system add leads without an API key. Each integration has its own URL and key. Send the lead to [`POST /api/v1/webhooks/leads/{webhook_token}`](/api-reference/lead-intake-webhook/pushLead) with the key in the `X-Lead-Webhook-Key` header (or `?key=` in the URL). The body is a flat JSON object: - `name`, `phone`, `email`, `company`, `title` fill the core fields. A lead needs `phone` or `email`. - `lead_id` (or `leadId`, `leadgen_id`, `id`) is your ID for the lead. It is saved as `externalId`. - Any other key and simple value is saved in `attributes`. - Google Ads lead forms (`user_column_data`) and Meta lead ads (`field_data`) payloads are understood as sent. - `is_test: true` checks your setup without creating a lead. ```bash curl -X POST https://api.callmitra.ai/api/v1/webhooks/leads/WEBHOOK_TOKEN \ -H "X-Lead-Webhook-Key: $LEAD_WEBHOOK_KEY" \ -H "Content-Type: application/json" \ -d '{ "lead_id": "form-88213", "name": "Asha Rao", "phone": "+919876543210", "city": "Pune" }' ``` ```js await fetch(`https://api.callmitra.ai/api/v1/webhooks/leads/${webhookToken}`, { method: 'POST', headers: { 'X-Lead-Webhook-Key': process.env.LEAD_WEBHOOK_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ lead_id: 'form-88213', name: 'Asha Rao', phone: '+919876543210', city: 'Pune' }), }); ``` ```python requests.post( f"https://api.callmitra.ai/api/v1/webhooks/leads/{webhook_token}", headers={"X-Lead-Webhook-Key": os.environ["LEAD_WEBHOOK_KEY"]}, json={"lead_id": "form-88213", "name": "Asha Rao", "phone": "+919876543210", "city": "Pune"}, timeout=30, ) ``` A new lead returns `{ "success": true, "leadId": "…", "externalLeadId": "form-88213", "campaignAttached": true }`. When the integration is linked to a campaign, the lead is added to it. Repeats are safe. The webhook deduplicates per integration on `lead_id`; without one, on the source, phone, email, name and form. A repeat returns `{ "success": true, "duplicate": true, "externalLeadId": "…" }` and creates nothing. | Status | Body | Why | | --- | --- | --- | | `400` | `{ "success": false, "error": "Lead must include phone or email" }` | No phone and no email. | | `401` | `{ "success": false, "error": "invalid webhook key" }` | Missing or wrong webhook key. | | `404` | `{ "success": false, "error": "invalid token" }` or `"integration not found"` | Unknown webhook token. | | `429` | `{ "success": false, "error": "rate limit" }` | More than 300 requests a minute from one IP address. | | `500` | `{ "success": false, … }` | Our error. Retry; deduplication absorbs repeats. | The intake webhook does not refuse a lead for its phone format. It saves the number with a `+` prefix, so send it in E.164. # Tickets (/guides/tickets) Tickets track customer requests in CallMitra's helpdesk. Your agents and your team open them in calls, WhatsApp chats and the console. With the API you can create tickets from your own systems, keep them in sync, add notes and reply to the customer. | Endpoint | What it does | | --- | --- | | [`GET /api/v1/tickets/`](/api-reference/tickets/listTickets) | List and filter tickets | | [`POST /api/v1/tickets/`](/api-reference/tickets/createTicket) | Create a ticket | | [`GET /api/v1/tickets/{ticket_id}`](/api-reference/tickets/getTicket) | Get a ticket with its latest activities | | [`PATCH /api/v1/tickets/{ticket_id}`](/api-reference/tickets/updateTicket) | Update a ticket | | [`GET /api/v1/tickets/{ticket_id}/activities`](/api-reference/tickets/listTicketActivities) | Page through older activities | | [`POST /api/v1/tickets/{ticket_id}/activities`](/api-reference/tickets/addTicketNote) | Add a private team note | | [`POST /api/v1/tickets/{ticket_id}/replies`](/api-reference/tickets/replyToTicket) | Reply to the customer on WhatsApp | | [`GET /api/v1/tickets/categories`](/api-reference/tickets/listTicketCategories) | List categories | | [`GET /api/v1/tickets/teams`](/api-reference/tickets/listTicketTeams) | List teams | A key limited to resources needs **Tickets** ([Authentication](/authentication)). ## The ticket [#the-ticket] | Field | Description | | --- | --- | | `id` | Ticket ID. | | `ref` | Short reference shown to people, for example `T-1A2B3C4D`. | | `subject`, `description` | One-line summary and details. | | `status` | `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`. | | `priority` | `low`, `normal`, `high` or `urgent`. | | `type` | `support` or `sales_followup`. | | `source` | How it was opened: `manual`, `inbound_call`, `outbound_call`, `import` or `whatsapp_conversation`. | | `leadId`, `leadName`, `leadPhone` | The lead (customer) the ticket is about. Every ticket has one. | | `sourceCallId` | The call that opened the ticket, if any. | | `waConversationId` | The WhatsApp conversation it came from, if any. | | `categoryId`, `categoryName` | The category, or `null`. | | `teamId`, `teamName` | The team it is routed to, or `null`. | | `assignees` | Everyone assigned (`userId`, `name`, `email`), in assignment order. | | `assignedToUserId` | The first assignee's user ID, or `null` when unassigned. | | `tags` | Tags. | | `dueAt`, `overdue` | Resolution due time, and whether it has passed without the ticket being resolved. | | `sla` | Service-level targets: `firstResponse`, `resolution` and `paused`. | | `createdAt`, `updatedAt`, `resolvedAt`, `closedAt` | Timestamps (ISO 8601). | | `mergedIntoId` | Set when the ticket was merged into another. A merged ticket is read-only. | | `version` | Goes up on every change. Send it back to avoid overwriting someone else's change. | A single ticket ([get](/api-reference/tickets/getTicket), and the `ticket` in update responses) also has `canEdit`, `canManageAssignees` and `canReopenClosed`: what the key's user may do with it. ## List tickets [#list-tickets] The list is sorted by last change, newest first. It is paged with `page` and `limit` (default 25, up to 200). See [Pagination](/pagination). | Query parameter | Description | | --- | --- | | `page`, `limit` | Page number from 1, and tickets per page (1–200). | | `search` | Ticket ref, words in the subject or description, or the lead's name or phone. | | `status` | One status. `open` also matches `in_progress` and `waiting_on_customer`. | | `priority` | `low`, `normal`, `high` or `urgent`. | | `type` | `support` or `sales_followup`. | | `leadId` | Only this lead's tickets. | | `sourceCallId` | Only tickets opened from this call. | | `categoryId` | Category ID, or `none` for tickets without one. | | `teamId` | Team ID, or `none` for tickets without one. | | `tag` | Only tickets with this tag. | | `unassigned` | `true` for tickets nobody is assigned to. | | `sort` | `updated` (the default), `created`, `due`, `priority` or `status`. | | `dir` | `asc` or `desc`. | ```bash curl "https://api.callmitra.ai/api/v1/tickets/?status=open&priority=urgent&limit=50" \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const params = new URLSearchParams({ status: 'open', priority: 'urgent', limit: '50' }); const res = await fetch(`https://api.callmitra.ai/api/v1/tickets/?${params}`, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }); const { tickets, pagination } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.callmitra.ai/api/v1/tickets/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params={"status": "open", "priority": "urgent", "limit": 50}, timeout=30, ) data = res.json() tickets, pagination = data["tickets"], data["pagination"] ``` ```json { "success": true, "tickets": [ { "id": "a1b2c3d4-0000-4000-8000-000000000001", "ref": "T-A1B2C3D4", "subject": "Refund not received", "status": "open", "priority": "urgent", "type": "support", "leadId": "5e6f7a8b-0000-4000-8000-000000000002", "leadName": "Asha Verma", "leadPhone": "+919812345678", "teamId": null, "assignees": [], "version": 3 } ], "pagination": { "currentPage": 1, "itemsPerPage": 50, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false, "totalCapped": false }, "sort": { "key": "updated", "dir": "desc" } } ``` The ticket above is shortened. `totalCapped` is `true` when `totalItems` stopped counting at the cap. ## Create a ticket [#create-a-ticket] Every ticket belongs to a lead. Send `leadId`, or `waConversationId` to open the ticket from a WhatsApp conversation (its contact's lead is used and `source` becomes `whatsapp_conversation`). If you send both, they must point to the same lead. Sending neither fails with `422` [`parameter_invalid`](/errors/parameter_invalid). | Field | Description | | --- | --- | | `subject` | Required. One-line summary, 1–512 characters. | | `description` | Details, up to 20,000 characters. | | `leadId` | The lead the ticket is about. | | `waConversationId` | A WhatsApp conversation, instead of `leadId`. | | `type` | `support` (the default) or `sales_followup`. | | `priority` | `low`, `normal`, `high` or `urgent`. Default: the category's priority, else `normal`. | | `categoryId` | A category ID from [List categories](#categories-and-teams). | | `tags` | Up to 20 tags. | | `assignedToUserId` | Assign one team member (user ID). | | `assignedUserIds` | Assign several team members (up to 50). Wins over `assignedToUserId`. | | `sourceCallId` | The call the ticket came from. | | `dueAt` | Resolution due time (ISO 8601). | The category and the source decide the ticket's team. The team's rules may then assign it automatically. Send an `Idempotency-Key` header so a retry does not create a second ticket ([Idempotency](/idempotency)). ```bash curl -X POST https://api.callmitra.ai/api/v1/tickets/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Idempotency-Key: crm-case-88213" \ -H "Content-Type: application/json" \ -d '{ "leadId": "5e6f7a8b-0000-4000-8000-000000000002", "subject": "Refund not received", "description": "Order #1042, refund started on 10 Jan.", "priority": "high", "tags": ["refund"] }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/tickets/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Idempotency-Key': 'crm-case-88213', 'Content-Type': 'application/json', }, body: JSON.stringify({ leadId: '5e6f7a8b-0000-4000-8000-000000000002', subject: 'Refund not received', description: 'Order #1042, refund started on 10 Jan.', priority: 'high', tags: ['refund'], }), }); const { ticket } = await res.json(); ``` ```python res = requests.post( "https://api.callmitra.ai/api/v1/tickets/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "crm-case-88213", }, json={ "leadId": "5e6f7a8b-0000-4000-8000-000000000002", "subject": "Refund not received", "description": "Order #1042, refund started on 10 Jan.", "priority": "high", "tags": ["refund"], }, timeout=30, ) ticket = res.json()["ticket"] ``` The response is `{"success": true, "ticket": {...}}`, the same as [Get a ticket](/api-reference/tickets/getTicket). ## Get a ticket [#get-a-ticket] [`GET /api/v1/tickets/{ticket_id}`](/api-reference/tickets/getTicket) returns the ticket with its latest `activities`, oldest first. When `hasOlderActivities` is `true`, pass `activitiesCursor` as `before` to [`GET /api/v1/tickets/{ticket_id}/activities`](/api-reference/tickets/listTicketActivities) to read older ones (`limit` default 50, up to 200). Each page returns the next `activitiesCursor`; stop when `hasOlderActivities` is `false`. Each activity has `id`, `ticketId`, `activityType`, `actorUserId` (`null` for the customer or the system), `actorName`, `createdAt` and `payload`. Common `activityType` values are `created`, `comment` (a note, its text in `payload.note`), `reply`, `status_change` and `assignment`. ## Update a ticket [#update-a-ticket] [`PATCH /api/v1/tickets/{ticket_id}`](/api-reference/tickets/updateTicket) changes only the fields you send: | Field | Description | | --- | --- | | `subject`, `description` | Text fields. | | `status` | `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`. | | `priority` | `low`, `normal`, `high` or `urgent`. | | `type` | `support` or `sales_followup`. | | `dueAt` | Resolution due time (ISO 8601). | | `categoryId` | Category ID. `null` clears it. | | `teamId` | Team ID. `null` takes the ticket out of its team. | | `tags` | Replaces all tags (up to 20). | | `version` | The `version` you last read. If the ticket changed since, the request fails with `409` [`ticket_version_conflict`](/errors/ticket_version_conflict). Leave it out to skip the check. | Assignees can be set when you create a ticket. The update endpoint does not change them. ```bash curl -X PATCH https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001 \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "resolved", "version": 3 }' ``` The response holds `ticket` (the ticket after the change), `changed` (the fields that changed) and `activities` (only the activities this request added). Who may change what: - The key acts as the user who created it. If that user is an agent, it can change only tickets assigned to it or unassigned ones. Others fail with `403` [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden). - Reopening a `closed` ticket needs a manager's key. Otherwise it fails with `403` [`ticket_reopen_forbidden`](/errors/ticket_reopen_forbidden). - A merged ticket is read-only: changes fail with `409` [`ticket_merged`](/errors/ticket_merged). Update the ticket it was merged into. If your workspace set up ticket updates in the console (**Tickets → Settings**), a status change can also send the customer a WhatsApp update. ## Notes and replies [#notes-and-replies] There are two ways to write on a ticket: | | Note | Reply | | --- | --- | --- | | Endpoint | [`POST .../activities`](/api-reference/tickets/addTicketNote) | [`POST .../replies`](/api-reference/tickets/replyToTicket) | | Who sees it | Your team only | The customer, on WhatsApp | | `activityType` | `comment` | `reply` | | Retry safety | `Idempotency-Key` header | `clientId` in the body | ### Add a note [#add-a-note] Send `note` (up to 8000 characters). You can also send `status` to move the ticket in the same request, and `version` for the conflict check. ```bash curl -X POST https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001/activities \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Idempotency-Key: crm-note-5521" \ -H "Content-Type: application/json" \ -d '{ "note": "Finance confirmed the refund on 14 Jan.", "status": "waiting_on_customer" }' ``` An empty note fails with `422` [`parameter_invalid`](/errors/parameter_invalid). ### Reply to the customer [#reply-to-the-customer] A reply goes to the ticket's customer on WhatsApp. It is sent from the number of the ticket's WhatsApp chat, or else from the ticket-updates number chosen in **Tickets → Settings**. Replies are off until a manager turns them on there. | Field | Description | | --- | --- | | `clientId` | Required. Your unique ID for this reply, 8–64 characters. A retry with the same `clientId` returns the first reply, with `replayed: true`, and never sends twice. | | `text` | Reply text, up to 4096 characters. Only within 24 hours of the customer's last message. | | `templateEvent` | Outside the window: the ticket event whose approved template to send, for example `waiting_on_customer`. Events are `created`, `in_progress`, `waiting_on_customer`, `resolved`, `resolved_rating` and `closed`; the template must be set up for that event in **Tickets → Settings**. Cannot be combined with `text`. | | `version` | The ticket `version` you last read (optional). | ```bash curl -X POST https://api.callmitra.ai/api/v1/tickets/a1b2c3d4-0000-4000-8000-000000000001/replies \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "clientId": "crm-reply-5522", "text": "Your refund is on its way." }' ``` ```js const res = await fetch( `https://api.callmitra.ai/api/v1/tickets/${ticketId}/replies`, { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ clientId: 'crm-reply-5522', text: 'Your refund is on its way.' }), }, ); ``` ```python res = requests.post( f"https://api.callmitra.ai/api/v1/tickets/{ticket_id}/replies", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, json={"clientId": "crm-reply-5522", "text": "Your refund is on its way."}, timeout=30, ) ``` The reply is queued for sending and recorded on the ticket right away. When it cannot be sent, nothing is sent and the request fails with `409` [`ticket_reply_blocked`](/errors/ticket_reply_blocked). `detail.code` says why: | `detail.code` | Reason | | --- | --- | | `replies_off` | Customer replies are turned off in **Tickets → Settings**. | | `no_number` | No WhatsApp number to reply from. | | `number_offline` | The WhatsApp number is not connected. | | `no_phone` | The lead has no valid phone number. | | `dnc` | The customer is on do-not-contact. | | `opted_out` | The customer opted out of WhatsApp messages. | | `window_closed` | The 24-hour window is closed. Send `templateEvent` instead of `text`. | ## Categories and teams [#categories-and-teams] - [`GET /api/v1/tickets/categories`](/api-reference/tickets/listTicketCategories) lists categories in display order. Each has `id`, `name`, `isActive`, `sortOrder`, `defaultPriority` and `defaultTeamId`. Inactive categories are included unless you send `includeInactive=false`. - [`GET /api/v1/tickets/teams`](/api-reference/tickets/listTicketTeams) lists teams by name. Each has `id`, `name`, `isDefault`, `members` and `assignmentMode` (`manual`, `round_robin` or `least_busy`). A new ticket goes to its category's `defaultTeamId`. When neither its category nor its source picks a team, it goes to the team with `isDefault: true`. Categories and teams are managed in the console. ## Webhooks [#webhooks] Get ticket changes pushed to you instead of polling: | Event | When | | --- | --- | | [`ticket.created`](/api-reference/webhooks/onTicketCreated) | A ticket was opened. | | [`ticket.updated`](/api-reference/webhooks/onTicketUpdated) | A ticket changed. | | [`ticket.resolved`](/api-reference/webhooks/onTicketResolved) | A ticket was resolved. | | [`ticket.reopened`](/api-reference/webhooks/onTicketReopened) | A ticket was opened again. | | [`ticket.rated`](/api-reference/webhooks/onTicketRated) | A customer rated a ticket. | See [Webhook events](/webhooks/events) for the payloads. ## Errors [#errors] | Status | Code | When | | --- | --- | --- | | `403` | [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden) | The key's user is an agent and the ticket is assigned to someone else. | | `403` | [`ticket_reopen_forbidden`](/errors/ticket_reopen_forbidden) | Reopening a closed ticket without a manager's key. | | `404` | [`resource_not_found`](/errors/resource_not_found) | The ticket, lead or conversation does not exist in your workspace. | | `409` | [`ticket_version_conflict`](/errors/ticket_version_conflict) | The ticket changed since the `version` you sent. Fetch it again and retry. | | `409` | [`ticket_merged`](/errors/ticket_merged) | The ticket was merged into another and is read-only. | | `409` | [`ticket_reply_blocked`](/errors/ticket_reply_blocked) | The reply cannot be sent; see `detail.code`. | | `409` | [`ticket_attachment_unavailable`](/errors/ticket_attachment_unavailable) | One of the `attachmentIds` was already used or removed. Attachments are uploaded in the console; API integrations normally leave `attachmentIds` out. | | `409` | [`idempotency_key_reused`](/errors/idempotency_key_reused) | Same `Idempotency-Key`, different body. | | `422` | [`parameter_invalid`](/errors/parameter_invalid) | A field is missing or invalid. | Every error uses the standard [error envelope](/errors). # Web calls (/guides/web-calls) Browser (web) calls from your own site or app are not yet available through the public API. They are on the roadmap. What you can use today: - **Test an agent in the browser.** In the console, open **Agents → Test console** to talk to an agent in the browser, chat with it, or have it call your phone. This works only inside the console. - **Hear an agent on your phone.** [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) calls a number from one of your numbers so you can hear the agent. See [Agents](/guides/agents). - **Call your customers.** Place a phone call with [`POST /api/v1/calls/`](/api-reference/calls/createCall) ([Direct calls](/guides/direct-calls)), or run [campaigns](/guides/campaigns). # WhatsApp messages (/guides/whatsapp) The WhatsApp API sends messages from your connected WhatsApp Business number. You can send approved templates at any time and free-form messages while the customer's 24-hour window is open. You can also read a message's delivery status and list your templates. | Endpoint | What it does | | --- | --- | | [`POST /api/v1/whatsapp/messages`](/api-reference/whatsapp/sendWhatsAppMessage) | Send a message | | [`GET /api/v1/whatsapp/messages/{message_id}`](/api-reference/whatsapp/getWhatsAppMessage) | Get a message and its status | | [`GET /api/v1/whatsapp/message-templates`](/api-reference/whatsapp/listWhatsAppTemplates) | List your templates | Request and response fields are camelCase. ## Before you start [#before-you-start] - **Connect a number.** Connect your WhatsApp Business number in the console under **WhatsApp → Numbers**. Until a number is connected, sends fail with `409` [`whatsapp_number_not_connected`](/errors/whatsapp_number_not_connected). - **Get templates approved.** Create templates in WhatsApp Manager or the console. A template created in WhatsApp Manager shows up in the API after a template sync in the console. - **Use an API key with WhatsApp access.** A key limited to resources needs **WhatsApp** ([Authentication](/authentication)). A read-only key can list templates and read messages, but cannot send. ## The 24-hour window [#the-24-hour-window] WhatsApp decides what you may send by the customer service window: | Message `type` | When you can send it | | --- | --- | | `template` | Any time. The template must be approved. | | `text`, `image`, `video`, `audio`, `document`, `sticker`, `interactive`, `location`, `contacts` | Only within 24 hours of the customer's last message to that number. | Outside the window a free-form send fails with `409` [`whatsapp_window_closed`](/errors/whatsapp_window_closed) and nothing is sent. Send an approved template instead. The window opens again when the customer replies. The [`whatsapp.message.received`](/api-reference/webhooks/onWhatsappMessageReceived) webhook tells you when a customer writes, with `windowOpen` and `serviceWindowExpiresAt`. ## Send a message [#send-a-message] ```bash curl -X POST https://api.callmitra.ai/api/v1/whatsapp/messages \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Idempotency-Key: order-1042-shipped" \ -H "Content-Type: application/json" \ -d '{ "to": "+919812345678", "type": "template", "template": { "name": "order_update", "language": "en", "values": { "body": ["Asha", "#1042"] } } }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/whatsapp/messages', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Idempotency-Key': 'order-1042-shipped', 'Content-Type': 'application/json', }, body: JSON.stringify({ to: '+919812345678', type: 'template', template: { name: 'order_update', language: 'en', values: { body: ['Asha', '#1042'] }, }, }), }); const message = await res.json(); ``` ```python import os import requests res = requests.post( "https://api.callmitra.ai/api/v1/whatsapp/messages", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "order-1042-shipped", }, json={ "to": "+919812345678", "type": "template", "template": { "name": "order_update", "language": "en", "values": {"body": ["Asha", "#1042"]}, }, }, timeout=30, ) message = res.json() ``` Response: ```json { "id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10", "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2", "status": "accepted", "conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44", "error": null, "createdAt": "2026-01-15T09:30:00+00:00" } ``` Keep `id`. You need it to read the message later. ### Request body [#request-body] | Field | Type | Description | | --- | --- | --- | | `to` | string | Recipient in international format, for example `+919812345678`. Up to 32 characters. Send `to` or `contactId`. | | `contactId` | string | ID of an existing WhatsApp contact, instead of `to`. | | `phoneId` | string | ID of your sending WhatsApp number. Leave it out to send from your default number. An ID that is not a valid UUID fails with `422`; it never falls back to the default number. | | `type` | string | `template` (the default), `text`, `image`, `video`, `audio`, `document`, `sticker`, `interactive`, `location` or `contacts`. | | `template` | object | Required for `type: "template"`. See below. | | `text` | string | The message text for `type: "text"`. Up to 4096 characters. Must not be empty. | | `media` | object | Required for media types (`image`, `video`, `audio`, `document`, `sticker`). See below. | | `content` | object | For `interactive`, `location` or `contacts`: the object the WhatsApp Cloud API takes under that key. | | `optIn` | object | Records the recipient's opt-in with this send: `source` (required, up to 64 characters, for example `checkout`) and `text` (the consent wording the customer agreed to, up to 2000 characters). | `template`: | Field | Description | | --- | --- | | `name` | Template name exactly as approved. | | `language` | Template language code, for example `en` or `en_US`. | | `values` | Values for the template's variables: `body` as a list in order (or an object keyed by placeholder, such as `{"1": "Asha"}`), plus `header` and `buttons` when the template has them. | | `components` | Advanced: WhatsApp Cloud API `components`, sent as-is instead of `values`. | Find `name` and `language` with [List templates](#list-templates). A missing variable fails with `422` [`parameter_invalid`](/errors/parameter_invalid) on `template.values`. `media`: | Field | Description | | --- | --- | | `link` | Public `https://` URL of the file. Other schemes fail with `422`. | | `id` | WhatsApp media ID of a file you already uploaded. Send `link` or `id`. | | `caption` | Caption shown under an image, video or document. Up to 1024 characters. | | `filename` | File name shown for a document. | A free-form text message: ```json { "to": "+919812345678", "type": "text", "text": "Your order #1042 has shipped." } ``` ### Consent [#consent] - If the recipient has opted out of your WhatsApp messages, every send fails with `409` [`whatsapp_recipient_opted_out`](/errors/whatsapp_recipient_opted_out). Do not retry. - A **marketing** template needs a recorded opt-in. Without one the send fails with `409` [`whatsapp_opt_in_required`](/errors/whatsapp_opt_in_required). Send `optIn` with the message to record consent you collected, or use a utility or authentication template. - If the customer turned off promotional messages in WhatsApp, marketing templates fail with `409` [`whatsapp_marketing_opted_out`](/errors/whatsapp_marketing_opted_out). Utility and authentication templates still go through. ## Retry safely [#retry-safely] Send an `Idempotency-Key` header with every send. Create it once per message and reuse it on every retry of that message. CallMitra checks it in two ways: 1. **For 24 hours**, the standard [idempotency](/idempotency) rules apply. The same key with the same body returns the first response again, with the header `Idempotent-Replayed: true`. The same key with a different body fails with `409` [`idempotency_key_reused`](/errors/idempotency_key_reused). 2. **Permanently**, CallMitra also stores the key on the message itself, once per workspace. A retry after 24 hours, or while the idempotency store is unavailable, does not send again. It returns the message that was already sent, with its current `status`. If that retry names a different recipient (`to` or `contactId`), it fails with `409` [`idempotency_key_reused`](/errors/idempotency_key_reused). If it names the same customer but would go into a different conversation, for example from another of your numbers, it fails with `409` [`whatsapp_client_message_id_reused`](/errors/whatsapp_client_message_id_reused). In both cases nothing is sent; use a new key for each new message. There is no separate `clientMessageId` field in the request body. The `Idempotency-Key` header is the only way to make a send retry-safe. When WhatsApp certainly did not take the message (`429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) or `503` [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable)), the key is released. Wait for the seconds in `Retry-After` and retry with the same key: the retry really sends. ## Message status [#message-status] `status` moves forward as WhatsApp reports progress: | `status` | Meaning | | --- | --- | | `queued` | Created, not yet handed to WhatsApp. | | `accepted` | WhatsApp accepted the message. `wamid` is set. | | `sent` | WhatsApp sent it. | | `delivered` | It reached the customer's phone. | | `read` | The customer read it. | | `failed` | Final. WhatsApp refused it; `error` says why. | | `unknown` | WhatsApp did not answer clearly. A later status update settles it. | If WhatsApp refuses a message after CallMitra created it, the send still returns `200`, with `status: "failed"` and an `error` object holding WhatsApp's `code` and `message`. Check `status` on every `200`. Read the current status with the `id` from the send: ```bash curl https://api.callmitra.ai/api/v1/whatsapp/messages/7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10 \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const res = await fetch( `https://api.callmitra.ai/api/v1/whatsapp/messages/${messageId}`, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }, ); const { status, error } = await res.json(); ``` ```python res = requests.get( f"https://api.callmitra.ai/api/v1/whatsapp/messages/{message_id}", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30, ) status = res.json()["status"] ``` The response has the same shape as the send response. An unknown ID, or a message of another workspace, returns `404` [`resource_not_found`](/errors/resource_not_found). ## List templates [#list-templates] [`GET /api/v1/whatsapp/message-templates`](/api-reference/whatsapp/listWhatsAppTemplates) returns up to 500 templates, sorted by name and language. Deleted templates are left out. | Query parameter | Description | | --- | --- | | `phoneId` | Only templates usable from this sending number. | | `status` | Filter by review status, for example `APPROVED`. Case does not matter. | | `category` | `MARKETING`, `UTILITY` or `AUTHENTICATION`. | | `q` | Part of the template name. | ```bash curl "https://api.callmitra.ai/api/v1/whatsapp/message-templates?status=APPROVED&category=UTILITY" \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```json { "templates": [ { "id": "4a9e7c21-3b5d-4f1e-8c2a-9d6b0e1f2a34", "name": "order_update", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": null, "parameterFormat": "POSITIONAL", "components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped." } ], "lastSyncedAt": "2026-01-15T08:00:00+00:00" } ] } ``` Only `APPROVED` templates can be sent. Sending any other fails with `409` [`whatsapp_template_not_approved`](/errors/whatsapp_template_not_approved), and the message names the current status. A name and language pair that does not exist on the sending number's account fails with `404` [`whatsapp_template_not_found`](/errors/whatsapp_template_not_found). ## Receive messages [#receive-messages] When a customer writes to your number, CallMitra sends the [`whatsapp.message.received`](/api-reference/webhooks/onWhatsappMessageReceived) webhook event. It includes the contact (with its `id`, which you can send back as `contactId`), the conversation, the sending number's `phoneId` and the message. Set up an endpoint in [Webhooks](/webhooks/endpoints) and see all payloads in [Webhook events](/webhooks/events). ## Rate limit [#rate-limit] Sends are limited to **50 messages per second per workspace**. Above that, a send fails with `429` [`rate_limit_exceeded`](/errors/rate_limit_exceeded) and `Retry-After: 1`. The general API [rate limits](/rate-limits) apply too. WhatsApp's own limits on your number show up as `429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled). ## Errors [#errors] | Status | Code | When | | --- | --- | --- | | `404` | [`resource_not_found`](/errors/resource_not_found) | The `contactId` or message ID does not exist in your workspace. | | `404` | [`whatsapp_template_not_found`](/errors/whatsapp_template_not_found) | No template with that name and language on the sending number's account. | | `409` | [`whatsapp_number_not_connected`](/errors/whatsapp_number_not_connected) | No connected number, or `phoneId` is not one of your connected numbers. | | `409` | [`whatsapp_template_not_approved`](/errors/whatsapp_template_not_approved) | The template is not approved. | | `409` | [`whatsapp_opt_in_required`](/errors/whatsapp_opt_in_required) | Marketing template without a recorded opt-in. | | `409` | [`whatsapp_recipient_opted_out`](/errors/whatsapp_recipient_opted_out) | The recipient opted out. | | `409` | [`whatsapp_marketing_opted_out`](/errors/whatsapp_marketing_opted_out) | The recipient stopped marketing messages. | | `409` | [`whatsapp_window_closed`](/errors/whatsapp_window_closed) | Free-form message outside the 24-hour window. | | `409` | [`idempotency_key_reused`](/errors/idempotency_key_reused) | Same key, different body (within 24 hours) or different recipient. | | `409` | [`whatsapp_client_message_id_reused`](/errors/whatsapp_client_message_id_reused) | The key already belongs to a message in another conversation (same customer, another number). | | `409` | [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) | The first request with this key is still running. | | `422` | [`parameter_invalid`](/errors/parameter_invalid) | A field is missing or invalid: `to` not an international number, empty `text`, non-https `media.link`, missing template variable, bad `type`. | | `429` | [`rate_limit_exceeded`](/errors/rate_limit_exceeded) | More than 50 sends per second. | | `429` | [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) | WhatsApp is limiting your number. Nothing was delivered. | | `503` | [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable) | WhatsApp had a temporary problem. Nothing was delivered. | For `429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) and `503` [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable), `detail` holds the message record with `retryable: true`. Retry after `Retry-After` with the same `Idempotency-Key`. Every error uses the standard [error envelope](/errors). # Workspace and usage (/guides/workspace-usage) Two read-only endpoints tell your integration about the workspace it works in: - [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace): which workspace and which key a request runs as. - [`GET /api/v1/usage`](/api-reference/workspace/getUsage): calls, talk time, billed minutes, wallet charges, plan and balance for a period. Every API key can call both with `GET`, including read-only keys and keys limited to other resources ([Authentication](/authentication)). ## Check a key: GET /workspace [#check-a-key-get-workspace] Use it to: - **Verify a key** before real work, for example when a customer pastes a key into your app. A bad key answers `401` [`invalid_api_key`](/errors/invalid_api_key), an expired one `401` [`api_key_expired`](/errors/api_key_expired). - **Show the workspace name** next to the connection in your UI. - **Read the key's limits**: its access, the resources it can reach, its expiry and its rate limit. - **Confirm the agency context**: with `X-Workspace-Id`, an agency key sees the client workspace ([Agencies](/guides/agencies)). `GET /auth/me` is a console endpoint. API keys get `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden) there and everywhere under `/auth`. Call `GET /api/v1/workspace` instead. ```bash curl https://api.callmitra.ai/api/v1/workspace \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/workspace', { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }); if (res.status === 401) throw new Error('This API key is not valid'); const { workspace, apiKey } = await res.json(); console.log(`Connected to ${workspace.name} with ${apiKey.prefix}…`); ``` ```python import os import requests res = requests.get( "https://api.callmitra.ai/api/v1/workspace", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30, ) if res.status_code == 401: raise RuntimeError("This API key is not valid") body = res.json() print(f"Connected to {body['workspace']['name']} with {body['apiKey']['prefix']}…") ``` ```json title="200 OK" { "success": true, "workspace": { "id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01", "name": "Acme Realty", "parentId": null }, "apiKey": { "id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a", "prefix": "vk_live_Ab3dE6", "name": "CRM sync", "scopes": { "access": "read", "resources": ["calls", "leads"] }, "expiresAt": null }, "rateLimit": { "limit": 300, "windowSeconds": 60 } } ``` | Field | Meaning | | --- | --- | | `workspace.id`, `workspace.name` | The workspace the request runs in. | | `workspace.parentId` | The agency workspace this client workspace belongs to; `null` for a workspace that is not a client. | | `apiKey.id`, `apiKey.name` | The key that sent the request, and the name it was given. `apiKey` is `null` when the request was not made with an API key (a console session). | | `apiKey.prefix` | The first characters of the key, as shown in the console. The secret is never returned. | | `apiKey.scopes.access` | `full`, or `read` (read-only keys may only send `GET`). | | `apiKey.scopes.resources` | Resource groups the key may reach. An empty list means all of them. | | `apiKey.expiresAt` | When the key stops working; `null` if never. | | `rateLimit.limit` | Requests per minute allowed for this key; `0` means no limit. `windowSeconds` is the window length. See [Rate limits](/rate-limits). | ### Agency keys [#agency-keys] An agency key without `X-Workspace-Id` sees the agency workspace. With the header set to one of its client workspaces, `workspace` is the client and `workspace.parentId` is the agency. Use this to check that a client ID is valid before you start work in it: a workspace the key cannot act in answers `403` [`permission_denied`](/errors/permission_denied), never `404`. ```bash curl https://api.callmitra.ai/api/v1/workspace \ -H "X-API-Key: $AGENCY_API_KEY" \ -H "X-Workspace-Id: 3f2b6c1e-8a4d-4f7e-9b2a-1c5d7e9f0a12" ``` ## Read usage: GET /usage [#read-usage-get-usage] [`GET /api/v1/usage`](/api-reference/workspace/getUsage) reports one workspace: the one the request runs in (the client workspace when an agency key sends `X-Workspace-Id`). ### Choosing the period [#choosing-the-period] | Parameter | Format | Meaning | | --- | --- | --- | | `from` | ISO 8601 date or date-time | Start of the period, **inclusive**. A date-time without an offset is UTC. A bare date (`2026-11-01`) means 00:00 UTC that day. | | `to` | ISO 8601 date or date-time | End of the period, **exclusive**. A bare date includes that whole day (UTC). Default: now. | - Neither sent: the current billing period of your plan, from its start until now (`basis: "billing_period"`). Without a plan period, the last 30 days (`basis: "last_30_days"`). - Only `from`: from `from` until now. - Only `to`: the 30 days before `to`. - With either sent, `basis` is `custom`. - `from` must be before `to`, and the range can cover at most 366 days. Otherwise `422` [`parameter_invalid`](/errors/parameter_invalid). A value that is not an ISO 8601 date or date-time answers the same code. Bare dates use UTC midnight, not India Standard Time. For an IST calendar month, send date-times with an offset, for example `from=2026-11-01T00:00:00+05:30` and `to=2026-12-01T00:00:00+05:30`. In a raw URL, encode the `+` as `%2B`; the examples below do this for you. ```bash curl -G https://api.callmitra.ai/api/v1/usage \ -H "X-API-Key: $CALLMITRA_API_KEY" \ --data-urlencode "from=2026-11-01T00:00:00+05:30" \ --data-urlencode "to=2026-12-01T00:00:00+05:30" ``` ```js const url = new URL('https://api.callmitra.ai/api/v1/usage'); url.search = new URLSearchParams({ from: '2026-11-01T00:00:00+05:30', to: '2026-12-01T00:00:00+05:30', }); const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }); const usage = await res.json(); console.log(usage.calls.billedMinutes, 'minutes billed'); if (usage.balance) console.log('Balance: ₹', usage.balance.balanceInrPaise / 100); ``` ```python usage = requests.get( "https://api.callmitra.ai/api/v1/usage", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params={"from": "2026-11-01T00:00:00+05:30", "to": "2026-12-01T00:00:00+05:30"}, timeout=30, ).json() print(usage["calls"]["billedMinutes"], "minutes billed") if usage["balance"] is not None: print("Balance: ₹", usage["balance"]["balanceInrPaise"] / 100) ``` ```json title="200 OK" { "success": true, "period": { "start": "2026-11-01T00:00:00Z", "end": "2026-11-15T12:00:00Z", "basis": "billing_period" }, "calls": { "total": 412, "completed": 288, "durationSeconds": 21950.0, "billedMinutes": 402, "walletChargedInrPaise": 0 }, "plan": { "name": "Growth", "slug": "growth", "periodStart": "2026-11-01T00:00:00+00:00", "periodEnd": "2026-12-01T00:00:00+00:00", "minutesIncluded": 2000, "minutesUsed": 402, "minutesRemaining": 1598, "overageMinutes": 0, "overageAmountInrPaise": 0 }, "balance": { "balanceInrPaise": 150000, "ratePerMinuteInrPaise": 600, "minutesAtCurrentRate": 250 }, "billingEnabled": true } ``` ### Fields [#fields] Money is in **paise** (1 INR = 100 paise), as integers. Talk time is in seconds; billed amounts of time are in whole minutes. | Field | Meaning | | --- | --- | | `period.start`, `period.end` | The period used: start inclusive, end exclusive. | | `period.basis` | `billing_period`, `last_30_days` or `custom` (see above). | | `calls.total` | Calls created in the period, every status, test calls included. | | `calls.completed` | Calls that connected and ended normally. | | `calls.durationSeconds` | Talk time of completed calls, in seconds. | | `calls.billedMinutes` | Minutes charged for this workspace's calls in the period. | | `calls.walletChargedInrPaise` | Money taken from the wallet for calls in the period, in paise. | | `plan` | The **current** billing period of the workspace's plan, whatever period you asked for: `name`, `slug`, `periodStart`, `periodEnd`, `minutesIncluded`, `minutesUsed`, `minutesRemaining`, `overageMinutes`, `overageAmountInrPaise`. For a client workspace its agency pays for, this is the agency's shared plan. `null` without a plan. | | `balance.balanceInrPaise` | Wallet balance, in paise. | | `balance.ratePerMinuteInrPaise` | Price of a minute paid from the wallet, in paise. | | `balance.minutesAtCurrentRate` | Minutes the balance pays for at that rate; `null` when there is no rate. | | `billingEnabled` | Whether plan limits and wallet charges apply on this deployment. | ### When billing is off [#when-billing-is-off] When billing is not enabled on the deployment, `billingEnabled` is `false` and `balance` is `null`. The request still succeeds, and `period`, `calls` and `plan` are filled in as usual. Check for `null` before reading `balance`. ```json { "success": true, "period": { "start": "2026-10-16T12:00:00Z", "end": "2026-11-15T12:00:00Z", "basis": "last_30_days" }, "calls": { "total": 58, "completed": 41, "durationSeconds": 3120.0, "billedMinutes": 0, "walletChargedInrPaise": 0 }, "plan": null, "balance": null, "billingEnabled": false } ``` ## Related [#related] - [Authentication & API keys](/authentication) - [Agencies & client workspaces](/guides/agencies) - [Rate limits](/rate-limits) - [Place and read calls](/guides/direct-calls) # Idempotency (/idempotency) Networks fail. When a `POST` times out you cannot tell whether CallMitra received it, and retrying blindly could create a second campaign or place a second call. Send an `Idempotency-Key` header and the retry returns the first result instead of doing the work twice. ```bash curl -X POST https://api.callmitra.ai/api/v1/campaigns/create-with-leads \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Idempotency-Key: 6f1d2c4e-campaign-2026-11-15" \ -H "Content-Type: application/json" \ -d @campaign.json ``` ## Which endpoints support it [#which-endpoints-support-it] These `POST` endpoints accept `Idempotency-Key`. Their pages in the [API reference](/api-reference) list the header and the `Idempotent-Replayed` response header. On other endpoints the header is ignored. | Resource | Endpoints | | --- | --- | | Agents | [Create an agent](/api-reference/agents/createAgent), [import an agent](/api-reference/agents/importAgent) | | Calls | [Place a call](/api-reference/calls/createCall) | | Campaigns | [Create a campaign](/api-reference/campaigns/createCampaign), [create with leads](/api-reference/campaigns/createCampaignWithLeads) | | Leads | [Create a lead](/api-reference/leads/createLead), [bulk action](/api-reference/leads/bulkLeadAction), [add to do-not-call](/api-reference/do-not-call/addDoNotCall), [add a note](/api-reference/lead-notes/createLeadNote) | | Tickets | [Create a ticket](/api-reference/tickets/createTicket), [add a note](/api-reference/tickets/addTicketNote) | | WhatsApp | [Send a message](/api-reference/whatsapp/sendWhatsAppMessage) | | Webhooks | [Create an endpoint](/api-reference/webhooks/createWebhookEndpoint) | ## Rules [#rules] - **Key format:** any string of 1–255 characters. A UUID v4 per logical operation is a good choice. A longer or empty key is rejected with `400` [`bad_request`](/errors/bad_request) and `param: "Idempotency-Key"`. - **Scope:** a key is scoped to the credential that sent it, plus the HTTP method and the exact path. Two different API keys can use the same key value without colliding. Send the credential the same way on every retry: the same API key sent once as `X-API-Key` and once as `Authorization: Bearer` counts as two credentials. - **Agency keys:** the workspace in `X-Workspace-Id` is not part of the scope. When one agency key works in several client workspaces, include the client in the key (for example `client-42:campaign-2026-11-15`) so two clients never share a key ([Agencies](/guides/agencies)). - **Lifetime:** the result is kept for **24 hours**. After that the same key starts a new request. - **Same request, same key:** you get the stored status code and body again, with the header `Idempotent-Replayed: true`. Successes (`2xx`) and client errors (`4xx`) are stored, except `401`, `403`, `404` and `429`. "Same request" means the same method, path and byte-for-byte body; a replay returns the stored body and content type, not the other headers of the first response. - **Different body, same key:** `409` [`idempotency_key_reused`](/errors/idempotency_key_reused). Use a new key for a new operation. - **First request still running:** `409` [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) with `Retry-After: 1`. Wait and retry with the same key. The claim is held for as long as the first request runs; if it never finishes (for example the server restarted), the claim is released after 2 minutes. - **Server errors, rate limits and auth errors are not stored.** If the first attempt failed with a `5xx`, a `429`, a `401`, a `403` or a `404` (or the response was larger than 1 MB), the key is released and a retry runs the request again. - **Large request bodies:** a request body over 1 MB is processed without idempotency (the key is ignored). - **Responses that contain a secret are never stored.** [Create a webhook endpoint](/api-reference/webhooks/createWebhookEndpoint) returns its signing `secret` once. A concurrent duplicate still gets `409` [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress), but once the first request has succeeded, a retry with the same key gets `409` [`idempotency_key_reused`](/errors/idempotency_key_reused) instead of the secret. Nothing is created twice: list your endpoints and [rotate the secret](/api-reference/webhooks/rotateWebhookEndpointSecret) if you lost it. - **Best effort.** If CallMitra's idempotency store is briefly unavailable, the request runs normally without replay protection. [WhatsApp sends](/guides/whatsapp) also keep the `Idempotency-Key` on the message permanently, so a repeated key returns the message already sent, even after 24 hours. ## Retry pattern [#retry-pattern] Create the key once per operation, before the first attempt, and reuse it on every retry of that operation. ```js import { randomUUID } from 'node:crypto'; async function createCampaign(payload) { const idempotencyKey = randomUUID(); for (let attempt = 0; attempt < 5; attempt++) { try { const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/create-with-leads', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json', }, body: JSON.stringify(payload), }); const body = await res.json(); const inProgress = body.error?.code === 'idempotency_request_in_progress'; if (!inProgress && res.status !== 429 && res.status < 500) return body; } catch { // Network error or non-JSON reply: safe to retry with the same key. } await new Promise((r) => setTimeout(r, 2 ** attempt * 1000)); } throw new Error('Could not create the campaign'); } ``` ```python import os import time import uuid import requests def create_campaign(payload): idempotency_key = str(uuid.uuid4()) for attempt in range(5): try: res = requests.post( "https://api.callmitra.ai/api/v1/campaigns/create-with-leads", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": idempotency_key, }, json=payload, timeout=30, ) body = res.json() code = (body.get("error") or {}).get("code") if code != "idempotency_request_in_progress" and res.status_code != 429 and res.status_code < 500: return body except (requests.ConnectionError, requests.Timeout, ValueError): pass # Network error or non-JSON reply: safe to retry with the same key. time.sleep(2**attempt) raise RuntimeError("Could not create the campaign") ``` Only retry a `409` with the same key when its code is `idempotency_request_in_progress`. A `409 idempotency_key_reused` means your code sent a different body under an old key; fix the bug instead of retrying. ## If idempotency is unavailable [#if-idempotency-is-unavailable] If CallMitra's idempotency store is briefly unavailable, the request still runs normally, without replay protection. Design receivers of [webhooks](/webhooks) to tolerate duplicates as well. WhatsApp message sends (`POST /whatsapp/messages`) follow the same rules, and a key that already sent a message never sends a second one, even after 24 hours: the original message is returned instead. When WhatsApp is throttling or briefly unavailable the send answers `429` or `503` with `Retry-After` and nothing is delivered, so retrying with the same key sends the message. # Introduction (/) The CallMitra API lets your CRM, website or backend drive the same AI voice agents your team uses in the console. You send people to call, CallMitra's agents call them over Indian phone lines, and you get the transcript, summary and outcome of every call back as JSON. ## What you can build [#what-you-can-build] Create, configure, publish and test AI voice agents, or import them from another platform. Place one call, then read its status, transcript, summary, outcome and recording. Group leads with an agent and a caller ID, then dial them on a schedule. Create, update and search the people your agents call. Keep a do-not-call list. Send template and session messages from your connected WhatsApp Business number. Create and update support tickets, add notes and reply to customers. Receive signed events, such as `call.completed`, instead of polling. Move from Vapi, Retell, Bland, ElevenLabs or Bolna. The API covers the whole lifecycle: 1. **Agents** — the AI voice agents that make and answer calls. 2. **Leads** — the people to call, with their phone number and any fields your agent needs. 3. **Campaigns** — a list of leads, an AI agent and a caller ID, dialled inside a calling window. 4. **Calls** — every call placed, with its result: status, transcript, summary, outcome and recording. 5. **WhatsApp** — follow-up messages through your connected WhatsApp Business number. 6. **Tickets** — issues raised from calls for your team to resolve. 7. **Webhooks** — call results and other events pushed to your server as they happen. Each API key can be limited to the resources it needs ([scopes](/authentication#limit-what-a-key-can-do)). ## How calls reach your customers [#how-calls-reach-your-customers] Calls go out over phone carriers connected to your workspace: **Twilio**, **Plivo** and **Vobiz** numbers, or your own **SIP trunk**. You connect numbers in the console under **Phone numbers**; the API lists them so you can pick a caller ID. Agents speak Indian English, Hindi and other Indian languages, depending on how the agent is configured. ## Before you start [#before-you-start] - A CallMitra workspace, and a **manager** role in it (only managers can create API keys). - At least one connected phone number (set up in the console). You can create agents in the console or through the API. - A server to keep your API key on. Never put a key in a browser or a mobile app. ## Conventions at a glance [#conventions-at-a-glance] | | | | --- | --- | | Base URL | `https://api.callmitra.ai/api/v1` | | Auth | `X-API-Key: ` on every request ([Authentication](/authentication)) | | Format | JSON request and response bodies, camelCase field names | | IDs | UUID strings | | Time | ISO 8601 timestamps in UTC | | Phone numbers | E.164, for example `+919876543210` | | Errors | One envelope with a stable `error.code` ([Errors](/errors)) | | Versioning | Additive changes only inside v1 ([Versioning](/versioning)) | Make your first request and start a campaign in a few minutes. Every public endpoint, with request and response examples. ## Docs for AI tools [#docs-for-ai-tools] Every page is also available as plain Markdown: add `.md` to the URL (for example [/quickstart.md](/quickstart.md)). [/llms.txt](/llms.txt) lists all pages and [/llms-full.txt](/llms-full.txt) contains the whole site in one file, ready to paste into an AI assistant. # Import agents (/migrate/import-agents) [`POST /api/v1/agents/import`](/api-reference/agents/importAgent) turns an agent exported from another platform into a CallMitra agent. You send the source platform's JSON as it is. CallMitra maps what it can, replaces what is not available, and tells you about everything else in a list of `warnings`. The new agent is always a **draft**. Nothing takes calls until you review it, publish it and go live. ## Request [#request] | Field | Type | Required | Notes | | --- | --- | --- | --- | | `source` | `vapi`, `retell`, `bland`, `callmitra` | yes | The platform the JSON comes from. | | `config` | object | yes | The agent JSON exported from that platform, unchanged. | What to send in `config` for each source: | `source` | Send | | --- | --- | | `vapi` | The assistant object, as returned by Vapi's `GET /assistant/{id}`. | | `retell` | `{"agent": {...}, "llm": {...}}` with the Retell agent and its Retell LLM. You can also send the agent object with the LLM fields merged into it, or put the LLM under `retell_llm`. | | `bland` | The body of a Bland `POST /v1/calls` request, or a saved Bland agent config. | | `callmitra` | A [getAgent](/api-reference/agents/getAgent) response, its `agent` object, `{name, config}`, or a bare config. | There is no dry-run mode. Every successful request creates an agent. The endpoint accepts an `Idempotency-Key` header, so a retry does not create a second agent ([Idempotency](/idempotency)). The API key needs the **Agents** resource, with write access ([Authentication](/authentication)). ## Response [#response] ```json { "success": true, "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Riley", "status": "draft" }, "warnings": [ { "field": "language", "message": "Language 'en' is not available; using en-IN." }, { "field": "voice", "message": "Voice '11labs/burt' is not available; using sarvam voice 'shubh'." } ] } ``` - `agent` is the full agent, the same shape as [getAgent](/api-reference/agents/getAgent) (shortened above). The imported settings are in `config`. - `warnings` lists each value that was changed, replaced or not imported. Each item has the source `field` and a `message`. An empty list means everything mapped. ## How an import works [#how-an-import-works] **Map.** CallMitra reads the fields it knows for the source and writes them to CallMitra config keys. The tables below list them. **Pick a language.** An exact match wins (case does not matter). If there is none, CallMitra uses a language with the same base, preferring the India variant (for example `hi` becomes `hi-IN`). If nothing matches, it uses `en-IN` and adds a warning. **Pick a voice.** CallMitra looks for the same provider and voice ID that supports the language. Next it tries the same voice ID or name with any provider, and warns that it matched by name. If there is still no match, it uses the default voice for the language, or the first voice that supports it, and warns that the original voice is not available. **Fill the gaps.** If the source sets no speech-to-text provider, CallMitra picks the default for the language. An unsupported language model is replaced with `gpt-4o-mini`, with a warning. **Drop bad values.** Each value that would fail CallMitra's save checks (for example out of range) is removed, with a warning that starts `Not imported:`. The agent is created with the rest. **Report the rest.** Every non-empty source field that CallMitra does not read gets the warning `Not imported: there is no matching setting.` A vendor value never makes the import fail. Text-to-speech provider names are matched loosely: `11labs`, `elevenlabs` and `eleven_labs` all mean `elevenlabs`, and `google` means `gemini`. An unknown provider is ignored and the voice is searched across all providers. If the source has no name, the agent is called `Imported Vapi agent`, `Imported Retell agent`, `Imported Bland agent` or `Imported agent`. ## Field maps [#field-maps] CallMitra config keys are listed as they appear in `config`. See the [config reference](/guides/agents#config-reference) for their ranges. ### Vapi [#vapi] | Vapi field | CallMitra field | Notes | | --- | --- | --- | | `name` | agent name | | | `model.messages` (role `system`) | `template_payload.system_prompt` | All system messages are joined. Other messages are skipped, with a warning. | | `model.model` | `llm_model` | Must be a supported model, else `gpt-4o-mini` with a warning. | | `model.provider` | — | `custom-llm` is not supported. You get a warning and the default model. | | `model.temperature` | `temperature` | `0` to `2`. | | `model.maxTokens` | `max_tokens` | `1` to `32000`. | | `firstMessage` | `template_payload.greeting_message` | | | `firstMessageMode` | — | `assistant-waits-for-user` is not supported, with a warning. The agent speaks first. | | `voice.provider` + `voice.voiceId` | `tts` + `voice` | Resolved as described above. | | `voice.speed` | `tts_speed` | Clamped to `0.5`–`1.5`, with a warning if changed. | | `transcriber.provider` | `stt` | If CallMitra supports it. Otherwise a warning and the default. | | `transcriber.language` | `language` | Resolved as described above. | | `endCallMessage` | `template_payload.system_prompt` | Added to the end of the prompt as the closing line, with a warning. | | `maxDurationSeconds` | `call_time_limit_seconds` | `10` to `3600`. | | `backgroundSound` | `background_sound` | `off` turns it off. `office` and call-center sounds map to `office`. Any other value, such as a sound URL, also becomes `office`, with a warning. | | `recordingEnabled`, `artifactPlan.recordingEnabled` | `call_recording` | | Not imported, with a warning: `model.tools`, `model.toolIds`. Skipped without a warning: `id`, `orgId`, `createdAt`, `updatedAt`, `isServerUrlSecretSet`. ### Retell [#retell] | Retell field | CallMitra field | Notes | | --- | --- | --- | | `agent_name` | agent name | | | `llm.general_prompt` | `template_payload.system_prompt` | | | `llm.begin_message` | `template_payload.greeting_message` | If `null`, you get a warning to add a greeting. | | `llm.model` | `llm_model` | Must be a supported model, else `gpt-4o-mini` with a warning. | | `llm.model_temperature` | `temperature` | `0` to `2`. | | `voice_id` | `tts` + `voice` | A prefixed ID such as `11labs-Adrian` is split into provider `elevenlabs` and voice `adrian`. | | `voice_speed` | `tts_speed` | `0.5` to `1.5`. | | `volume` | `tts_volume` | `0.2` to `1.0`. | | `language` | `language` | Resolved as described above. | | `interruption_sensitivity` | `interruption_sensitivity` | Below `0.34` is `low`, below `0.67` is `medium`, otherwise `high`. | | `ambient_sound` | `background_sound` | `null` or `off` turns it off. `office` and call-center sounds map to `office`. Any other value also becomes `office`, with a warning. | | `max_call_duration_ms` | `call_time_limit_seconds` | Divided by 1,000. | Not imported, with a warning: `llm.general_tools`, `llm.states` (multi-state flows), and a `response_engine.type` other than `retell-llm`. Skipped without a warning: `agent_id`, `version`, `is_published`, `last_modification_timestamp`, `llm_id`, `voice_model`, `starting_state`. ### Bland [#bland] | Bland field | CallMitra field | Notes | | --- | --- | --- | | `name` | agent name | | | `task` or `prompt` | `template_payload.system_prompt` | If both are set and differ, `task` is used, with a warning. | | `first_sentence` | `template_payload.greeting_message` | | | `voice` | `tts` + `voice` | Bland sends no provider, so the voice is matched by ID or name. | | `language` | `language` | Resolved as described above. | | `model` | `llm_model` | Bland model tiers are not supported. You get `gpt-4o-mini` with a warning. | | `temperature` | `temperature` | `0` to `2`. | | `max_duration` | `call_time_limit_seconds` | Minutes, multiplied by 60. | | `record` | `call_recording` | | | `background_track` | `background_sound` | `null` or `none` turns it off. `office` and call-center sounds map to `office`. Any other value also becomes `office`, with a warning. | Skipped without a warning: `phone_number`, `from`, `agent_id`, `call_id`, `created_at`, `metadata`. ### CallMitra [#callmitra] Use `source: "callmitra"` to copy an agent between workspaces. The config is copied as it is, including inline tools and the post-call webhook URL, with two exceptions. An inline tool whose `tool_id` is not a tool in **your** workspace, or whose URL is not a public `http(s)` address, is dropped as a whole. A post-call webhook URL that is not public is dropped too. Each drop adds a `Not imported:` warning. The webhook signing secret is not copied, with a warning. Set it again with [setAgentPostCallWebhook](/api-reference/webhooks/setAgentPostCallWebhook). ## What never imports [#what-never-imports] - Tools and function definitions from Vapi, Retell or Bland. - Knowledge bases from other platforms. - Webhooks and server URLs from other platforms. - Multi-state flows (Retell `states`). - Phone numbers. - Custom LLM endpoints. - Webhook signing secrets. Rebuild these in CallMitra after the import. Inline tools go in `config.tools` ([Tools](/guides/agents#tools)). ## Errors [#errors] The import fails only when the request itself cannot be served: | Code | When | | --- | --- | | [`parameter_invalid`](/errors/parameter_invalid) | `source` is not one of the four values, or `config` is not an object or is nested more than 16 levels deep. Also when a value is refused and cannot be dropped. | | [`payload_too_large`](/errors/payload_too_large) | `config` (the source JSON) is larger than 512 KB. | | [`payment_required`](/errors/payment_required) | Your plan's agent limit is reached. | | [`permission_denied`](/errors/permission_denied) | The key cannot write agents. | | [`idempotency_key_reused`](/errors/idempotency_key_reused) | The `Idempotency-Key` was used before with a different body. | See [Errors](/errors) for the envelope. ## Example: import a Vapi assistant [#example-import-a-vapi-assistant] Fetch the assistant from Vapi, then send it as `config`: ```bash curl -X POST https://api.callmitra.ai/api/v1/agents/import \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: import-vapi-riley-001" \ -d '{ "source": "vapi", "config": { "name": "Riley", "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?", "model": { "provider": "openai", "model": "gpt-4o", "messages": [ { "role": "system", "content": "You qualify home-buyer leads." } ] }, "voice": { "provider": "11labs", "voiceId": "burt" }, "transcriber": { "provider": "deepgram", "language": "en" } } }' ``` ```js // The assistant JSON you fetched from Vapi's GET /assistant/{id}. const vapiAssistant = { name: 'Riley', firstMessage: 'Hi, this is Riley from Acme Realty. Is now a good time?', model: { provider: 'openai', model: 'gpt-4o', messages: [{ role: 'system', content: 'You qualify home-buyer leads.' }], }, voice: { provider: '11labs', voiceId: 'burt' }, transcriber: { provider: 'deepgram', language: 'en' }, }; const res = await fetch('https://api.callmitra.ai/api/v1/agents/import', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': 'import-vapi-riley-001', }, body: JSON.stringify({ source: 'vapi', config: vapiAssistant }), }); const { agent, warnings } = await res.json(); for (const w of warnings) console.log(`${w.field}: ${w.message}`); ``` ```python import os import requests # The assistant JSON you fetched from Vapi's GET /assistant/{id}. vapi_assistant = { "name": "Riley", "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?", "model": { "provider": "openai", "model": "gpt-4o", "messages": [{"role": "system", "content": "You qualify home-buyer leads."}], }, "voice": {"provider": "11labs", "voiceId": "burt"}, "transcriber": {"provider": "deepgram", "language": "en"}, } res = requests.post( "https://api.callmitra.ai/api/v1/agents/import", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "import-vapi-riley-001", }, json={"source": "vapi", "config": vapi_assistant}, timeout=30, ) body = res.json() for w in body["warnings"]: print(f"{w['field']}: {w['message']}") ``` The response creates the draft agent `Riley`. In this example the language `en` and the ElevenLabs voice `burt` are not available, so the warnings show the replacements: `en-IN` and a Sarvam voice. ## After importing [#after-importing] **Read the warnings.** Then read the agent with [getAgent](/api-reference/agents/getAgent) and check `config`. **Check the voice and language.** Pick a voice with [listVoices](/api-reference/agents/listVoices) and fix it with [`PATCH`](/api-reference/agents/updateAgent) if needed. **Add what did not import.** Greeting, tools, knowledge, and the [post-call webhook](/api-reference/webhooks/setAgentPostCallWebhook). **Assign a phone number** to the agent in the console. **Publish** with [publishAgent](/api-reference/agents/publishAgent). **Place a test call** with [testCallAgent](/api-reference/agents/testCallAgent). **Go live** with [startAgent](/api-reference/agents/startAgent). ## Related [#related] - [Build agents with the API](/guides/agents) - [Migrate to CallMitra](/migrate) - [Idempotency](/idempotency) - [Errors](/errors) # Migrate to CallMitra (/migrate) Most voice AI platforms are built from the same parts: an agent, a phone number, calls, batches of calls, tools, and a webhook at the end. This guide maps each part to CallMitra, then gives you one checklist that works whichever platform you are leaving. Names below come from each platform's public documentation at the time of writing. Check your platform's current docs for exact field names before you write mapping code. ## Concept map [#concept-map] | Concept | Vapi | Retell | Bland | ElevenLabs | Bolna | **CallMitra** | | --- | --- | --- | --- | --- | --- | --- | | Agent | Assistant (or Squad) | Agent + Retell LLM or conversation flow | Call `task` or Pathway | Agent | Agent | **Agent** | | System prompt | Model system message | `general_prompt` | `task` / pathway nodes | Agent prompt | Agent prompt | **Script** (goal, steps, end rules, closing) + **Knowledge** | | First message | `firstMessage` | `begin_message` | `first_sentence` | `first_message` | Welcome message | Script **opening** | | Phone number | Phone number (bought or imported) | Phone number (bought or imported via SIP) | Inbound number / BYOT | Phone number (Twilio or SIP trunk) | Phone number (Plivo, Twilio, Exotel) | **Phone number** on your own Plivo, Vobiz, Twilio or SIP trunk account | | One outbound call | `POST /call` | Create phone call | `POST /v1/calls` | Outbound call | Make call | [`POST /api/v1/calls/`](/api-reference/calls/createCall) | | Batch of calls | Outbound campaign | Batch call | Batch | Batch calling | Batch | **[Campaign](/guides/campaigns)** with leads, a calling window and retries | | Contact | `customer` | `to_number` + variables | `phone_number` + `request_data` | Batch recipient row | CSV row | **[Lead](/api-reference/leads/createLead)** with `attributes` and `externalId` | | Variables | `{{name}}`, `variableValues` | `{{name}}`, dynamic variables | `{{name}}`, `request_data` | `{{name}}`, dynamic variables | `{name}`, CSV columns | `{{name}}` filled from the lead, or `variables` on a direct call | | Tools | Tools (function, API request) | Custom functions | Custom tools, webhook nodes | Server tools, client tools, MCP | Custom functions | **Tools**: API request, MCP servers, built-ins | | Knowledge base | Files / knowledge base | Knowledge base | Knowledge base | Knowledge base (RAG) | Knowledge base | Agent **Knowledge** (facts, Q&A, rules, notes) | | Post-call analysis | Analysis plan (summary, structured data) | Post-call analysis | Summary / analysis | Evaluation + data collection | Extractions | **What to collect** fields + call analysis | | End-of-call webhook | Server URL, `end-of-call-report` | `call_ended` / `call_analyzed` | `webhook` per call | Post-call webhook | Agent webhook | [`call.completed`](/webhooks/events) | | Transfer | Transfer call tool | Transfer call | Transfer number | Transfer to number | Transfer call | Handoff rules + [`call.escalated`](/webhooks/events#callescalated) | | API auth | `Authorization: Bearer` | `Authorization: Bearer` | `authorization` header | `xi-api-key` | `Authorization: Bearer` | `X-API-Key` or `Authorization: Bearer vk_live_…` | ### What is different in CallMitra [#what-is-different-in-callmitra] - **No raw system prompt.** You write the agent's script (goal, steps, end rules, closing) and knowledge; CallMitra builds the full prompt around it, including language, tone, compliance lines and the built-in end-call tool. Paste your old prompt's instructions into the script steps and its facts into knowledge. - **Knowledge is text, not files.** There is no document upload or vector search. Knowledge items (facts, Q&A, rules, objections) and free-form notes go straight into the agent's prompt, up to 48,000 characters in total. Paste your FAQ and the key parts of your documents. - **Every call belongs to a lead.** A [direct call](/guides/direct-calls) finds or creates the lead for the number you call. Batches run as campaigns, which hold the caller IDs, calling window, retries and daily limit. Direct calls start at once with no calling window, so the hours are your responsibility. - **Calls wait for the calling window.** A campaign only starts automatic calls inside its window (10:00–17:00 Asia/Kolkata by default) and never dials numbers on your do-not-call list. See [Calling in India](/guides/india-calling). - **Your carrier, your numbers.** CallMitra does not sell numbers. See [Indian carriers](/guides/indian-carriers). ## Migration checklist [#migration-checklist] ### Create an API key [#create-an-api-key] In the console, open **Settings → Developers** and create a key. Give each integration its own key, limited to the resources it needs, or read-only for reporting jobs. Send it as `X-API-Key: vk_live_…` (or `Authorization: Bearer vk_live_…`, which is what most platforms use, so your HTTP client may need only a new base URL and key). See [Authentication](/authentication). If you run many client accounts, set them up as client workspaces under one agency and use one key with `X-Workspace-Id`. See [Agencies](/guides/agencies). ### Connect your phone numbers [#connect-your-phone-numbers] If your numbers live in your own Plivo, Twilio or Vobiz account, add them under **Calls → Phone numbers** with that account's credentials. Numbers bought inside another voice AI platform usually stay with it; ask that platform or your carrier about porting. Wait before clicking **Connect automatically** for inbound: it points the number at CallMitra, which moves inbound calls away from your old platform. Do it at cutover (step 7). Outbound calls work as soon as the number is added. See [Indian carriers](/guides/indian-carriers). ### Import or rebuild each agent [#import-or-rebuild-each-agent] From Vapi, Retell or Bland, start with [`POST /api/v1/agents/import`](/migrate/import-agents): send the platform's agent export JSON unchanged with its `source` (`vapi`, `retell`, `bland`, or `callmitra` to copy between workspaces). It always creates a **draft** agent and returns `warnings` for every value it changed or could not map; vendor values never make it fail. A language or voice CallMitra does not offer is replaced by a default, with a warning. Tools, knowledge bases, webhooks, multi-state flows, phone numbers and custom LLM endpoints never import. From any other platform, or to finish an import, create or edit the agent in the console's agent studio or with the [agents API](/guides/agents), and map your old settings: | Your old setting | Where it goes in the studio | | --- | --- | | First message / greeting | **Script → Opening** | | System prompt instructions | **Script**: goal, steps, end rules, closing | | FAQ, product facts, objection handling | **Knowledge**: facts, Q&A, rules, objections, notes | | Voice, language, speech-to-text, LLM | **Voice** and **Settings**. Eleven Indian languages are supported (`en-IN`, `hi-IN`, `bn-IN`, `ta-IN`, `te-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `gu-IN`, `pa-IN`, `od-IN`), with pipeline or speech-to-speech engines. | | Structured data / extraction schema | **What to collect**: each field has a key, label, description and type (text, number, email, phone, date, yes/no, pick one). Values arrive in `extractedFields`. | | Functions / tools | **Actions & tools** (next step) | | Transfer destination | Handoff rules: cold or warm transfer, one number, several in sequence, or all at once | | Max call duration | **Settings** (600 seconds by default, 10–3,600) | | Recording, AI disclosure | **Settings**: both on by default, with a spoken recording notice | Publish the agent, then call yourself with **Call my phone** or [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent). There is no per-agent voicemail message or answering-machine setting: voicemail is detected after the call and reported as the `voicemail` outcome. **Variables.** CallMitra variables are `{{lowercase_snake_case}}`, filled from the lead on every call: | Token | Value | | --- | --- | | `{{lead_name}}`, `{{lead_first_name}}`, `{{lead_last_name}}` | The lead's name | | `{{lead_phone}}`, `{{lead_email}}`, `{{lead_company}}` | The lead's contact details | | `{{company_name}}` | Your workspace's company name | | `{{agent_name}}` | The agent's spoken name | | `{{any_attribute}}` | Each key in the lead's `attributes`, lowercased with non-alphanumerics turned into `_` (`"Loan Amount"` becomes `{{loan_amount}}`) | Rename camelCase variables (`{{customerName}}` → `{{lead_name}}`, `{{loanAmount}}` → `{{loan_amount}}`) and convert Bolna's single-brace `{name}` to `{{name}}`. A variable with no value is dropped from spoken lines rather than read aloud. Agents can be created, edited, published and tested entirely through the API. See [Build agents with the API](/guides/agents). ### Recreate tools [#recreate-tools] In **Actions & tools**, add an **API request** tool for each function your agent calls: name, description, method, URL, headers, a body template, a JSON Schema for the parameters, and optional bearer or API-key auth (the secret is stored encrypted). The agent's arguments fill `{{param}}` placeholders in the URL, headers and body; for `GET` and `DELETE`, leftover arguments are sent as query parameters. Click **Test** before you attach it to an agent. Your endpoint can return any JSON or text; there is no `toolCallId` wrapper to produce. CallMitra waits up to 12 seconds, retries once on a `5xx` or timeout, and passes the first 4,000 characters of the response to the agent. MCP servers (streamable HTTP or SSE) can be added too; their tools are discovered and attached like any other. Built-in actions cover ending the call, transfer, scheduling a callback, WhatsApp messages and support tickets. ### Point your webhook receiver at CallMitra [#point-your-webhook-receiver-at-callmitra] Register your receiver once with [`POST /api/v1/webhook-endpoints/`](/api-reference/webhooks/createWebhookEndpoint) and pick the events it needs, for example `call.completed`, `call.failed` and `call.escalated` ([Webhook endpoints](/webhooks/endpoints)). Every subscribed event in the workspace goes to that endpoint, whichever campaign, agent or direct call it came from. The response holds the signing secret (`whsec_...`) once. Each event is a JSON envelope `{ id, type, apiVersion, createdAt, data }`. For call events, `data` holds the fields below: | CallMitra `data` field | Vapi `end-of-call-report` | Retell `call_analyzed` | Bland webhook | ElevenLabs post-call | Bolna execution | | --- | --- | --- | --- | --- | --- | | `type` (envelope) | `message.type` | `event` | — | `type` | `status` | | `callId` | `call.id` | `call.call_id` | `call_id` | `conversation_id` | `id` | | `agentId` | `assistant.id` | `call.agent_id` | `pathway_id` | `agent_id` | `agent_id` | | `customerNumber` | `customer.number` | `call.to_number` | `to` | from client data | `telephony_data.to_number` | | `status`, `endedReason` | `endedReason` | `call.call_status`, `disconnection_reason` | `status` | `status` | `status`, hangup reason | | `duration` (seconds) | from `startedAt` / `endedAt` | `duration_ms` ÷ 1000 | `call_length` (minutes) × 60 | `metadata.call_duration_secs` | `telephony_data.duration` | | `transcript` | `artifact.transcript` | `call.transcript` | `concatenated_transcript` | `transcript` (turns) | `transcript` | | `summary` | `analysis.summary` | `call_analysis.call_summary` | `summary` | `analysis.transcript_summary` | `summary` | | `extractedFields` | `analysis.structuredData` | `call_analysis.custom_analysis_data` | `analysis` | `analysis.data_collection_results` | `extracted_data` | | `sentiment` | — | `call_analysis.user_sentiment` | — | — | — | | `recordingUrl` | `artifact.recordingUrl` | `call.recording_url` | `recording_url` | — | `telephony_data.recording_url` | | `lead.externalId`, `lead.customFields` | `call.metadata`, variable values | `call.metadata`, dynamic variables | `variables`, `metadata` | dynamic variables | `context_details` | Four behaviours to adjust in your receiver: - **Signature.** CallMitra follows [Standard Webhooks](https://www.standardwebhooks.com/): verify `webhook-signature` against `webhook-id`, `webhook-timestamp` and the raw body, and refuse old timestamps. It replaces the header your old platform used. See [Verify signatures](/webhooks/verify-signatures). - **Duplicates.** The same event can arrive more than once. Store `webhook-id` (the same as the envelope `id`) and skip repeats. - **Failed calls.** A call that never connects (busy, no answer, carrier failure) sends `call.failed` together with `call.completed`. Subscribe to only one of them if you do not want both. - **Transfers** arrive as a separate [`call.escalated`](/webhooks/events) event; the call still sends `call.completed` when it ends. The recording URL needs your API key: download it with `X-API-Key` and store it yourself. Already using a campaign `crmWebhookUrl` or an agent post-call webhook? Those single-URL webhooks still work and run alongside endpoints. See [Campaign and agent webhooks](/webhooks/campaign-agent-webhooks). The workspace CRM webhook was retired on 2026-11-16; saved workspace URLs became webhook endpoints (see the [changelog](/changelog#2026-11-16)). ### Move contacts and run a pilot campaign [#move-contacts-and-run-a-pilot-campaign] 1. **Import your do-not-call list first** with [`POST /api/v1/leads/dnc`](/api-reference/do-not-call/addDoNotCall), so nobody who opted out on the old platform is called. 2. Map each CSV or batch row to a lead: `phone` (E.164, `+91…`), `name`, `email`, `company`, your own ID in `externalId`, and every other column in `attributes` (these become the agent's variables). 3. Create the campaign and its leads in one request with [`POST /api/v1/campaigns/create-with-leads`](/api-reference/campaigns/createCampaignWithLeads) (`leadSourceType: "bulk_upload"`, rows in `uploadedLeads`), including a calling window in `campaignData`. 4. Keep the pilot small: a few dozen leads and a low `maxCallsPerDay`. 5. [Start it](/api-reference/campaigns/startCampaign) and watch [`GET /campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus) to see why it is or is not dialing. See [Run a campaign](/guides/campaigns) for the full walkthrough. ### Cut over [#cut-over] 1. Compare the pilot's outcomes, transcripts and webhook data with your old platform. 2. Move outbound volume campaign by campaign. Stop retries for those leads on the old platform so nobody is called twice. 3. For inbound, click **Connect automatically** on each number (or update the addresses by hand for Vobiz and SIP trunks), then call the number to confirm the CallMitra agent answers. 4. Keep your old platform's webhook receiver running until its last retries have arrived. ## Error handling differences [#error-handling-differences] | | Many platforms | CallMitra | | --- | --- | --- | | Error body | A `message` or `error` string, shape varies by endpoint | Always the same [envelope](/errors): `detail` plus `error` with `type`, `code`, `message`, `param`, `docUrl` and `requestId` | | What to branch on | Status code and message text | `error.code` (stable, documented in the [catalogue](/errors#all-error-codes)), then `error.type` | | Invalid input | `400` | `422` with every problem listed and `param` naming the field | | Rate limits | Concurrency or plan limits, often undocumented headers | 300 requests per minute per key, with `RateLimit-*` headers and `Retry-After` on `429`. See [Rate limits](/rate-limits) | | Safe retries | Varies | `Idempotency-Key` header on create requests, kept 24 hours. See [Idempotency](/idempotency) | | Refused calls | Often dialed at once or failed | Calls outside the window are **deferred**, not failed; do-not-call numbers, daily limits and busy lines are refused with a readable message. See [Calling refusals](/errors#calling-refusals) | | Webhook delivery | Varies | Answer `2xx` within 10 seconds. Failures are retried up to 12 times with backoff; most `4xx` answers are not retried. See [Webhooks](/webhooks) | | Support | Varies | Quote the `requestId` from the error or the `X-Request-ID` header. See [Request IDs](/request-ids) | # Pagination (/pagination) List endpoints return results in pages. Each list uses one of four styles: - **Page number**: `page` and `limit`, with a `pagination` object. - **Cursor**: pass back the `nextCursor` you received. Leads and calls support both styles. - **Offset**: `limit` and `offset` (callbacks). - **One response**: small lists that return everything at once. ## Which list uses which style [#which-list-uses-which-style] | Endpoint | Style | `limit` default / max | Total count | Order | | --- | --- | --- | --- | --- | | [`GET /api/v1/leads/`](/api-reference/leads/listLeads) | Page or cursor | 25 / 200 | Capped at 10,000, exact with `includeTotal=true` | Newest first (`createdAt`, then `id`), or your `sortBy` | | [`GET /api/v1/calls/`](/api-reference/calls/listCalls) | Page or cursor | 25 / 200 | Capped at 10,000 | Newest first (`createdAt`, then `id`) | | [`GET /api/v1/campaigns/`](/api-reference/campaigns/listCampaigns) | Page | 25 / 200 | Exact | Newest first (`createdAt`, then `id`) | | [`GET /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/listCampaignLeads) | Page (optional) | 50 / 200 | Exact | Newest lead first, then `id` | | [`GET /api/v1/tickets/`](/api-reference/tickets/listTickets) | Page | 25 / 200 | Capped at 10,000 | Your sort, then `id` | | [`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) | Offset | 50 / 200 | Exact (`total`) | Soonest `dialAt` first | | [`GET /api/v1/leads/{lead_id}/timeline`](/api-reference/leads/getLeadTimeline) | Cursor | 30 / 100 | — | Newest first | | [`GET /api/v1/leads/{lead_id}/notes`](/api-reference/lead-notes/listLeadNotes) | Cursor | 30 / 50 | `notesCount` | Newest first, pinned notes on the first page | | [`GET /api/v1/webhook-deliveries/`](/api-reference/webhooks/listWebhookDeliveries) | Cursor | 25 / 100 | — | Newest first | | [`GET /api/v1/leads/dnc`](/api-reference/do-not-call/listDoNotCall) | One response, up to 500 | — | Entries returned | Most recently updated first | Agents, phone numbers, SIP trunks, tools, voices, the lead fields catalogue, ticket categories and teams, webhook endpoints and WhatsApp templates are returned in one response with no paging. ## Page-number lists [#page-number-lists] | Parameter | Default | Notes | | --- | --- | --- | | `page` | `1` | 1-based page number. | | `limit` | see table | Items per page. A larger value returns `422`. | The response carries the items and a `pagination` object: ```json { "success": true, "leads": [{ "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao" }], "pagination": { "currentPage": 1, "totalPages": 8, "totalItems": 187, "totalCapped": false, "itemsPerPage": 25, "hasNextPage": true, "hasPreviousPage": false, "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…" }, "hasMore": true, "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…" } ``` Keep requesting `page + 1` while `hasNextPage` (or the top-level `hasMore`) is `true`. ### Large counts: `totalCapped` and `includeTotal` [#large-counts-totalcapped-and-includetotal] Counting millions of rows is slow, so leads, calls and tickets stop counting at 10,000: - When more than 10,000 rows match, `totalItems` is `10000` and `totalCapped` is `true`. Show it as "10,000+". - `totalPages` is then based on 10,000, and `hasNextPage` stays `true` while pages come back full. Loop on `hasNextPage`, not on `totalPages`. - On leads, send `includeTotal=true` to get the exact count. It is slower on large workspaces. Campaigns and campaign leads always return an exact count. `GET /api/v1/campaigns/{campaign_id}/leads` returns `currentPage`, `totalItems`, `itemsPerPage`, `hasNextPage` and `hasPreviousPage` only, and returns every lead in one response when you omit `page`. ## Cursor lists [#cursor-lists] Pass the `nextCursor` from one response as `cursor` on the next request. You have reached the end when `hasMore` is `false` and `nextCursor` is `null`. ```json { "success": true, "items": [{ "id": "…", "type": "call" }], "hasMore": true, "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…" } ``` A cursor is an opaque string: do not parse it or build one yourself. An invalid cursor returns `422` [`parameter_invalid`](/errors/parameter_invalid). ### Leads and calls [#leads-and-calls] `GET /api/v1/leads/` and `GET /api/v1/calls/` accept `cursor` (up to 200 characters) as well as `page`: - An empty `cursor` asks for the first page in cursor mode. - In cursor mode the count is skipped, so it stays fast however deep you go. `pagination` holds only `itemsPerPage`, `hasNextPage` and `nextCursor`. - On leads, `cursor` works only with the default sort (newest first). With another `sortBy` you get `422` `parameter_invalid`; use `page` instead. - A page-number request on the default sort also returns `nextCursor`, so you can switch to cursor mode after the first page. Prefer the cursor for full exports. Rows created while you read do not shift later pages. ```js async function* allLeads() { let cursor = ''; while (true) { const url = new URL('https://api.callmitra.ai/api/v1/leads/'); url.searchParams.set('limit', '200'); url.searchParams.set('cursor', cursor); const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } }); const body = await res.json(); yield* body.leads; if (!body.hasMore || !body.nextCursor) return; cursor = body.nextCursor; } } ``` ```python import os, requests def all_leads(): cursor = "" while True: res = requests.get( "https://api.callmitra.ai/api/v1/leads/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params={"limit": 200, "cursor": cursor}, timeout=30, ) body = res.json() yield from body["leads"] if not body.get("hasMore") or not body.get("nextCursor"): return cursor = body["nextCursor"] ``` ### Ticket activity [#ticket-activity] [`GET /api/v1/tickets/{ticket_id}/activities`](/api-reference/tickets/listTicketActivities) pages backwards: pass the `activitiesCursor` you received as `before` to load older activity, while `hasOlderActivities` is `true`. `limit` defaults to 50, up to 200. ## Offset lists [#offset-lists] [`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) takes `limit` (default `50`, 1 to 200) and `offset` (default `0`) and returns `{ "callbacks": [...], "total": 12 }`. Add `limit` to `offset` until `offset` reaches `total`. Callbacks with the same `dialAt` have no fixed order between them, so a callback can move across a page boundary; filter by `dateFrom` and `dateTo` for exact windows. ## Capped lists [#capped-lists] [`GET /api/v1/leads/dnc`](/api-reference/do-not-call/listDoNotCall) returns up to 500 entries, most recently updated first. `total` is the number of entries in the response, and `hasMore` is `true` when your list holds more than 500. ## Tips [#tips] - Collection paths end with a slash (`/api/v1/leads/`). Without it the API answers with a redirect to the slash form. - Filters (`search`, `status`, `campaignId`, …) apply before pagination, so `totalItems` counts the filtered set. - Every list except callbacks ends its order on `id`, so rows with the same timestamp keep a fixed order and page boundaries do not overlap. - For a full export, use the largest `limit` and stay within your [rate limit](/rate-limits). # Quickstart (/quickstart) This guide takes you from no key to a running campaign. You need a manager role in a CallMitra workspace with at least one agent and one connected phone number. ### Create an API key [#create-an-api-key] 1. Sign in to the console and open **Settings → Developers**. 2. Choose **Create key**, give it a name (for example `crm-sync`), and pick its access and expiry. See [Authentication](/authentication) for what each option does. 3. Copy the key. It starts with `vk_live_` and is shown **only once**. Store it as a secret on your server, for example in an environment variable: ```bash export CALLMITRA_API_KEY="vk_live_..." ``` Never put an API key in a browser, mobile app or public repository. Anyone with the key can act on your workspace. ### Make your first request [#make-your-first-request] List your agents. Every request sends the key in the `X-API-Key` header. ```bash curl https://api.callmitra.ai/api/v1/agents/ \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/agents/', { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }); const { agents } = await res.json(); console.log(agents.map((agent) => [agent.id, agent.name])); ``` ```python import os import requests res = requests.get( "https://api.callmitra.ai/api/v1/agents/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, timeout=30, ) res.raise_for_status() for agent in res.json()["agents"]: print(agent["id"], agent["name"]) ``` A `200` response lists your agents. Note the `id` of the agent that should make the calls. Collection paths end with a slash (`/agents/`); without it the API answers with a `307` redirect. If you get `401`, check the key and the header name. Every error has the same [envelope](/errors) with a stable `error.code`. ### Pick a caller ID [#pick-a-caller-id] List the phone numbers connected to your workspace and note the `id` of the number to call from: ```bash curl https://api.callmitra.ai/api/v1/phone-numbers/ \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ### Create a campaign with leads [#create-a-campaign-with-leads] Create the campaign and its leads in one request. `campaignData.name` and `campaignData.agentId` are required. Phone numbers are E.164 (`+91…`). ```bash curl -X POST https://api.callmitra.ai/api/v1/campaigns/create-with-leads \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "campaignData": { "name": "Demo follow-up", "agentId": "AGENT_ID", "phoneNumberId": "PHONE_NUMBER_ID" }, "leadSourceType": "bulk_upload", "uploadedLeads": [ { "name": "Asha Rao", "phone": "+919876543210", "attributes": { "city": "Pune" } } ] }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/create-with-leads', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ campaignData: { name: 'Demo follow-up', agentId: 'AGENT_ID', phoneNumberId: 'PHONE_NUMBER_ID', }, leadSourceType: 'bulk_upload', uploadedLeads: [{ name: 'Asha Rao', phone: '+919876543210', attributes: { city: 'Pune' } }], }), }); const { campaignId, processedLeads } = await res.json(); ``` ```python res = requests.post( "https://api.callmitra.ai/api/v1/campaigns/create-with-leads", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, json={ "campaignData": { "name": "Demo follow-up", "agentId": "AGENT_ID", "phoneNumberId": "PHONE_NUMBER_ID", }, "leadSourceType": "bulk_upload", "uploadedLeads": [ {"name": "Asha Rao", "phone": "+919876543210", "attributes": {"city": "Pune"}} ], }, timeout=30, ) res.raise_for_status() campaign_id = res.json()["campaignId"] ``` The response contains `campaignId` and `processedLeads`. `attributes` are extra fields your agent can use in the conversation. ### Start the campaign [#start-the-campaign] ```bash curl -X POST https://api.callmitra.ai/api/v1/campaigns/CAMPAIGN_ID/start \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` Calls are placed inside the campaign's calling window, so the first call may not start immediately. Check progress with [`GET /api/v1/campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus), or list results with `GET /api/v1/calls/?campaignId=CAMPAIGN_ID`. ### Receive the result [#receive-the-result] Instead of polling, register a webhook endpoint once, in the console under **Settings → Developers → Webhooks** or with the API. CallMitra then sends a signed `call.completed` event after every call, with the status, transcript, summary and outcome: ```bash curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/callmitra", "events": ["call.completed", "call.failed"] }' ``` The response (or the console) shows the signing `secret` (`whsec_...`) only once. Store it on your server. A minimal receiver checks the [Standard Webhooks](https://www.standardwebhooks.com/) signature over the raw body: ```js import crypto from 'node:crypto'; import express from 'express'; const app = express(); const key = Buffer.from(process.env.CALLMITRA_WEBHOOK_SECRET.split('_')[1], 'base64'); app.post('/webhooks/callmitra', express.raw({ type: 'application/json' }), (req, res) => { const id = req.get('webhook-id'); const timestamp = req.get('webhook-timestamp'); if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401); const expected = crypto .createHmac('sha256', key) .update(`${id}.${timestamp}.${req.body.toString('utf8')}`) .digest('base64'); const valid = (req.get('webhook-signature') ?? '') .split(' ') .some((sig) => { const value = sig.split(',')[1] ?? ''; return value.length === expected.length && crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected)); }); if (!valid) return res.sendStatus(401); const event = JSON.parse(req.body.toString('utf8')); console.log(event.type, event.data.callId, event.data.merchantOutcome, event.data.summary); res.sendStatus(204); // answer 2xx within 10 seconds, then do slow work }); app.listen(3000); ``` See [Verify signatures](/webhooks/verify-signatures) for Python, PHP and Go, and [Webhooks](/webhooks) for retries, de-duplication and every event. ## Next steps [#next-steps] Handle failures by `error.code`. Stay inside 300 requests per minute per key. Lead sources, calling windows, pausing and stopping. Every endpoint with examples. # Rate limits (/rate-limits) Each API key has its own budget of **300 requests per minute**. The budget is a fixed 60-second window: when it runs out, requests answer `429` until the window resets. Keys do not share a budget with each other or with your team's console sessions (the console has its own budget of 120 requests per minute per workspace), so a busy integration cannot slow down people working in the console, and one integration cannot starve another. ## Which requests count [#which-requests-count] - Every authenticated request made with the key counts once, including requests that end in a `4xx` error. - A request refused before the key is accepted (no key, unknown, expired, or an endpoint no key may call) does not count against any budget. - An agency key acting in client workspaces with `X-Workspace-Id` uses **one** budget across all of them ([Agencies](/guides/agencies)). - Lead intake webhooks authenticated with an integration key (not an API key) have their own limits and do not use this budget. Need a higher limit for a production integration? Contact support with your expected volume. ## Response headers [#response-headers] Every response to an API-key request, successful or not, carries the current state of the key's budget: | Header | Meaning | | --- | --- | | `RateLimit-Limit` | Requests allowed in the current window (for example `300`). | | `RateLimit-Remaining` | Requests left in the current window. | | `RateLimit-Reset` | Seconds until the window resets. | | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | The same values under the older names, for clients that expect them. | | `Retry-After` | On `429` only: seconds to wait before retrying. | ```http HTTP/1.1 429 Too Many Requests RateLimit-Limit: 300 RateLimit-Remaining: 0 RateLimit-Reset: 17 Retry-After: 17 Content-Type: application/json { "detail": "Too many requests", "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` ## Handling 429 [#handling-429] 1. Stop sending requests with that key. 2. Wait for `Retry-After` seconds. 3. Retry with exponential backoff and jitter if it happens again. ```js async function callWithRetry(url, init, attempts = 5) { for (let attempt = 0; attempt < attempts; attempt++) { const res = await fetch(url, init); if (res.status !== 429 && res.status < 500) return res; const retryAfter = Number(res.headers.get('Retry-After')); const backoff = Math.min(30, 2 ** attempt) + Math.random(); await new Promise((r) => setTimeout(r, (retryAfter || backoff) * 1000)); } throw new Error('CallMitra API still failing after retries'); } ``` ```python import random import time import requests def call_with_retry(method, url, attempts=5, **kwargs): for attempt in range(attempts): res = requests.request(method, url, timeout=30, **kwargs) if res.status_code != 429 and res.status_code < 500: return res retry_after = float(res.headers.get("Retry-After") or 0) time.sleep(retry_after or min(30, 2**attempt) + random.random()) raise RuntimeError("CallMitra API still failing after retries") ``` Only retry `POST` requests that are safe to repeat; see [Idempotency](/idempotency). ## Stay under the limit [#stay-under-the-limit] - Use bulk endpoints for big jobs: [create a campaign with its leads](/api-reference/campaigns/createCampaignWithLeads) in one request, or [act on many leads](/api-reference/leads/bulkLeadAction) at once. - Use [webhooks](/webhooks) for call results instead of polling. - Ask for larger pages (`limit` up to 200 on most lists) rather than many small ones. - Watch `RateLimit-Remaining` and slow down before it reaches zero. ## Other limits [#other-limits] Calling has its own limits, separate from the request budget: - **A campaign's daily call limit** (`maxCallsPerDay`, default 50 per campaign per day in the campaign's timezone). When auto-dial reaches it, the campaign waits for the next day. Asking for a manual call on that campaign once it is reached answers `429` [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached). Waiting a few seconds will not help; the limit resets at local midnight. - **Concurrent calls:** per campaign (`maxConcurrentCalls`), per phone number, and per carrier account. A call that would exceed one answers `409` (for example [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) or [`carrier_capacity_reached`](/errors/carrier_capacity_reached)). Your plan's limit on simultaneous calls answers `429` [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached). See [Calling refusals](/errors#calling-refusals). - **WhatsApp sends:** up to 50 messages per second per workspace. Above that, [`POST /whatsapp/messages`](/api-reference/whatsapp/sendWhatsAppMessage) answers `429` `rate_limit_exceeded` with `Retry-After: 1`. - **Placing calls with `POST /calls`:** a fixed number of calls per workspace per UTC day (2,000 by default). Above it, [`createCall`](/api-reference/calls/createCall) answers `429` [`daily_call_limit_reached`](/errors/daily_call_limit_reached), with `Retry-After` counting down to 00:00 UTC. - **Webhook test events and redeliveries:** 10 per endpoint per minute, shared between [sendTestWebhook](/api-reference/webhooks/sendTestWebhook) and [redeliverWebhook](/api-reference/webhooks/redeliverWebhook). Above it you get `429` `rate_limit_exceeded` with `Retry-After`. Check `error.code` to tell a request-budget `429` (`rate_limit_exceeded`) from a calling `429`. The codes each endpoint can return are listed in the [API reference](/api-reference). # Request IDs (/request-ids) Every response from the API carries an `X-Request-ID` header. Errors repeat it in the body as `error.requestId`. It identifies one request end to end in CallMitra's logs, so it is the fastest way for support to find what happened. ```http HTTP/1.1 404 Not Found X-Request-ID: req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69 Content-Type: application/json { "detail": "Campaign not found", "error": { "type": "not_found_error", "code": "resource_not_found", "message": "Campaign not found", "param": null, "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69" } } ``` ## Send your own [#send-your-own] To correlate CallMitra's logs with yours, send your own ID in the `X-Request-ID` request header. CallMitra uses it as-is when it is 1–64 characters of letters, digits, `.`, `_` or `-`; otherwise it generates a new `req_…` ID. Either way, the ID in use is echoed back in the response. ```bash curl -i https://api.callmitra.ai/api/v1/campaigns/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "X-Request-ID: crm-sync-2026-11-15-0042" ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/', { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'X-Request-ID': 'crm-sync-2026-11-15-0042', }, }); console.log(res.status, res.headers.get('X-Request-ID')); ``` ```python res = requests.get( "https://api.callmitra.ai/api/v1/campaigns/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "X-Request-ID": "crm-sync-2026-11-15-0042", }, timeout=30, ) print(res.status_code, res.headers["X-Request-ID"]) ``` ## Good practice [#good-practice] - Log the `X-Request-ID` of every failed request next to your own error. - Do not reuse one ID for many requests; it makes logs harder to read. To retry safely, use an [`Idempotency-Key`](/idempotency) instead. - When you contact support, include the request ID, the time, and the endpoint. # Versioning (/versioning) The API version is part of the path: every endpoint lives under `/api/v1`. Within v1 we only make **additive** changes, following [Google AIP-180](https://google.aip.dev/180). Code you write against v1 today keeps working. ## Changes we may make inside v1 [#changes-we-may-make-inside-v1] These are not breaking, so build your client to accept them: - New endpoints and new optional request parameters or body fields. - New fields in response bodies and webhook payloads. - New values in enums that are documented as open (for example call outcomes or `endedReason`). - New error codes, always within the existing [error types](/errors). - New webhook event types (you only receive events you subscribe to). - New response headers. Ignore JSON fields you do not recognise, handle unknown enum values with a sensible default, and switch on `error.type` before `error.code`. ## Changes we never make inside v1 [#changes-we-never-make-inside-v1] - Removing or renaming a field, parameter or endpoint. - Changing a field's type or meaning. - Making an optional field required, or tightening validation on existing input. - Changing the status code an endpoint returns for a given outcome. A change like that would ship as a new major version (`/api/v2`), with v1 kept running alongside it. ## Pre-GA changes (2026-11-15) [#pre-ga-changes-2026-11-15] Before the public API reached general availability, one release on **2026-11-15** made breaking changes inside v1. Examples: new dedicated error codes with corrected status codes, the WhatsApp API moving to `/api/v1/whatsapp`, and API keys losing access to `/auth/*`. The [changelog](/changelog) lists every change and what to update. The rules above apply to every release after that one. ## `/platform/v1` [#platformv1] `/platform/v1` is not part of the public API. API keys are refused there with `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden). Use `/api/v1`. ## Deprecation [#deprecation] If we ever retire an endpoint or the alias, we will: 1. Announce it on this site, on the affected reference pages. 2. Add the `Deprecation: true` and [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) `Sunset: ` response headers to the affected endpoints. 3. Keep it working for **12 months** after the `Sunset` header first appears. No endpoint is deprecated today, so no response carries these headers yet. Logging any `Sunset` header you receive is a cheap way to get early warning. # Campaign and agent webhooks (/webhooks/campaign-agent-webhooks) A campaign or an agent can have its own webhook URL. CallMitra sends that call's results there as flat JSON signed with `X-Signature-SHA256`. These URLs send fewer events than [webhook endpoints](/webhooks/endpoints), have no delivery log, and use a simpler signature. Use webhook endpoints for new integrations, and see [Move to webhook endpoints](#move-to-webhook-endpoints) to switch. The workspace CRM webhook (`/api/v1/merchant/crm-webhook`) was retired on 2026-11-16. Saved workspace URLs were moved to webhook endpoints with a new secret. See the [changelog](/changelog). Campaign and agent URLs and webhook endpoints are independent. If a call has a campaign or agent URL **and** you have an endpoint subscribed to `call.completed`, both get a copy. ## The two URLs [#the-two-urls] | URL | Where you set it | Signing secret | | --- | --- | --- | | **Campaign webhook** | `crmWebhookUrl` and `crmWebhookSecret` on [`POST /api/v1/campaigns/`](/api-reference/campaigns/createCampaign), [`PUT /api/v1/campaigns/{campaign_id}`](/api-reference/campaigns/updateCampaign), or inside `campaignData` on [`POST /api/v1/campaigns/create-with-leads`](/api-reference/campaigns/createCampaignWithLeads) | The campaign's `crmWebhookSecret` | | **Agent post-call webhook** | [`PUT /api/v1/agents/{agent_id}/post-call-webhook`](/api-reference/webhooks/setAgentPostCallWebhook) | The agent's webhook `secret` | Campaign and agent URLs can be `http://` or `https://`, but they must point to a public internet address. The secret is optional. Without one, deliveries have no `X-Signature-SHA256` header. ### Agent post-call webhook [#agent-post-call-webhook] ```bash curl -X PUT https://api.callmitra.ai/api/v1/agents/3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10/post-call-webhook \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/hooks/calls", "secret": "a-long-random-secret", "trigger": "completed"}' ``` | Field | Description | | --- | --- | | `url` | Where to send call results. Send `""` to turn the webhook off. A URL that is not a public internet address is refused with [`agent_state_blocked`](/errors/agent_state_blocked). | | `secret` | Signing secret. Leave it out to keep the current one. It is never returned; the response has `hasSecret`. | | `trigger` | Which calls are sent: `every` (default), `completed` (the call connected: status `completed`, or an outcome other than `no_answer`, `busy` or `call_failed`), or `voicemail` (outcome `voicemail`). | The change applies to the live agent at once. `trigger` only applies when this agent webhook is the URL chosen for the call (see below). ## Which URL a call uses [#which-url-a-call-uses] For `call.completed` and `call.escalated`, CallMitra picks **one** URL per call. The first match wins: 1. The call's **campaign** webhook. 2. The call's **agent** post-call webhook. Its `trigger` can skip the call. If neither is set, the call is sent only to your webhook endpoints. ## Which events go where [#which-events-go-where] | Event | Campaign or agent URL | | --- | --- | | `call.completed` | The URL picked above. | | `call.escalated` | The URL picked above. The agent's `trigger` is not applied. | | `transfer.failed`, `callback.scheduled`, `callback.completed`, `callback.failed` | The campaign webhook, else the agent webhook. Only while **CRM webhook** alerts are on in **Settings → Notifications** for that event. They are on by default. | | `call.failed`, `ticket.*`, `lead.*`, `campaign.*`, `whatsapp.message.received` | Not sent. Use a webhook endpoint. | ## Delivery format [#delivery-format] ```http POST /hooks/call-results HTTP/1.1 Content-Type: application/json X-Webhook-Id: 3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b:call.completed X-Webhook-Event: call.completed X-Signature-SHA256: 5d41402abc4b2a76b9719d911017c592ae0e5f3e8c2a1b9f0d7e6c5b4a392817 ``` | Header | Meaning | | --- | --- | | `X-Webhook-Id` | Stays the same across retries. For `call.completed` and `call.escalated` it is `{callId}:{event}`. For other events it is a job UUID. Use it to drop duplicates. | | `X-Webhook-Event` | The event type. | | `X-Signature-SHA256` | Hex HMAC-SHA256 of the raw body, keyed with the secret. Only when a secret is set. | The body is flat JSON. It has the same fields as the event's `data` in [Event types](/webhooks/events), plus two more: - `event`: the event type, for example `call.completed`. - `timestamp`: when this attempt was sent, in Unix seconds. It changes on every retry. The JSON is compact, with keys sorted alphabetically and non-ASCII characters escaped (`\u0928`). A `call.completed` body, shown here with line breaks: ```json title="call.completed (campaign or agent URL)" { "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "callAnalysis": { "summary": "…" }, "callId": "3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b", "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "crmPayload": { "callAnalysis": { "summary": "…" } }, "customerNumber": "+919876543210", "direction": "outbound", "duration": 94, "endTime": "2026-11-15T05:31:46+00:00", "endedReason": "customer-ended-call", "event": "call.completed", "extractedFields": { "preferredCallbackDay": "Monday" }, "lead": { "company": "", "customFields": { "plan": "Gold" }, "email": "", "externalId": "crm-1042", "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao", "phone": "+919876543210" }, "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "merchantOutcome": "callback", "outcome": "callback_requested", "outcomeCategory": "positive", "phone": "+919876543210", "providerCallId": "CA1234567890abcdef", "recommendedLeadStatus": "follow_up", "recordingUrl": "https://api.callmitra.ai/api/v1/calls/3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b/recording", "sentiment": "positive", "startTime": "2026-11-15T05:30:12+00:00", "status": "completed", "summary": "Customer wants to renew the Gold plan and asked for a callback on Monday.", "timestamp": 1763184710, "transcript": "Agent: Namaste Asha ji…" } ``` ## Retries and pausing [#retries-and-pausing] These deliveries use the same rules as endpoints: answer `2xx` within **10 seconds**. `408`, `409`, `425`, `429`, `5xx`, timeouts and connection errors are retried up to **12 attempts**, starting at 30 seconds and doubling. Other `4xx` answers are not retried. Unlike endpoints, a delivery still not sent **24 hours** after it was queued expires. If **20 call events in a row** to the same URL are rejected for good (a non-retryable `4xx`, or all attempts used), CallMitra **pauses** that URL. Rejected `callback.*` events do not count. While a URL is paused, new events for it are skipped. You get a "CRM webhook paused" notification in the console, and by email or WhatsApp if those alerts are on. To resume, fix your receiver, open **Settings → Developers → Webhooks** in the console, and send a test from the **Campaign and agent webhooks** card. The test re-sends the newest finished call that used the URL, with its real `X-Webhook-Id`. If your server accepts it, the URL resumes. There is no delivery log or redelivery for campaign and agent URLs. ## Verify X-Signature-SHA256 [#verify-x-signature-sha256] `X-Signature-SHA256` is the lowercase hex HMAC-SHA256 of the raw body bytes, keyed with the secret as UTF-8 text. 1. Read the **raw body bytes** exactly as received. Do not parse and re-serialize the JSON first. 2. Compute `HMAC-SHA256(secret, rawBody)` and hex-encode it. 3. Compare it with `X-Signature-SHA256` using a **constant-time** comparison. Reject the request with `401` if they differ. 4. Parse the JSON and reject it if `timestamp` is more than **5 minutes** old. This stops someone replaying a captured request later. 5. Skip the event if you already handled its `X-Webhook-Id`. ```js import crypto from 'node:crypto'; import express from 'express'; const app = express(); const secret = process.env.CALLMITRA_WEBHOOK_SECRET; app.post('/hooks/call-results', express.raw({ type: 'application/json' }), (req, res) => { const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex'); const received = req.get('X-Signature-SHA256') ?? ''; const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); if (!valid) return res.sendStatus(401); const event = JSON.parse(req.body.toString('utf8')); if (!Number.isInteger(event.timestamp) || Math.abs(Date.now() / 1000 - event.timestamp) > 300) { return res.sendStatus(401); } // Look up req.get('X-Webhook-Id') in your store and skip duplicates, then queue the work. res.sendStatus(204); }); ``` ```python import hashlib import hmac import json import os import time from flask import Flask, abort, request app = Flask(__name__) SECRET = os.environ["CALLMITRA_WEBHOOK_SECRET"].encode() @app.post("/hooks/call-results") def callmitra_webhook(): raw = request.get_data() # raw bytes, before any JSON parsing expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest() received = request.headers.get("X-Signature-SHA256", "") if not hmac.compare_digest(expected, received): abort(401) event = json.loads(raw) if abs(time.time() - event["timestamp"]) > 300: abort(401) # Skip duplicates by request.headers["X-Webhook-Id"], then queue the work. return "", 204 ``` ```php 300) { http_response_code(401); exit; } // Skip duplicates by $_SERVER['HTTP_X_WEBHOOK_ID'], then queue the work. http_response_code(204); ``` ```go package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "encoding/json" "io" "net/http" "os" "time" ) var secret = []byte(os.Getenv("CALLMITRA_WEBHOOK_SECRET")) func callmitraWebhook(w http.ResponseWriter, r *http.Request) { raw, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "bad body", http.StatusBadRequest) return } mac := hmac.New(sha256.New, secret) mac.Write(raw) expected := hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Signature-SHA256"))) { w.WriteHeader(http.StatusUnauthorized) return } var event struct { Event string `json:"event"` Timestamp int64 `json:"timestamp"` } if json.Unmarshal(raw, &event) != nil { w.WriteHeader(http.StatusBadRequest) return } if d := time.Now().Unix() - event.Timestamp; d > 300 || d < -300 { w.WriteHeader(http.StatusUnauthorized) return } // Skip duplicates by r.Header.Get("X-Webhook-Id"), then queue the work. w.WriteHeader(http.StatusNoContent) } ``` ```java import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.HexFormat; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public final class CallMitraSignature { /** True when signatureHeader is the hex HMAC-SHA256 of rawBody with secret. */ public static boolean isValid(byte[] rawBody, String signatureHeader, String secret) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); String expected = HexFormat.of().formatHex(mac.doFinal(rawBody)); byte[] received = signatureHeader == null ? new byte[0] : signatureHeader.getBytes(StandardCharsets.UTF_8); return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), received); } } // After isValid(...) returns true, parse the JSON, reject a `timestamp` older than 300 seconds, // and skip X-Webhook-Id values you have already handled. ``` **Use the right secret.** A campaign webhook is signed with the campaign's `crmWebhookSecret` and an agent webhook with the agent's secret. ### On webhook endpoint deliveries [#on-webhook-endpoint-deliveries] Deliveries to [webhook endpoints](/webhooks/endpoints) also carry `X-Signature-SHA256`, so you can point an existing campaign or agent receiver at an endpoint. Some things differ: - The key is the **whole** endpoint secret as text, including the `whsec_` prefix. It is not base64-decoded. - It is computed with the **current** secret only. After you [rotate the secret](/webhooks/endpoints#rotate-the-signing-secret), it uses the new one at once, with no overlap. - The envelope body has no `timestamp` field. Check the `webhook-timestamp` header instead, but note that `X-Signature-SHA256` does not cover it. For these reasons, verify `webhook-signature` on endpoint deliveries. See [Verify signatures](/webhooks/verify-signatures). ## Move to webhook endpoints [#move-to-webhook-endpoints] ### Create an endpoint [#create-an-endpoint] [Create a webhook endpoint](/webhooks/endpoints#create-an-endpoint) for your receiver's URL (it must be `https://`), subscribed to the events you use today, for example `call.completed` and `call.escalated`. Store the `whsec_…` secret. ### Update your receiver [#update-your-receiver] Read the event from the envelope: the type is in `type` and the fields are in `data`. Verify `webhook-signature` as in [Verify signatures](/webhooks/verify-signatures), and drop duplicates by `webhook-id`. If you build ids from `X-Webhook-Id`, note that endpoint ids are `evt_…` values. ### Run both for a while [#run-both-for-a-while] Both systems deliver while the campaign or agent URL is set, so your receiver gets two copies of each call event with different ids. Dedupe on `data.callId` plus the event type until you clear that URL. ### Clear the campaign and agent URLs [#clear-the-campaign-and-agent-urls] Send `""` as the campaign's `crmWebhookUrl` and the agent's `url`. # Managing endpoints (/webhooks/endpoints) A webhook endpoint is a URL plus a list of event types. CallMitra signs every delivery to it with the endpoint's own secret. You can manage endpoints in the console or with the API. **In the console**, open **Settings → Developers → Webhooks**. A manager can create, edit and delete endpoints, pick event types, copy the signing secret (shown once), send a test event, and browse the delivery log and redeliver events. **With the API**, use the requests below. All paths are under `https://api.callmitra.ai`. | Task | Request | | --- | --- | | Create an endpoint | [`POST /api/v1/webhook-endpoints/`](/api-reference/webhooks/createWebhookEndpoint) | | List endpoints | [`GET /api/v1/webhook-endpoints/`](/api-reference/webhooks/listWebhookEndpoints) | | Get one endpoint | [`GET /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/getWebhookEndpoint) | | Update an endpoint | [`PATCH /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/updateWebhookEndpoint) | | Delete an endpoint | [`DELETE /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/deleteWebhookEndpoint) | | Rotate the secret | [`POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret`](/api-reference/webhooks/rotateWebhookEndpointSecret) | | Send a test event | [`POST /api/v1/webhook-endpoints/{endpoint_id}/test`](/api-reference/webhooks/sendTestWebhook) | | List event types | [`GET /api/v1/webhook-event-types/`](/api-reference/webhooks/listWebhookEventTypes) | | List deliveries | [`GET /api/v1/webhook-deliveries/`](/api-reference/webhooks/listWebhookDeliveries) | | Get one delivery | [`GET /api/v1/webhook-deliveries/{delivery_id}`](/api-reference/webhooks/getWebhookDelivery) | | Redeliver an event | [`POST /api/v1/webhook-deliveries/{delivery_id}/redeliver`](/api-reference/webhooks/redeliverWebhook) | ## Permissions [#permissions] - **Reading** (list and get endpoints, deliveries and event types) works for any member of the workspace. - **Changing** (create, update, delete, rotate, test and redeliver) needs a workspace **manager**. An API key acts with the role of the user who created it. - An API key limited to certain resources needs the **Webhooks** resource. A read-only key can only send `GET` requests. Without the right access you get [`permission_denied`](/errors/permission_denied) or [`api_key_scope_denied`](/errors/api_key_scope_denied). A request that is not tied to a workspace gets [`webhook_workspace_required`](/errors/webhook_workspace_required). ## Create an endpoint [#create-an-endpoint] | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | Yes | Public `https://` URL, up to 2048 characters. See [URL requirements](/webhooks#url-requirements). | | `description` | string | No | A label for you, up to 500 characters. Default `""`. | | `events` | string[] | No | Event types to receive, up to 50. Empty or left out means every event type. See [Event types](/webhooks/events). | | `enabled` | boolean | No | Default `true`. Send `false` to create the endpoint without sending to it yet. | ```bash curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6a1d0f3e-create-crm-endpoint" \ -d '{ "url": "https://example.com/webhooks/callmitra", "description": "CRM sync", "events": ["call.completed", "call.failed", "lead.created"] }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/webhook-endpoints/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': '6a1d0f3e-create-crm-endpoint', }, body: JSON.stringify({ url: 'https://example.com/webhooks/callmitra', description: 'CRM sync', events: ['call.completed', 'call.failed', 'lead.created'], }), }); const { webhookEndpoint, secret } = await res.json(); // Store `secret` now. It is not shown again. ``` ```python import os import requests res = requests.post( "https://api.callmitra.ai/api/v1/webhook-endpoints/", headers={ "X-API-Key": os.environ["CALLMITRA_API_KEY"], "Idempotency-Key": "6a1d0f3e-create-crm-endpoint", }, json={ "url": "https://example.com/webhooks/callmitra", "description": "CRM sync", "events": ["call.completed", "call.failed", "lead.created"], }, ) body = res.json() secret = body["secret"] # Store it now. It is not shown again. ``` The `Idempotency-Key` header is optional. With it, a retried create request does not make a second endpoint. See [Idempotency](/idempotency). ```json { "success": true, "webhookEndpoint": { "id": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c", "url": "https://example.com/webhooks/callmitra", "description": "CRM sync", "events": ["call.completed", "call.failed", "lead.created"], "enabled": true, "disabledReason": null, "disabledAt": null, "consecutiveFailures": 0, "lastStatus": "", "lastSuccessAt": null, "lastFailureAt": null, "previousSecretExpiresAt": null, "createdAt": "2026-11-15T05:30:00.000000+00:00", "updatedAt": "2026-11-15T05:30:00.000000+00:00" }, "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8m1gTzZ4dKo=" } ``` `secret` appears only in this response and in the response to a [rotation](#rotate-the-signing-secret). CallMitra stores it encrypted and never returns it again. If you lose it, rotate the secret. | Error | When | | --- | --- | | [`webhook_https_required`](/errors/webhook_https_required) | The URL is not `https://`. | | [`webhook_url_invalid`](/errors/webhook_url_invalid) | The URL is not absolute, has a username or password, or resolves to a private or local address. | | [`webhook_event_type_unknown`](/errors/webhook_event_type_unknown) | `events` contains a type that does not exist, or `webhook.test`. | | [`webhook_endpoint_limit_reached`](/errors/webhook_endpoint_limit_reached) | The workspace already has 20 endpoints. | | [`idempotency_key_reused`](/errors/idempotency_key_reused) | You sent the same `Idempotency-Key` with a different body. | ## Endpoint fields [#endpoint-fields] | Field | Description | | --- | --- | | `id` | Endpoint id. | | `url` | Where events are sent. | | `description` | Your label. | | `events` | Subscribed event types. Empty means every event type. | | `enabled` | `false` when you paused it or CallMitra [disabled it](/webhooks#automatic-disabling). | | `disabledReason` | Why CallMitra disabled it, for example `Disabled after 20 failed deliveries in a row over 24 hours (last: HTTP 500).` | | `disabledAt` | When CallMitra disabled it. | | `consecutiveFailures` | Failed attempts in a row since the last success. Retries count. | | `lastStatus` | Result of the latest attempt, such as `HTTP 200` or `timeout`. | | `lastSuccessAt` | Time of the latest successful attempt. | | `lastFailureAt` | Time of the latest failed attempt. | | `previousSecretExpiresAt` | After a rotation, the time until which the old secret also signs deliveries. | | `createdAt`, `updatedAt` | ISO 8601 times. | ## List and get endpoints [#list-and-get-endpoints] `GET /api/v1/webhook-endpoints/` returns every endpoint of the workspace in one page, as `webhookEndpoints`. `nextCursor` is always `null` and `hasMore` is always `false`. `GET /api/v1/webhook-endpoints/{endpoint_id}` returns one endpoint as `webhookEndpoint`, or [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found). ```bash curl https://api.callmitra.ai/api/v1/webhook-endpoints/ \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ## Update an endpoint [#update-an-endpoint] `PATCH` changes only the fields you send: `url`, `description`, `events` or `enabled`. A new `events` list replaces the old one. A new `url` goes through the same checks as on create. Setting `"enabled": true` on a disabled endpoint clears `disabledReason`, `disabledAt` and the failure count. New events start to arrive again. Events from the time it was disabled are not queued again; [redeliver](#redeliver-an-event) the ones you need. ```bash curl -X PATCH https://api.callmitra.ai/api/v1/webhook-endpoints/7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true, "events": ["call.completed", "call.failed"]}' ``` ```js const endpointId = '7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c'; const res = await fetch(`https://api.callmitra.ai/api/v1/webhook-endpoints/${endpointId}`, { method: 'PATCH', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ enabled: true, events: ['call.completed', 'call.failed'] }), }); const { webhookEndpoint } = await res.json(); ``` ```python endpoint_id = "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c" res = requests.patch( f"https://api.callmitra.ai/api/v1/webhook-endpoints/{endpoint_id}", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, json={"enabled": True, "events": ["call.completed", "call.failed"]}, ) endpoint = res.json()["webhookEndpoint"] ``` ## Delete an endpoint [#delete-an-endpoint] `DELETE /api/v1/webhook-endpoints/{endpoint_id}` stops deliveries to it at once, including pending retries. It also deletes the endpoint's delivery history. The response is `{"success": true, "id": "…", "deleted": true}`. To stop deliveries but keep the history, set `"enabled": false` instead. ## Rotate the signing secret [#rotate-the-signing-secret] `POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret` returns a new `secret`, once, in the same shape as the create response. For the next **24 hours**, the old secret keeps working. Each delivery carries two signatures in `webhook-signature`: the new one first, then the old one. `previousSecretExpiresAt` shows when the old secret stops. This gives you time to deploy the new secret without failing any delivery. ```http webhook-signature: v1,Q3VycmVudFNpZ25hdHVyZUJhc2U2NA== v1,T2xkU2lnbmF0dXJlQmFzZTY0QmFzZQ== ``` ### Rotate [#rotate] Call `rotate-secret` and store the new secret. ### Deploy [#deploy] Update your receiver to use the new secret. A receiver that [checks every signature in the header](/webhooks/verify-signatures) accepts deliveries during the whole switch. ### Wait [#wait] After `previousSecretExpiresAt`, only the new secret signs deliveries. Rotating again within 24 hours makes the secret you just replaced the "old" one. The secret before it stops working at once. The `X-Signature-SHA256` header is signed with the **new** secret only, from the moment you rotate. If your receiver checks that header, deploy the new secret first. See [Verify X-Signature-SHA256](/webhooks/campaign-agent-webhooks#verify-x-signature-sha256). ## Send a test event [#send-a-test-event] `POST /api/v1/webhook-endpoints/{endpoint_id}/test` sends a signed `webhook.test` event to the endpoint at once, whatever its `events` filter. The request waits for the attempt and returns the delivery, with your server's answer and the payload that was sent. ```bash curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c/test \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` ```json { "success": true, "webhookDelivery": { "id": "0b9d6c2e-3f41-4a7b-8e5d-9c1f2a3b4d5e", "eventId": "evt_2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b", "eventType": "webhook.test", "endpointId": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c", "status": "delivered", "attempts": 1, "lastStatusCode": 200, "lastError": "", "responseSnippet": "ok", "latencyMs": 184, "nextAttemptAt": null, "lastAttemptAt": "2026-11-15T05:35:12.004211+00:00", "deliveredAt": "2026-11-15T05:35:12.004211+00:00", "createdAt": "2026-11-15T05:35:11.812930+00:00", "payload": { "id": "evt_2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b", "type": "webhook.test", "apiVersion": "v1", "createdAt": "2026-11-15T05:35:11.810422Z", "data": { "endpointId": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c", "message": "This is a test event from Call Mitra." } } } } ``` If your server fails the test, `status` is `pending` and the test is retried like any other delivery. A disabled endpoint returns [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled); enable it first. You cannot subscribe to `webhook.test`. ## List event types [#list-event-types] `GET /api/v1/webhook-event-types/` returns every type you can put in `events`, with a short description. ```json { "success": true, "eventTypes": [ { "type": "call.completed", "description": "A call ended (any final status). Sent after post-call analysis." }, { "type": "call.failed", "description": "A call ended without connecting: busy, no answer or carrier failure. Sent with call.completed." }, { "type": "call.escalated", "description": "The agent transferred the caller to a person." } ] } ``` See [Event types](/webhooks/events) for when each one fires and what it contains. ## Delivery log [#delivery-log] Each time CallMitra queues an event for an endpoint, it creates a **delivery**. Retries update the same delivery. A redelivery creates a new one. `GET /api/v1/webhook-deliveries/` lists deliveries, newest first. | Query parameter | Description | | --- | --- | | `endpointId` | Only deliveries to this endpoint. An unknown id returns [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found). | | `eventType` | Only this event type, for example `call.completed`. | | `status` | `pending`, `processing`, `delivered` or `failed`. Any other value returns [`parameter_invalid`](/errors/parameter_invalid). | | `limit` | Deliveries per page, 1 to 100. Default 25. | | `cursor` | `nextCursor` from the previous page. | The response has `webhookDeliveries`, `nextCursor` and `hasMore`. While `hasMore` is `true`, pass `nextCursor` as `cursor` to get the next page. List items do not include `payload`. ```bash curl -G https://api.callmitra.ai/api/v1/webhook-deliveries/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ --data-urlencode "endpointId=7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c" \ --data-urlencode "status=failed" \ --data-urlencode "limit=50" ``` ```js const failed = []; let cursor; do { const params = new URLSearchParams({ status: 'failed', limit: '100' }); if (cursor) params.set('cursor', cursor); const res = await fetch(`https://api.callmitra.ai/api/v1/webhook-deliveries/?${params}`, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY }, }); const page = await res.json(); failed.push(...page.webhookDeliveries); cursor = page.hasMore ? page.nextCursor : undefined; } while (cursor); ``` ```python failed, cursor = [], None while True: params = {"status": "failed", "limit": 100} if cursor: params["cursor"] = cursor page = requests.get( "https://api.callmitra.ai/api/v1/webhook-deliveries/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, params=params, ).json() failed.extend(page["webhookDeliveries"]) if not page["hasMore"]: break cursor = page["nextCursor"] ``` | Status | Meaning | | --- | --- | | `pending` | Waiting for its first attempt or its next retry. See `nextAttemptAt`. | | `processing` | An attempt is being sent now. | | `delivered` | Your server answered `2xx`. Final. | | `failed` | Rejected with a non-retryable status, out of attempts, or stopped (for example the endpoint was disabled). Final. | | Field | Description | | --- | --- | | `id` | Delivery id. | | `eventId` | Event id (`evt_…`). The `webhook-id` header. | | `eventType` | Event type. | | `endpointId` | Endpoint it is sent to. | | `status` | See the table above. | | `attempts` | Attempts made so far, up to 12. | | `lastStatusCode` | HTTP status from the last attempt. `null` if no response was received. | | `lastError` | Why the last attempt failed, such as `HTTP 500` or `timeout`. Empty on success. | | `responseSnippet` | First 1 KB of your last response body. | | `latencyMs` | How long the last attempt took. | | `nextAttemptAt` | When the next attempt is due. Only while `pending`. | | `lastAttemptAt` | Time of the last attempt. | | `deliveredAt` | When your server accepted the event. | | `createdAt` | When the delivery was queued. | | `payload` | The exact envelope that was signed and sent. Only on a single delivery, not in lists. | Delivered and failed deliveries are deleted after **30 days**. ## Get a delivery [#get-a-delivery] `GET /api/v1/webhook-deliveries/{delivery_id}` returns one delivery as `webhookDelivery`, including `payload`. Use it to see exactly what was sent. An unknown id returns [`webhook_delivery_not_found`](/errors/webhook_delivery_not_found). ## Redeliver an event [#redeliver-an-event] `POST /api/v1/webhook-deliveries/{delivery_id}/redeliver` queues the same event to the same endpoint again, due now. It creates a **new** delivery with the same `eventId` and `payload` and returns it (usually with `status: "pending"`). The `webhook-id` header is the same as before, so a receiver that drops duplicates ignores events it already handled. ```bash curl -X POST https://api.callmitra.ai/api/v1/webhook-deliveries/0b9d6c2e-3f41-4a7b-8e5d-9c1f2a3b4d5e/redeliver \ -H "X-API-Key: $CALLMITRA_API_KEY" ``` The endpoint must be enabled, or you get [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled). The new delivery gets the full retry schedule. Test events and redeliveries share a limit of **10 per endpoint per minute**, from the console and the API combined. Above it you get `429` [`rate_limit_exceeded`](/errors/rate_limit_exceeded) with `Retry-After`. To catch up on many events, space out the redeliveries. To catch up after an outage: re-enable the endpoint, list deliveries with `status=failed` for it, and redeliver each one. # Event types (/webhooks/events) Every delivery to a [webhook endpoint](/webhooks/endpoints) has the same envelope. The event's own fields are in `data`. ```json { "id": "evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b", "type": "call.completed", "apiVersion": "v1", "createdAt": "2026-11-15T05:31:50.412093Z", "data": {} } ``` The `type` field and the `X-Webhook-Event` header tell events apart. New event types and new fields in `data` can be added at any time (see [Versioning](/versioning)). Ignore fields and event types you do not use. Event names are never renamed or removed. Each event links to its page in the API reference, which has the full schema. You can also list the types with [`GET /api/v1/webhook-event-types/`](/api-reference/webhooks/listWebhookEventTypes). ## Catalogue [#catalogue] | Event | When it fires | Also sent to [campaign and agent URLs](/webhooks/campaign-agent-webhooks) | | --- | --- | --- | | [`call.completed`](#callcompleted-and-callfailed) | A call ended, with any final status. Sent after post-call analysis. | Yes | | [`call.failed`](#callcompleted-and-callfailed) | A call ended without connecting: busy, no answer or carrier failure. Sent together with `call.completed`. | No | | [`call.escalated`](#callescalated) | The agent transferred the caller to a person. | Yes | | [`transfer.failed`](#transferfailed) | A transfer to a person did not connect. | If enabled | | [`callback.scheduled`](#callback-events) | A callback was booked for a lead. | If enabled | | [`callback.completed`](#callback-events) | A booked callback was made. | If enabled | | [`callback.failed`](#callback-events) | A booked callback could not reach the lead after its attempts. | If enabled | | [`lead.created`](#leadcreated-and-leadupdated) | A lead was added one at a time: through the API, the console's add-lead form or a lead source. Not sent for bulk imports. | No | | [`lead.updated`](#leadcreated-and-leadupdated) | A lead was edited in the console or through the API. | No | | [`campaign.started`](#campaignstarted-and-campaigncompleted) | A campaign was started. | No | | [`campaign.completed`](#campaignstarted-and-campaigncompleted) | A campaign finished dialing every lead. | No | | [`ticket.created`](#ticket-events) | A support ticket was opened. | No | | [`ticket.updated`](#ticket-events) | A support ticket changed. | No | | [`ticket.resolved`](#ticket-events) | A support ticket was resolved. | No | | [`ticket.reopened`](#ticket-events) | A resolved or closed ticket opened again. | No | | [`ticket.rated`](#ticket-events) | A customer rated a support ticket. | No | | [`whatsapp.message.received`](#whatsappmessagereceived) | A customer sent a WhatsApp message to one of your numbers. | No | | [`webhook.test`](#webhooktest) | You sent a test event. Cannot be subscribed to. | No | ## `call.completed` and `call.failed` [#callcompleted-and-callfailed] `call.completed` is sent once per call when it ends, answered or not. CallMitra waits about 20 seconds after the call ends so the post-call analysis is ready, and reads the call's data when the first attempt is sent. `call.failed` is sent for the same call, at the same time, only when the final status is `failed`, `busy` or `no_answer`. Its `data` is the same as `call.completed`. The two events have different ids. Subscribe to `call.failed` alone if you only want to act on calls that did not connect. Reference: [`call.completed`](/api-reference/webhooks/onCallCompleted), [`call.failed`](/api-reference/webhooks/onCallFailed). | Field | Type | Description | | --- | --- | --- | | `callId` | UUID | The call. Fetch details with [`GET /api/v1/calls/{call_id}`](/api-reference/calls/getCall). | | `campaignId` | UUID or null | The campaign that placed or received the call. | | `leadId` | UUID or null | The lead called. | | `agentId` | UUID or null | The agent that handled the call. | | `phone` | string or null | The lead's phone number, or the dialed number when there is no lead. | | `customerNumber` | string or null | The number dialed, or the caller's number. | | `lead` | object or null | `id`, `name`, `phone`, `email`, `company`, `externalId`, and `customFields` (your custom fields, minus sensitive and archived ones). | | `direction` | string | `outbound` or `inbound`. | | `status` | string | Final call status, for example `completed`, `no_answer`, `busy` or `failed`. | | `duration` | number or null | Talk time in seconds. | | `endedReason` | string or null | Why the call ended. | | `startTime`, `endTime` | string or null | ISO 8601, UTC. | | `recordingUrl` | string or null | Recording URL. Fetch it with your `X-API-Key`; see [`GET /api/v1/calls/{call_id}/recording`](/api-reference/calls/getCallRecording). | | `summary` | string or null | AI summary of the conversation. | | `transcript` | string or null | Full transcript. | | `outcome`, `outcomeCategory` | string or null | The agent's detailed outcome and its category. | | `merchantOutcome` | string | Normalized outcome: `qualified`, `interested`, `callback`, `not_interested`, `no_response`, `no_answer`, `busy`, `call_failed`, `voicemail`, or empty. | | `sentiment` | string or null | `positive`, `neutral` or `negative`, when analyzed. | | `extractedFields` | object | Values the agent collected, keyed by the field names set on the agent. | | `callAnalysis` | object or null | The full post-call analysis. | | `recommendedLeadStatus` | string or null | Suggested next status for the lead in your CRM. | | `crmPayload` | object or null | Everything the call stored for your CRM, including the analysis and transfer details. | | `providerCallId` | string or null | The carrier's call id. | ```json title="call.completed" { "id": "evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b", "type": "call.completed", "apiVersion": "v1", "createdAt": "2026-11-15T05:31:50.412093Z", "data": { "callId": "3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b", "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "phone": "+919876543210", "customerNumber": "+919876543210", "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "lead": { "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao", "phone": "+919876543210", "email": "", "company": "", "externalId": "crm-1042", "customFields": { "plan": "Gold" } }, "direction": "outbound", "status": "completed", "duration": 94, "endedReason": "customer-ended-call", "startTime": "2026-11-15T05:30:12+00:00", "endTime": "2026-11-15T05:31:46+00:00", "recordingUrl": "https://api.callmitra.ai/api/v1/calls/3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b/recording", "summary": "Customer wants to renew the Gold plan and asked for a callback on Monday.", "transcript": "Agent: Namaste Asha ji…", "outcome": "callback_requested", "outcomeCategory": "positive", "merchantOutcome": "callback", "sentiment": "positive", "extractedFields": { "preferredCallbackDay": "Monday" }, "callAnalysis": { "summary": "…" }, "recommendedLeadStatus": "follow_up", "crmPayload": { "callAnalysis": { "summary": "…" } }, "providerCallId": "CA1234567890abcdef" } } ``` ## `call.escalated` [#callescalated] Sent when the agent transfers a call to a person, for example a warm transfer to your sales team. The same call still sends `call.completed` when it ends. If the transfer does not connect, [`transfer.failed`](#transferfailed) is sent too. Reference: [`call.escalated`](/api-reference/webhooks/onCallEscalated). | Field | Type | Description | | --- | --- | --- | | `callId`, `campaignId`, `leadId`, `agentId` | UUID or null | As for `call.completed`. | | `phone`, `customerNumber`, `lead`, `direction` | | As for `call.completed`. | | `transferType` | string or null | How the call was handed over, for example `cold_pstn`, `cold_sip` or `warm_mpc`. | | `transferTarget` | string or null | Where it was transferred to. | | `transferStatus` | string or null | State of the transfer, for example `initiated`. | | `transferDialStatus` | string or null | The carrier's answer for the transfer leg, when known. | | `transferReason` | string or null | Why the agent escalated. | | `endedReason` | string or null | Why the call ended. | | `providerCallId` | string or null | The carrier's call id. | ```json title="call.escalated" { "id": "evt_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "type": "call.escalated", "apiVersion": "v1", "createdAt": "2026-11-15T05:31:02.118540Z", "data": { "callId": "3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b", "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "phone": "+919876543210", "customerNumber": "+919876543210", "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "lead": { "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao", "phone": "+919876543210" }, "direction": "outbound", "transferType": "cold_pstn", "transferTarget": "+918041234567", "transferStatus": "initiated", "transferDialStatus": null, "transferReason": "Customer asked to speak to a sales manager.", "endedReason": "transfer_initiated", "providerCallId": "CA1234567890abcdef" } } ``` ## `transfer.failed` [#transferfailed] Sent when a transfer to a person does not connect. Reference: [`transfer.failed`](/api-reference/webhooks/onTransferFailed). | Field | Type | Description | | --- | --- | --- | | `callId` | UUID | The call. | | `leadId`, `campaignId`, `agentId` | UUID or null | The lead, campaign and agent of the call. | | `dialStatus` | string or null | The carrier's answer, for example `no-answer` or `busy`. | ```json title="transfer.failed" { "id": "evt_1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a", "type": "transfer.failed", "apiVersion": "v1", "createdAt": "2026-11-15T05:31:20.007311Z", "data": { "callId": "3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "dialStatus": "no-answer" } } ``` ## Callback events [#callback-events] `callback.scheduled` fires when a callback is booked for a lead, for example when the caller asks the agent to call back later. `callback.completed` fires when the callback call is made. `callback.failed` fires when the callback could not reach the lead after its attempts. All three have the same `data`. Reference: [`callback.scheduled`](/api-reference/webhooks/onCallbackScheduled), [`callback.completed`](/api-reference/webhooks/onCallbackCompleted), [`callback.failed`](/api-reference/webhooks/onCallbackFailed). | Field | Type | Description | | --- | --- | --- | | `callbackId` | UUID | The callback. | | `leadId` | UUID | The lead to call back. | | `kind` | string | `callback` or `reminder`. | | `campaignId`, `agentId` | UUID or null | The campaign and agent that make the call. | | `when` | string | The callback time in the lead's time zone, readable, for example `Tue 4 Nov, 5:00 PM`. | | `dialAt` | string | The callback time, ISO 8601. | | `attempts` | integer | Attempts made so far. | | `source` | string | How it was booked: `ai_tool` (the agent during a call), `analysis`, `keyword`, `console`, `api`, `csv`, `rule` or `handoff`. | | `note` | string | The note saved with the callback. | ```json title="callback.scheduled" { "id": "evt_4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e", "type": "callback.scheduled", "apiVersion": "v1", "createdAt": "2026-11-15T05:31:40.551902Z", "data": { "callbackId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "kind": "callback", "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "when": "Mon 17 Nov, 11:00 AM", "dialAt": "2026-11-17T05:30:00+00:00", "attempts": 0, "source": "ai_tool", "note": "Wants to discuss Gold plan renewal." } } ``` ## `lead.created` and `lead.updated` [#leadcreated-and-leadupdated] `lead.created` fires for leads added **one at a time**: - [`createLead`](/api-reference/leads/createLead); - the console's add-lead form; - each lead a connected lead source delivers (Meta lead ads, Google Ads lead forms, lead-source webhooks). It is **not** sent for: - spreadsheet imports, campaign lead uploads, or campaigns created with leads; - leads made automatically for WhatsApp contacts, unknown inbound callers, outbound calls to a new number, or do-not-call entries. After a bulk import, list the leads with [`GET /api/v1/leads/`](/api-reference/leads/listLeads) instead of waiting for events. `lead.updated` fires when a lead is edited in the console or through the API. Both carry the lead as it is after the change. Reference: [`lead.created`](/api-reference/webhooks/onLeadCreated), [`lead.updated`](/api-reference/webhooks/onLeadUpdated). To fetch a lead later, use [`GET /api/v1/leads/{lead_id}`](/api-reference/leads/getLead). | Field | Type | Description | | --- | --- | --- | | `id` | UUID | The lead. | | `name`, `phone`, `email`, `company` | string | Contact details. | | `externalId` | string or null | Your id for this lead, when you sent one. | | `customFields` | object | Custom field values, minus sensitive and archived fields. | | `title` | string | The lead's title. | | `status` | string or null | Pipeline status, for example `new`. | | `source` | string | Where the lead came from, as set on the lead. | | `leadSourceId` | UUID or null | The lead source that created it, if any. | | `tags` | string[] | Tags. | | `assignedToUserId` | UUID or null | The user the lead is assigned to. | | `callStatus` | string or null | Calling state, for example `not_called`. | | `createdAt`, `updatedAt` | string or null | ISO 8601. | ```json title="lead.created" { "id": "evt_7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b", "type": "lead.created", "apiVersion": "v1", "createdAt": "2026-11-15T04:12:08.300114Z", "data": { "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao", "phone": "+919876543210", "email": "asha@example.com", "company": "", "externalId": "crm-1042", "customFields": { "plan": "Gold" }, "title": "", "status": "new", "source": "website", "leadSourceId": null, "tags": ["renewal"], "assignedToUserId": null, "callStatus": "not_called", "createdAt": "2026-11-15T04:12:08.291004+00:00", "updatedAt": "2026-11-15T04:12:08.291004+00:00" } } ``` ## `campaign.started` and `campaign.completed` [#campaignstarted-and-campaigncompleted] `campaign.started` fires when a campaign is started. For an inbound campaign, that is when it is turned on. `campaign.completed` fires when an outbound campaign has dialed every lead. Reference: [`campaign.started`](/api-reference/webhooks/onCampaignStarted), [`campaign.completed`](/api-reference/webhooks/onCampaignCompleted). | Field | Type | Description | | --- | --- | --- | | `campaignId` | UUID | The campaign. | | `name` | string | Campaign name. | | `direction` | string | `outbound` or `inbound`. | | `agentId` | UUID or null | The campaign's agent. | | `startedAt` | string or null | When dialing started, ISO 8601. | | `completedAt` | string | When it finished, ISO 8601. Only on `campaign.completed`. | ```json title="campaign.completed" { "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0", "type": "campaign.completed", "apiVersion": "v1", "createdAt": "2026-11-15T09:45:00.120044Z", "data": { "campaignId": "8a7d9c2b-1e3f-4a5b-8c6d-7e8f9a0b1c2d", "name": "Gold renewals – November", "direction": "outbound", "agentId": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726", "startedAt": "2026-11-15T04:30:00.004512+00:00", "completedAt": "2026-11-15T09:45:00.118201+00:00" } } ``` ## Ticket events [#ticket-events] | Event | When it fires | | --- | --- | | `ticket.created` | A ticket is opened. | | `ticket.updated` | A ticket changes: an edit, an assignment, a merge, an SLA breach, or a status change to anything other than `resolved`. | | `ticket.resolved` | The status changes to `resolved`. | | `ticket.reopened` | A `resolved` or `closed` ticket opens again. | | `ticket.rated` | The customer rates the ticket. | When a ticket reopens, CallMitra sends `ticket.updated` (for the status change) **and** `ticket.reopened`. If you subscribe to both, handle the reopen in one place. Closing a ticket (status `closed`) sends `ticket.updated`. Reference: [`ticket.created`](/api-reference/webhooks/onTicketCreated), [`ticket.updated`](/api-reference/webhooks/onTicketUpdated), [`ticket.resolved`](/api-reference/webhooks/onTicketResolved), [`ticket.reopened`](/api-reference/webhooks/onTicketReopened), [`ticket.rated`](/api-reference/webhooks/onTicketRated). | Field | Type | Description | | --- | --- | --- | | `ticketId` | UUID | The ticket. | | `ticketRef` | string | Short reference shown to the customer, for example `T-D4C3B2A1`. | | `merchantId` | UUID or null | Your workspace id. | | `leadId` | UUID | The customer's lead. | | `type` | string | `support` or `sales_followup`. | | `status` | string | `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`. | | `priority` | string | `low`, `normal`, `high` or `urgent`. | | `subject` | string | Subject line. | | `description` | string or null | Details. | | `source` | string | Where the ticket came from: `manual`, `inbound_call`, `outbound_call`, `import` or `whatsapp_conversation`. | | `sourceCallId` | UUID or null | The call that created it, if any. | | `assignedToUserId` | UUID or null | The main assignee. | | `assignees` | object[] | Every assignee: `userId`, `name`, `email`. | | `dueAt`, `firstResponseAt`, `resolvedAt`, `closedAt` | string or null | ISO 8601 times. | | `csatScore` | integer or null | The customer's rating. Set on `ticket.rated`. | | `csatAt` | string or null | When the customer rated it. | | `version` | integer | Goes up by one with each change. Use it to ignore older events that arrive late. | | `category`, `team` | object | `id` and `name`. Only when the ticket has one. | | `tags` | string[] | Only when the ticket has tags. | | `mergedInto` | object | `id` and `ref` of the ticket it was merged into. Only after a merge. | | `previousStatus` | string | The status before the reopen. Only on `ticket.reopened`. | | `reopenedBy` | string | What reopened it, for example `customer`. Only on `ticket.reopened`. | Some changes add extra keys that describe the change. Ignore keys you do not know. ```json title="ticket.resolved" { "id": "evt_6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d", "type": "ticket.resolved", "apiVersion": "v1", "createdAt": "2026-11-15T11:02:33.741220Z", "data": { "ticketId": "d4c3b2a1-9f8e-4d7c-b6a5-0f1e2d3c4b5a", "ticketRef": "T-D4C3B2A1", "merchantId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d", "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "type": "support", "status": "resolved", "priority": "high", "subject": "Renewal payment failed", "description": "Card was charged twice.", "source": "inbound_call", "sourceCallId": "3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b", "assignedToUserId": "9e8d7c6b-5a4f-4e3d-a2c1-b0a9f8e7d6c5", "assignees": [ { "userId": "9e8d7c6b-5a4f-4e3d-a2c1-b0a9f8e7d6c5", "name": "Ravi Kumar", "email": "ravi@example.com" } ], "dueAt": "2026-11-16T05:30:00+00:00", "firstResponseAt": "2026-11-15T06:10:00+00:00", "resolvedAt": "2026-11-15T11:02:33.720018+00:00", "closedAt": null, "csatScore": null, "csatAt": null, "version": 4, "category": { "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "name": "Billing" }, "tags": ["refund"] } } ``` ## `whatsapp.message.received` [#whatsappmessagereceived] Sent when a customer sends a message to one of your WhatsApp numbers. Each message is sent once, even if WhatsApp reports it twice. Reference: [`whatsapp.message.received`](/api-reference/webhooks/onWhatsappMessageReceived). | Field | Type | Description | | --- | --- | --- | | `conversationId` | UUID | The conversation. | | `phoneId` | UUID | Your WhatsApp number that received the message. | | `windowOpen` | boolean | `true` while you can send free-form replies. | | `serviceWindowExpiresAt` | string or null | When the reply window closes, ISO 8601. | | `contact` | object | `id`, `name`, `phone`, `bsuid`, `username`, `leadId`, `optInStatus`, `tags`. | | `entrySource` | string or null | How the conversation started, when known. | | `message.id` | UUID | CallMitra's message id. | | `message.wamid` | string or null | WhatsApp's message id. | | `message.type` | string | `text`, `image`, `button`, `interactive`, `location` and so on. | | `message.text` | string or null | The text, caption or button label. | | `message.payload` | object | Extra content for some types, for example `location` or `button_payload`. Empty for plain text. Its keys are **not** converted to camelCase. | | `message.hasMedia` | boolean | `true` when the message has a file. | | `message.mediaMime`, `message.mediaFilename` | string or null | File type and name. | | `message.replyToWamid` | string or null | The message this one replies to. | | `message.createdAt` | string or null | ISO 8601. | ```json title="whatsapp.message.received" { "id": "evt_3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f", "type": "whatsapp.message.received", "apiVersion": "v1", "createdAt": "2026-11-15T07:20:14.009871Z", "data": { "conversationId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "phoneId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "windowOpen": true, "serviceWindowExpiresAt": "2026-11-16T07:20:13+00:00", "contact": { "id": "f0e1d2c3-b4a5-4968-8776-655443322110", "name": "Asha Rao", "phone": "+919876543210", "bsuid": null, "username": null, "leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "optInStatus": "opted_in", "tags": [] }, "entrySource": null, "message": { "id": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg", "type": "text", "text": "Is my renewal done?", "payload": {}, "hasMedia": false, "mediaMime": null, "mediaFilename": null, "replyToWamid": null, "createdAt": "2026-11-15T07:20:13.882140+00:00" } } } ``` ## `webhook.test` [#webhooktest] Sent only when you call [`POST /api/v1/webhook-endpoints/{endpoint_id}/test`](/api-reference/webhooks/sendTestWebhook). It goes to that one endpoint, whatever its event filter. You cannot subscribe to it. Reference: [`webhook.test`](/api-reference/webhooks/onWebhookTest). ```json title="webhook.test" { "id": "evt_2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b", "type": "webhook.test", "apiVersion": "v1", "createdAt": "2026-11-15T05:35:11.810422Z", "data": { "endpointId": "7c1e2f4a-9b3d-4e8f-a6c2-1d5b7e9f0a3c", "message": "This is a test event from Call Mitra." } } ``` # Webhooks overview (/webhooks) CallMitra sends a webhook when something happens in your workspace: a call ends, a lead is created, a campaign finishes, a ticket is resolved, a customer writes on WhatsApp. Each webhook is an HTTPS `POST` with a JSON body. It is signed, so you can check that it came from CallMitra. If your server does not accept it, CallMitra retries. ## Two ways to receive events [#two-ways-to-receive-events] | | Webhook endpoints | Campaign and agent webhook URLs | | --- | --- | --- | | Where you set them | **Settings → Developers → Webhooks** in the console, or [`/api/v1/webhook-endpoints`](/webhooks/endpoints) | A campaign's `crmWebhookUrl` or an agent's post-call webhook | | Events | [Every event type](/webhooks/events), with a filter per endpoint | `call.completed`, `call.escalated`, plus `callback.*` and `transfer.failed` in some cases | | Body | An envelope: `id`, `type`, `apiVersion`, `createdAt`, `data` | Flat JSON with `event` and `timestamp` at the top level | | Signature | [Standard Webhooks](/webhooks/verify-signatures) (`webhook-signature`) and `X-Signature-SHA256` | `X-Signature-SHA256` only | | Delivery log and redelivery | Yes, for 30 days, in the console and the API | No | Use **webhook endpoints** for new integrations. The two systems are independent: when a call ends, every subscribed endpoint gets `call.completed`, and the campaign or agent URL for that call gets its own copy too. If you set up both and want one copy, clear that URL. See [Campaign and agent webhooks](/webhooks/campaign-agent-webhooks) for how those URLs work and how to move off them. There is no workspace-wide URL any more: use an endpoint. WhatsApp also has its own webhook endpoints, managed per WhatsApp number under **WhatsApp → Developers** in the console. This section covers workspace webhook endpoints. To get WhatsApp messages here, subscribe an endpoint to `whatsapp.message.received`. ## Quick setup [#quick-setup] ### Build a receiver [#build-a-receiver] Add an HTTPS route on your server that accepts `POST` requests with a JSON body. Keep the raw body bytes: you need them to [verify the signature](/webhooks/verify-signatures). ### Create an endpoint [#create-an-endpoint] In the console, open **Settings → Developers → Webhooks** and add the endpoint there. With the API, send your URL and the events you want. Send an empty `events` list (or leave it out) to get every event type. ```bash curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/ \ -H "X-API-Key: $CALLMITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/callmitra", "description": "CRM sync", "events": ["call.completed", "call.failed", "lead.created"] }' ``` ```js const res = await fetch('https://api.callmitra.ai/api/v1/webhook-endpoints/', { method: 'POST', headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://example.com/webhooks/callmitra', description: 'CRM sync', events: ['call.completed', 'call.failed', 'lead.created'], }), }); const { webhookEndpoint, secret } = await res.json(); // Store `secret` now. It is not shown again. ``` ```python import os import requests res = requests.post( "https://api.callmitra.ai/api/v1/webhook-endpoints/", headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]}, json={ "url": "https://example.com/webhooks/callmitra", "description": "CRM sync", "events": ["call.completed", "call.failed", "lead.created"], }, ) body = res.json() secret = body["secret"] # store it now; it is not shown again ``` ### Store the secret [#store-the-secret] The response includes `secret` (`whsec_…`). It appears only in this response and when you [rotate it](/webhooks/endpoints#rotate-the-signing-secret). Keep it in your secret store, for example as `CALLMITRA_WEBHOOK_SECRET`. ### Send a test event [#send-a-test-event] Use **Send test event** in the endpoint's menu in the console, or call [`POST /api/v1/webhook-endpoints/{endpoint_id}/test`](/api-reference/webhooks/sendTestWebhook). CallMitra sends a signed `webhook.test` event at once and returns your server's answer. Managing endpoints needs a workspace **manager** (or an API key created by one). An API key limited to resources needs **Webhooks**. See [Managing endpoints](/webhooks/endpoints). ## What a delivery looks like [#what-a-delivery-looks-like] ```http POST /webhooks/callmitra HTTP/1.1 Content-Type: application/json User-Agent: CallMitra-Webhooks/1 webhook-id: evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b webhook-timestamp: 1763184730 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= X-Webhook-Id: evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b X-Webhook-Event: call.completed X-Signature-SHA256: 9c1f0e… {"id":"evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b","type":"call.completed","apiVersion":"v1","createdAt":"2026-11-15T05:31:50.412093Z","data":{"callId":"3f2b8c1e-6a4d-4f7e-9b1a-2c5d8e9f0a1b",…}} ``` | Header | Meaning | | --- | --- | | `webhook-id` | The event id (`evt_` and 32 hex characters). The same on every retry and redelivery. Use it to drop duplicates. | | `webhook-timestamp` | When this attempt was sent, in Unix seconds. Each attempt has a new value. | | `webhook-signature` | One or more `v1,` values, separated by spaces. There are two for 24 hours after you rotate the secret. See [Verify signatures](/webhooks/verify-signatures). | | `X-Webhook-Id` | The same value as `webhook-id`. | | `X-Webhook-Event` | The event type, for example `call.completed`. | | `X-Signature-SHA256` | A hex HMAC-SHA256 of the raw body, for receivers built for [campaign and agent webhooks](/webhooks/campaign-agent-webhooks#verify-x-signature-sha256). | The body is the event envelope: | Field | Description | | --- | --- | | `id` | Event id. The same as the `webhook-id` header. | | `type` | Event type, for example `call.completed`. | | `apiVersion` | Always `v1` today. | | `createdAt` | When the event happened, ISO 8601 UTC. It does not change between retries. | | `data` | The event's fields. See [Event types](/webhooks/events). | New fields can be added to `data` at any time (see [Versioning](/versioning)). Ignore fields you do not use. ## Respond quickly [#respond-quickly] Answer with any `2xx` status within **10 seconds**. Do slow work, such as CRM updates or emails, after you respond, for example from a queue. CallMitra does not follow redirects, so a `3xx` counts as a failed attempt. It saves the first 1 KB of your response body in the delivery log to help you debug. ## Retries [#retries] | Your response | What CallMitra does | | --- | --- | | `2xx` | Delivered. | | `408`, `409`, `425`, `429`, `3xx`, any `5xx`, a timeout, a DNS or connection error | Retries, up to 12 attempts in total. | | Any other `4xx` | Treats the event as rejected. It does **not** retry. | | The URL now resolves to a private or local address | Fails at once. It does not retry. | The wait after each failed attempt starts at 30 seconds and doubles: | Attempt | Wait before it | About this long after the first attempt | | --- | --- | --- | | 1 | — | 0 | | 2 | 30 s | 30 s | | 3 | 1 min | 1.5 min | | 4 | 2 min | 3.5 min | | 5 | 4 min | 7.5 min | | 6 | 8 min | 15.5 min | | 7 | 16 min | 31.5 min | | 8 | 32 min | 1 h 4 min | | 9 | 64 min | 2 h 8 min | | 10 | 128 min | 4 h 16 min | | 11 | 256 min | 8 h 32 min | | 12 | 512 min | 17 h 4 min | After the 12th failed attempt, the delivery is marked `failed`. You can send it again from the [delivery log](/webhooks/endpoints#redeliver-an-event) for 30 days. `call.completed` and `call.failed` wait about 20 seconds after the call ends before the first attempt, so the post-call analysis is ready. The call's data is read when that first attempt is sent. ## Automatic disabling [#automatic-disabling] CallMitra disables an endpoint when both of these are true: - At least **20 attempts in a row** have failed. Retries count. - The endpoint has been failing for at least **24 hours** with no success. A disabled endpoint has `enabled: false`, a `disabledReason` and a `disabledAt` time. CallMitra alerts the workspace once when this happens: a notification in the console, plus email or WhatsApp if those alerts are turned on. New events are not queued for it. Retries that were waiting fail with `endpoint disabled`. Fix your receiver, then set `"enabled": true` with [`PATCH /api/v1/webhook-endpoints/{endpoint_id}`](/api-reference/webhooks/updateWebhookEndpoint). That clears the failure count. Then [redeliver](/webhooks/endpoints#redeliver-an-event) the events you missed. ## Duplicates and ordering [#duplicates-and-ordering] - **Expect duplicates.** If your server handles an event but answers too late, CallMitra retries it. A redelivery also sends the same event again. Store the `webhook-id` values you have handled and skip repeats. - **Expect any order.** Deliveries are sent in parallel, and a retry can arrive after a newer event. Use `createdAt`, or fetch the current state from the API, for example [`GET /api/v1/calls/{call_id}`](/api-reference/calls/getCall). - A call's `call.completed` and `call.failed` have different ids. Each is queued once per endpoint, even when the call end is reported twice internally. ## URL requirements [#url-requirements] - Use an absolute `https://` URL. Endpoints with `http://` are refused with [`webhook_https_required`](/errors/webhook_https_required). - The host must resolve to a public internet address. Private, loopback and link-local addresses are refused with [`webhook_url_invalid`](/errors/webhook_url_invalid), as are URLs with a username or password. CallMitra checks the address again before each attempt. - A workspace can have up to **20** endpoints. ## Next [#next] # Verify signatures (/webhooks/verify-signatures) Every delivery to a [webhook endpoint](/webhooks/endpoints) is signed with that endpoint's secret. Check the signature before you trust the body. The scheme follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification. ## How the signature works [#how-the-signature-works] Each delivery has three headers: | Header | Example | | --- | --- | | `webhook-id` | `evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b` | | `webhook-timestamp` | `1763184730` (Unix seconds, new on each attempt) | | `webhook-signature` | `v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=` | CallMitra computes the signature like this: 1. **Key:** take your secret (`whsec_MfKQ…`), remove the `whsec_` prefix, and base64-decode the rest. The result is 32 bytes. 2. **Signed content:** the `webhook-id`, a dot, the `webhook-timestamp`, a dot, then the raw request body: `{webhook-id}.{webhook-timestamp}.{body}`. 3. **Signature:** HMAC-SHA256 of the signed content with the key, base64-encoded (standard alphabet, with padding), prefixed with `v1,`. `webhook-signature` can hold more than one signature, separated by spaces. For 24 hours after you [rotate the secret](/webhooks/endpoints#rotate-the-signing-secret), it holds one from the new secret and one from the old secret. Accept the request if **any** `v1` signature matches. ## Steps [#steps] ### Read the raw body [#read-the-raw-body] Use the body bytes exactly as received. Do not parse and re-serialize the JSON first: any change in spacing or key order breaks the signature. ### Check the timestamp [#check-the-timestamp] Reject the request if `webhook-timestamp` is more than **5 minutes** away from your clock. This stops someone replaying a captured request later. ### Compute and compare [#compute-and-compare] Compute the expected signature as above. Compare it with each `v1,` entry in `webhook-signature` using a **constant-time** comparison. If none match, answer `401`. ### Drop duplicates [#drop-duplicates] Skip the event if you already handled its `webhook-id`. Retries and redeliveries reuse it. ## Examples [#examples] Each example reads the secret from `CALLMITRA_WEBHOOK_SECRET`. ```js import crypto from 'node:crypto'; import express from 'express'; const app = express(); const SECRET = process.env.CALLMITRA_WEBHOOK_SECRET; // whsec_... const KEY = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64'); const TOLERANCE_S = 300; function verify(rawBody, headers) { const id = headers['webhook-id']; const ts = headers['webhook-timestamp']; const sigHeader = headers['webhook-signature']; if (!id || !sigHeader || !/^\d+$/.test(ts ?? '')) return false; if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > TOLERANCE_S) return false; const expected = crypto .createHmac('sha256', KEY) .update(`${id}.${ts}.`) .update(rawBody) .digest(); return sigHeader.split(' ').some((entry) => { const [version, sig] = entry.split(','); if (version !== 'v1' || !sig) return false; const received = Buffer.from(sig, 'base64'); return received.length === expected.length && crypto.timingSafeEqual(received, expected); }); } // express.raw keeps the body as a Buffer, so the bytes are unchanged. app.post('/webhooks/callmitra', express.raw({ type: 'application/json' }), (req, res) => { if (!verify(req.body, req.headers)) return res.sendStatus(401); const event = JSON.parse(req.body.toString('utf8')); // Skip event.id if you have already handled it, then queue the work. res.sendStatus(204); }); ``` ```python import base64 import hashlib import hmac import json import os import time from flask import Flask, abort, request app = Flask(__name__) KEY = base64.b64decode(os.environ["CALLMITRA_WEBHOOK_SECRET"].removeprefix("whsec_")) TOLERANCE_S = 300 def verify(raw: bytes, headers) -> bool: msg_id = headers.get("webhook-id", "") ts = headers.get("webhook-timestamp", "") sig_header = headers.get("webhook-signature", "") if not (msg_id and sig_header and ts.isascii() and ts.isdigit()): return False if abs(time.time() - int(ts)) > TOLERANCE_S: return False signed = f"{msg_id}.{ts}.".encode() + raw expected = base64.b64encode(hmac.new(KEY, signed, hashlib.sha256).digest()).decode() for entry in sig_header.split(): version, _, sig = entry.partition(",") if version == "v1" and hmac.compare_digest(sig, expected): return True return False @app.post("/webhooks/callmitra") def callmitra_webhook(): raw = request.get_data() # raw bytes, before any JSON parsing if not verify(raw, request.headers): abort(401) event = json.loads(raw) # Skip event["id"] if you have already handled it, then queue the work. return "", 204 ``` ```php TOLERANCE_S) { return false; } $key = base64_decode(preg_replace('/^whsec_/', '', $secret)); $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$raw", $key, true)); foreach (explode(' ', $sigHeader) as $entry) { [$version, $sig] = array_pad(explode(',', $entry, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $sig)) { return true; } } return false; } $raw = file_get_contents('php://input'); $valid = callmitra_verify( getenv('CALLMITRA_WEBHOOK_SECRET'), $raw, $_SERVER['HTTP_WEBHOOK_ID'] ?? '', $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '' ); if (!$valid) { http_response_code(401); exit; } $event = json_decode($raw, true); // Skip $event['id'] if you have already handled it, then queue the work. http_response_code(204); ``` ```go package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "io" "net/http" "os" "strconv" "strings" "time" ) const toleranceS = 300 var key = mustKey(os.Getenv("CALLMITRA_WEBHOOK_SECRET")) func mustKey(secret string) []byte { k, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_")) if err != nil { panic("CALLMITRA_WEBHOOK_SECRET is not a whsec_ secret") } return k } func verify(raw []byte, h http.Header) bool { id, ts, sigHeader := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature") sent, err := strconv.ParseInt(ts, 10, 64) if id == "" || sigHeader == "" || err != nil { return false } if d := time.Now().Unix() - sent; d > toleranceS || d < -toleranceS { return false } mac := hmac.New(sha256.New, key) mac.Write([]byte(id + "." + ts + ".")) mac.Write(raw) expected := mac.Sum(nil) for _, entry := range strings.Fields(sigHeader) { version, sig, ok := strings.Cut(entry, ",") if !ok || version != "v1" { continue } received, err := base64.StdEncoding.DecodeString(sig) if err == nil && hmac.Equal(received, expected) { return true } } return false } func callmitraWebhook(w http.ResponseWriter, r *http.Request) { raw, err := io.ReadAll(r.Body) if err != nil || !verify(raw, r.Header) { w.WriteHeader(http.StatusUnauthorized) return } // Parse raw as JSON, skip ids you have already handled, then queue the work. w.WriteHeader(http.StatusNoContent) } ``` ## Use a Standard Webhooks library [#use-a-standard-webhooks-library] Because the scheme follows Standard Webhooks, the official libraries verify CallMitra deliveries too. For example, `standardwebhooks` on npm and PyPI. See [github.com/standard-webhooks/standard-webhooks](https://github.com/standard-webhooks/standard-webhooks) for other languages. Pass the whole `whsec_…` secret, the raw body and the request headers. ```python from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["CALLMITRA_WEBHOOK_SECRET"]) event = wh.verify(raw_body, request.headers) # raises if the signature or timestamp is wrong ``` ## Test your receiver [#test-your-receiver] Call [`POST /api/v1/webhook-endpoints/{endpoint_id}/test`](/api-reference/webhooks/sendTestWebhook). It sends a signed `webhook.test` event and returns your server's status code and the first 1 KB of its answer. A `401` there usually means one of the mistakes below. ## Common mistakes [#common-mistakes] - **Verifying parsed JSON.** Frameworks that parse the body first (for example `express.json()`) lose the original bytes. Use the raw body. - **Using the secret as text.** The HMAC key is the base64-decoded part after `whsec_`, not the secret string itself. - **Checking only the first signature.** After a rotation the header has two. Split on spaces and try each one. - **Plain string comparison.** `==` leaks timing information. Use the constant-time helpers shown above. - **Wrong endpoint's secret.** Each endpoint has its own secret. - **Clock drift.** The 5-minute window assumes your server clock is in sync (NTP). ## The `X-Signature-SHA256` header [#the-x-signature-sha256-header] Deliveries to webhook endpoints also carry `X-Signature-SHA256`, so a receiver built for [campaign and agent webhooks](/webhooks/campaign-agent-webhooks) keeps working. Prefer `webhook-signature`: it covers the id and timestamp, and it supports secret rotation. If you do check `X-Signature-SHA256` on an endpoint delivery, see [Verify X-Signature-SHA256](/webhooks/campaign-agent-webhooks#verify-x-signature-sha256) for the key it uses and how to check replays. # List client workspaces (/api-reference/workspace/listAgencyClients) ## GET /api/v1/agency/clients Operation ID: `listAgencyClients` List client workspaces For an agency: every client workspace it manages, oldest first. Send a client's `id` as `X-Workspace-Id` on any other request to run it inside that workspace. Every key of the agency can call this, whatever its resources; the key's user must be a manager. The workspace needs the agency add-on; without it, or from a client workspace, the call gets `permission_denied`. ### Responses #### 200 OK Example (example): ```json { "agency": { "id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01", "name": "Acme Agency" }, "clients": [ { "createdAt": "2026-03-02T09:15:00+00:00", "id": "3f2e1d0c-9b8a-4765-8432-1f0e9d8c7b6a", "name": "Sunrise Dental", "status": "active" } ], "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get usage and balance (/api-reference/workspace/getUsage) ## GET /api/v1/usage Operation ID: `getUsage` Get usage and balance Calls, talk time, billed minutes and wallet charges for a period, plus the current plan period and wallet balance. Defaults to the current billing period (or the last 30 days). `balance` is null when billing is not enabled on the deployment. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `from` | query | no | Start of the period: ISO 8601 date or date-time (UTC if no offset). | | `to` | query | no | End of the period (exclusive); a bare date includes that whole day. Default now. | ### Responses #### 200 OK Example (example): ```json { "balance": { "balanceInrPaise": 150000, "minutesAtCurrentRate": 250, "ratePerMinuteInrPaise": 600 }, "billingEnabled": true, "calls": { "billedMinutes": 402, "completed": 288, "durationSeconds": 21950, "total": 412, "walletChargedInrPaise": 0 }, "period": { "basis": "billing_period", "end": "2026-11-15T12:00:00Z", "start": "2026-11-01T00:00:00Z" }, "plan": { "minutesIncluded": 2000, "minutesRemaining": 1598, "minutesUsed": 402, "name": "Growth", "overageAmountInrPaise": 0, "overageMinutes": 0, "periodEnd": "2026-12-01T00:00:00+00:00", "periodStart": "2026-11-01T00:00:00+00:00", "slug": "growth" }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Check an API key (/api-reference/workspace/getWorkspace) ## GET /api/v1/workspace Operation ID: `getWorkspace` Check an API key Returns the workspace the request runs in, the key that sent it (access, resources, expiry) and its rate limit. Every key can call this, including read-only keys and keys limited to other resources. With `X-Workspace-Id`, an agency key sees the client workspace. ### Responses #### 200 OK Example (example): ```json { "apiKey": { "id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a", "name": "CRM sync", "prefix": "vk_live_Ab3dE6", "scopes": { "access": "read", "resources": [ "calls", "leads" ] } }, "rateLimit": { "limit": 300, "windowSeconds": 60 }, "success": true, "workspace": { "id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01", "name": "Acme Realty" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List agents (/api-reference/agents/listAgents) ## GET /api/v1/agents/ Operation ID: `listAgents` List agents Every agent in the workspace, newest first, with its published `config` and working `draftConfig`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `includeArchived` | query | no | Include archived agents (default true). | ### Responses #### 200 OK Example (example): ```json { "agents": [ { "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "tts": "sarvam", "voice": "priya" }, "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "language": "hi-IN", "name": "Priya", "rosterState": "in_training", "status": "draft", "takingCalls": false, "unpublishedChanges": false } ], "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create an agent (/api-reference/agents/createAgent) ## POST /api/v1/agents/ Operation ID: `createAgent` Create an agent Creates an agent from a `config` (see the AgentConfig schema). It starts as a `draft`; publish it with publishAgent, or send `status: published`. Values outside the documented range or list, and a language, voice or model that is not available, are refused with `parameter_invalid` naming the field (for example `config.voice`). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "A new agent. It starts as a draft unless `status` is `published`.", "properties": { "config": { "additionalProperties": true, "description": "Agent configuration. Omitted keys keep their current (or default) value.\n\nKeys are snake_case by design: this object is the stored agent config and the\nshape importAgent produces, so it is saved and returned exactly as written here,\nwhile the rest of the API uses camelCase. A known key with a bad value is refused\nwith `parameter_invalid` and a `param` path such as `config.tts_volume`. Unknown keys\nare not refused: they are dropped without an error and do not appear in the saved config.", "properties": { "agent_gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voice gender: `female`, `male` or `any`.", "title": "Agent Gender" }, "agent_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Kind of call the agent runs.", "enum": [ "announcement", "awareness", "conversation", "ivr_survey", "survey" ], "title": "Agent Mode" }, "ai_disclosure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Tell the caller they are speaking to an AI agent.", "title": "Ai Disclosure" }, "auto_adapt_language": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Follow the caller when they switch language.", "title": "Auto Adapt Language" }, "background_sound": { "anyOf": [ { "additionalProperties": true, "description": "Room tone mixed quietly under the agent's voice.", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Play the background sound on calls.", "title": "Enabled" }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Background sound slug from `GET /background-sounds`, or `off`.", "title": "Preset" }, "volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Loudness of the background sound.", "maximum": 1, "minimum": 0.02, "title": "Volume" } }, "title": "AgentBackgroundSound", "type": "object" }, { "type": "null" } ], "description": "Background room tone." }, "call_recording": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Record calls.", "title": "Call Recording" }, "call_time_limit_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Hard limit on call length.", "maximum": 3600, "minimum": 10, "title": "Call Time Limit Seconds" }, "caller_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name the agent introduces itself with.", "title": "Caller Name" }, "calling_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`instant` answers new leads right away; `bulk` runs campaigns; empty means not set.", "enum": [ "", "bulk", "instant" ], "title": "Calling Mode" }, "conversation_engine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Turn-taking engine version.", "enum": [ "v1", "v2" ], "title": "Conversation Engine" }, "extra_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second language the agent may switch to, e.g. `hi-IN`.", "title": "Extra Language" }, "greeting_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shortcut for `template_payload.greeting_message` on write.", "title": "Greeting Message" }, "interrupt_min_speech_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Caller speech needed to interrupt (time mode).", "maximum": 2000, "minimum": 100, "title": "Interrupt Min Speech Ms" }, "interrupt_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the caller interrupts the agent: by speaking time or by word count.", "enum": [ "time", "words" ], "title": "Interrupt Mode" }, "interrupt_word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Caller words needed to interrupt (words mode).", "maximum": 3, "minimum": 1, "title": "Interrupt Word Count" }, "interruption_sensitivity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How easily the caller can interrupt.", "enum": [ "low", "medium", "high" ], "title": "Interruption Sensitivity" }, "job_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title the agent plays, e.g. `Sales associate`.", "title": "Job Role" }, "knowledge": { "anyOf": [ { "additionalProperties": true, "description": "Facts and answers the agent can use during the call.", "properties": { "details": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Business details as `{key, label, value}` objects.", "title": "Details" }, "items": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Knowledge items as `{kind, q, text}`; kind is fact, qa, rule or objection.", "title": "Items" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text notes the agent may use.", "title": "Notes" } }, "title": "AgentKnowledgeConfig", "type": "object" }, { "type": "null" } ], "description": "Structured knowledge." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary call language code from `GET /voices` languages, e.g. `en-IN`, `hi-IN`.", "title": "Language" }, "llm_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Language model id, e.g. `gpt-4o-mini`, `gpt-4.1-mini`.", "title": "Llm Model" }, "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Longest reply in tokens.", "maximum": 32000, "minimum": 1, "title": "Max Tokens" }, "noise_reduction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Background noise filtering.", "enum": [ "off", "standard", "strong" ], "title": "Noise Reduction" }, "post_call_webhook": { "anyOf": [ { "additionalProperties": true, "description": "Where the call summary is sent after each call (read; set it with setAgentPostCallWebhook).", "properties": { "trigger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which calls are sent.", "enum": [ "completed", "every", "voicemail" ], "title": "Trigger" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTTPS endpoint that receives the call summary.", "title": "Url" } }, "title": "AgentPostCallWebhookConfig", "type": "object" }, { "type": "null" } ], "description": "Post-call webhook. Prefer setAgentPostCallWebhook, which also stores the signing secret." }, "realtime_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Realtime speech model when `voice_engine` is not pipeline.", "title": "Realtime Model" }, "realtime_voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Realtime voice when `voice_engine` is not pipeline.", "title": "Realtime Voice" }, "reasoning_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reasoning effort for models that support it; lower is faster.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "title": "Reasoning Effort" }, "recording_notice": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Tell the caller the call is recorded.", "title": "Recording Notice" }, "required_fields": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Values to collect on the call, as `{key, label, type}` objects.", "title": "Required Fields" }, "script": { "anyOf": [ { "additionalProperties": true, "description": "Structured call script: opening line, goal, steps and closing.", "properties": { "ask_first_question_in_greeting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Ask the first step's question in the opening line.", "title": "Ask First Question In Greeting" }, "closing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last thing the agent says before hanging up.", "title": "Closing" }, "end_rules": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "When the agent should end the call.", "title": "End Rules" }, "goal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What a successful call achieves.", "title": "Goal" }, "opening": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First thing the agent says when the call connects.", "title": "Opening" }, "steps": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentScriptStep" }, "type": "array" }, { "type": "null" } ], "description": "Ordered steps the agent follows.", "title": "Steps" }, "strictness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How closely the agent sticks to the steps.", "enum": [ "flexible", "balanced", "strict" ], "title": "Strictness" } }, "title": "AgentScriptConfig", "type": "object" }, { "type": "null" } ], "description": "Structured call script." }, "stt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Speech-to-text provider id from the active catalog, for example `deepgram` or `sarvam`. An id that is not active is refused with `parameter_invalid`.", "title": "Stt" }, "success_criteria": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What counts as a successful call, for call analysis.", "title": "Success Criteria" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shortcut for `template_payload.system_prompt` on write.", "title": "System Prompt" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Sampling temperature.", "maximum": 2, "minimum": 0, "title": "Temperature" }, "template_payload": { "anyOf": [ { "additionalProperties": true, "description": "Free-form prompt content: system prompt, greeting and knowledge text.", "properties": { "greeting_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opening line spoken when the call connects.", "title": "Greeting Message" }, "knowledge_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reference text the agent may quote from.", "title": "Knowledge Base" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instructions for the language model.", "title": "System Prompt" } }, "title": "AgentPromptContent", "type": "object" }, { "type": "null" } ], "description": "Free-form prompt content (system prompt, greeting, knowledge text)." }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Speaking style, e.g. `natural`, `friendly`, `formal`.", "title": "Tone" }, "tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentToolConfig" }, "type": "array" }, { "type": "null" } ], "description": "Tools the agent may use (at most 32).", "title": "Tools" }, "tts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text-to-speech provider id from `GET /voices` providers.", "title": "Tts" }, "tts_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Speaking speed; 1.0 is normal.", "maximum": 1.5, "minimum": 0.5, "title": "Tts Speed" }, "tts_volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Voice loudness; 1.0 is full.", "maximum": 1, "minimum": 0.2, "title": "Tts Volume" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voice id (`voiceId`) from `GET /voices` for the `tts` provider.", "title": "Voice" }, "voice_engine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`pipeline` uses separate speech-to-text, model and voice; the others use a single realtime speech model.", "enum": [ "pipeline", "gemini_live", "openai_realtime", "elevenlabs_agents" ], "title": "Voice Engine" } }, "title": "AgentConfig", "type": "object" }, "name": { "default": "", "description": "Display name; also the name the agent introduces itself with.", "maxLength": 255, "title": "Name", "type": "string" }, "sourceTemplateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Template id this agent is based on.", "title": "Sourcetemplateid" }, "sourceTemplateSlug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Template slug this agent is based on.", "title": "Sourcetemplateslug" }, "sourceTemplateVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Template version this agent is based on.", "title": "Sourcetemplateversion" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`draft` (default) or `published`.", "enum": [ "draft", "published" ], "title": "Status" } }, "title": "AgentCreateInput", "type": "object" } ``` Example: ```json { "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "stt": "sarvam", "template_payload": { "greeting_message": "Namaste, main Acme Realty se Priya bol rahi hoon.", "system_prompt": "You are Priya from Acme Realty. Qualify the lead's budget and preferred area." }, "tts": "sarvam", "voice": "priya" }, "name": "Priya" } ``` ### Responses #### 200 OK Example (example): ```json { "agent": { "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "tts": "sarvam", "voice": "priya" }, "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "language": "hi-IN", "name": "Priya", "rosterState": "in_training", "status": "draft", "takingCalls": false, "unpublishedChanges": false }, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 413 Payload too large: `payload_too_large`. Example (The request body is too large.): ```json { "detail": "The request body is too large.", "error": { "code": "payload_too_large", "docUrl": "https://docs.callmitra.ai/errors/payload_too_large", "message": "The request body is too large.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`payload_too_large`](/errors/payload_too_large) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Import an agent from another platform (/api-reference/agents/importAgent) ## POST /api/v1/agents/import Operation ID: `importAgent` Import an agent from another platform Creates a **draft** agent from JSON exported from another platform. Review it, then publish with publishAgent. Fields that have no equivalent, and values that had to be approximated, are listed in `warnings` instead of failing the import. | Our field | Vapi | Retell | Bland | | --- | --- | --- | --- | | name | `name` | `agent_name` | `name` | | system prompt | system entries of `model.messages` | `llm.general_prompt` | `task` (or `prompt`) | | greeting | `firstMessage` | `llm.begin_message` | `first_sentence` | | language model | `model.model` | `llm.model` | `model` (Bland tiers map to the default) | | temperature | `model.temperature` | `llm.model_temperature` | `temperature` | | voice | `voice.provider` + `voice.voiceId` | `voice_id` | `voice` | | transcriber | `transcriber.provider` | - | - | | language | `transcriber.language` | `language` | `language` | | speaking speed | `voice.speed` | `voice_speed` | - | | call time limit | `maxDurationSeconds` | `max_call_duration_ms` | `max_duration` (minutes) | | background sound | `backgroundSound` | `ambient_sound` | `background_track` | | recording | `recordingEnabled` | - | `record` | A voice or language that is not available here is replaced: first by a voice with the same id or name, then by the language's default voice, with a warning. Tools, knowledge bases, webhooks and multi-state flows are not imported. `callmitra` copies another workspace's agent config (signing secrets are not copied). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "An agent exported from another platform.", "properties": { "config": { "additionalProperties": true, "description": "The exported JSON: a Vapi assistant, a Retell agent (with its LLM as `llm`), a Bland call or agent configuration, or a Call Mitra agent from getAgent.", "title": "Config", "type": "object" }, "source": { "description": "Platform the JSON comes from.", "enum": [ "vapi", "retell", "bland", "callmitra" ], "title": "Source", "type": "string" } }, "required": [ "source", "config" ], "title": "AgentImportInput", "type": "object" } ``` Example: ```json { "config": { "firstMessage": "Hi, this is Riley from Acme Realty. Is now a good time?", "model": { "messages": [ { "content": "You qualify home-buyer leads.", "role": "system" } ], "model": "gpt-4o", "provider": "openai" }, "name": "Riley", "transcriber": { "language": "en", "provider": "deepgram" }, "voice": { "provider": "11labs", "voiceId": "burt" } }, "source": "vapi" } ``` ### Responses #### 200 OK Example (example): ```json { "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Riley", "status": "draft" }, "success": true, "warnings": [ { "field": "language", "message": "Language 'en' is not available; using en-IN." }, { "field": "voice", "message": "Voice '11labs/burt' is not available; using sarvam voice 'shubh'." } ] } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 413 Payload too large: `payload_too_large`. Example (The request body is too large.): ```json { "detail": "The request body is too large.", "error": { "code": "payload_too_large", "docUrl": "https://docs.callmitra.ai/errors/payload_too_large", "message": "The request body is too large.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`payload_too_large`](/errors/payload_too_large) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get an agent (/api-reference/agents/getAgent) ## GET /api/v1/agents/{agent_id} Operation ID: `getAgent` Get an agent The agent with its published `config`, working `draftConfig`, status and phone numbers. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "agent": { "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "tts": "sarvam", "voice": "priya" }, "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "language": "hi-IN", "name": "Priya", "rosterState": "in_training", "status": "draft", "takingCalls": false, "unpublishedChanges": false }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Update an agent (/api-reference/agents/updateAgent) ## PATCH /api/v1/agents/{agent_id} Operation ID: `updateAgent` Update an agent Saves the change as the agent's draft; calls keep using the published version until you call publishAgent. Only the `config` keys you send change; a nested object you send (for example `script`) replaces the stored one. Bad values are refused with `parameter_invalid` naming the field. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Request body `application/json` (required) ```json { "description": "Fields to change. The change is saved as a draft; publish it with publishAgent.", "properties": { "config": { "anyOf": [ { "additionalProperties": true, "description": "Agent configuration. Omitted keys keep their current (or default) value.\n\nKeys are snake_case by design: this object is the stored agent config and the\nshape importAgent produces, so it is saved and returned exactly as written here,\nwhile the rest of the API uses camelCase. A known key with a bad value is refused\nwith `parameter_invalid` and a `param` path such as `config.tts_volume`. Unknown keys\nare not refused: they are dropped without an error and do not appear in the saved config.", "properties": { "agent_gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voice gender: `female`, `male` or `any`.", "title": "Agent Gender" }, "agent_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Kind of call the agent runs.", "enum": [ "announcement", "awareness", "conversation", "ivr_survey", "survey" ], "title": "Agent Mode" }, "ai_disclosure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Tell the caller they are speaking to an AI agent.", "title": "Ai Disclosure" }, "auto_adapt_language": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Follow the caller when they switch language.", "title": "Auto Adapt Language" }, "background_sound": { "anyOf": [ { "$ref": "#/components/schemas/AgentBackgroundSound" }, { "type": "null" } ], "description": "Background room tone." }, "call_recording": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Record calls.", "title": "Call Recording" }, "call_time_limit_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Hard limit on call length.", "maximum": 3600, "minimum": 10, "title": "Call Time Limit Seconds" }, "caller_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name the agent introduces itself with.", "title": "Caller Name" }, "calling_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`instant` answers new leads right away; `bulk` runs campaigns; empty means not set.", "enum": [ "", "bulk", "instant" ], "title": "Calling Mode" }, "conversation_engine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Turn-taking engine version.", "enum": [ "v1", "v2" ], "title": "Conversation Engine" }, "extra_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second language the agent may switch to, e.g. `hi-IN`.", "title": "Extra Language" }, "greeting_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shortcut for `template_payload.greeting_message` on write.", "title": "Greeting Message" }, "interrupt_min_speech_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Caller speech needed to interrupt (time mode).", "maximum": 2000, "minimum": 100, "title": "Interrupt Min Speech Ms" }, "interrupt_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the caller interrupts the agent: by speaking time or by word count.", "enum": [ "time", "words" ], "title": "Interrupt Mode" }, "interrupt_word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Caller words needed to interrupt (words mode).", "maximum": 3, "minimum": 1, "title": "Interrupt Word Count" }, "interruption_sensitivity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How easily the caller can interrupt.", "enum": [ "low", "medium", "high" ], "title": "Interruption Sensitivity" }, "job_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title the agent plays, e.g. `Sales associate`.", "title": "Job Role" }, "knowledge": { "anyOf": [ { "$ref": "#/components/schemas/AgentKnowledgeConfig" }, { "type": "null" } ], "description": "Structured knowledge." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary call language code from `GET /voices` languages, e.g. `en-IN`, `hi-IN`.", "title": "Language" }, "llm_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Language model id, e.g. `gpt-4o-mini`, `gpt-4.1-mini`.", "title": "Llm Model" }, "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Longest reply in tokens.", "maximum": 32000, "minimum": 1, "title": "Max Tokens" }, "noise_reduction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Background noise filtering.", "enum": [ "off", "standard", "strong" ], "title": "Noise Reduction" }, "post_call_webhook": { "anyOf": [ { "$ref": "#/components/schemas/AgentPostCallWebhookConfig" }, { "type": "null" } ], "description": "Post-call webhook. Prefer setAgentPostCallWebhook, which also stores the signing secret." }, "realtime_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Realtime speech model when `voice_engine` is not pipeline.", "title": "Realtime Model" }, "realtime_voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Realtime voice when `voice_engine` is not pipeline.", "title": "Realtime Voice" }, "reasoning_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reasoning effort for models that support it; lower is faster.", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "title": "Reasoning Effort" }, "recording_notice": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Tell the caller the call is recorded.", "title": "Recording Notice" }, "required_fields": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Values to collect on the call, as `{key, label, type}` objects.", "title": "Required Fields" }, "script": { "anyOf": [ { "$ref": "#/components/schemas/AgentScriptConfig" }, { "type": "null" } ], "description": "Structured call script." }, "stt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Speech-to-text provider id from the active catalog, for example `deepgram` or `sarvam`. An id that is not active is refused with `parameter_invalid`.", "title": "Stt" }, "success_criteria": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What counts as a successful call, for call analysis.", "title": "Success Criteria" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shortcut for `template_payload.system_prompt` on write.", "title": "System Prompt" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Sampling temperature.", "maximum": 2, "minimum": 0, "title": "Temperature" }, "template_payload": { "anyOf": [ { "$ref": "#/components/schemas/AgentPromptContent" }, { "type": "null" } ], "description": "Free-form prompt content (system prompt, greeting, knowledge text)." }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Speaking style, e.g. `natural`, `friendly`, `formal`.", "title": "Tone" }, "tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentToolConfig" }, "type": "array" }, { "type": "null" } ], "description": "Tools the agent may use (at most 32).", "title": "Tools" }, "tts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text-to-speech provider id from `GET /voices` providers.", "title": "Tts" }, "tts_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Speaking speed; 1.0 is normal.", "maximum": 1.5, "minimum": 0.5, "title": "Tts Speed" }, "tts_volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Voice loudness; 1.0 is full.", "maximum": 1, "minimum": 0.2, "title": "Tts Volume" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voice id (`voiceId`) from `GET /voices` for the `tts` provider.", "title": "Voice" }, "voice_engine": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`pipeline` uses separate speech-to-text, model and voice; the others use a single realtime speech model.", "enum": [ "pipeline", "gemini_live", "openai_realtime", "elevenlabs_agents" ], "title": "Voice Engine" } }, "title": "AgentConfig", "type": "object" }, { "type": "null" } ], "description": "Config keys to change; omitted keys keep their current value. Nested objects are replaced." }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "New display name.", "title": "Name" } }, "title": "AgentUpdateInput", "type": "object" } ``` Example: ```json { "config": { "tts_speed": 1.1, "voice": "anushka" } } ``` ### Responses #### 200 OK Example (example): ```json { "agent": { "config": { "language": "hi-IN", "llm_model": "gpt-4o-mini", "tts": "sarvam", "voice": "priya" }, "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "language": "hi-IN", "name": "Priya", "rosterState": "in_training", "status": "draft", "takingCalls": false, "unpublishedChanges": true }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 413 Payload too large: `payload_too_large`. Example (The request body is too large.): ```json { "detail": "The request body is too large.", "error": { "code": "payload_too_large", "docUrl": "https://docs.callmitra.ai/errors/payload_too_large", "message": "The request body is too large.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 422 Invalid parameters: `agent_state_blocked`, `parameter_invalid`. Example (The agent cannot make this change yet.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "agent_state_blocked", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`payload_too_large`](/errors/payload_too_large) - [`agent_state_blocked`](/errors/agent_state_blocked) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Delete an agent (/api-reference/agents/deleteAgent) ## DELETE /api/v1/agents/{agent_id} Operation ID: `deleteAgent` Delete an agent Deletes the agent permanently. Past calls keep their records. To keep the agent but stop it, use pauseAgent. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "message": "Agent deleted", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Start taking calls (/api-reference/agents/startAgent) ## POST /api/v1/agents/{agent_id}/go-live Operation ID: `startAgent` Start taking calls Switches the agent on (`takingCalls: true`, `rosterState: live`). It needs a phone number assigned to the agent. A waiting draft (or a never-published agent) is published first, with the same checks as publishAgent. When a rule fails (no phone number, archived agent, draft breaks a publish rule) the call is refused with `agent_state_blocked` and a message naming what is missing. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Priya", "rosterState": "live", "status": "published", "takingCalls": true, "unpublishedChanges": false }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `agent_state_blocked`, `parameter_invalid`. Example (The agent cannot make this change yet.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "agent_state_blocked", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`agent_state_blocked`](/errors/agent_state_blocked) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Stop taking calls (/api-reference/agents/pauseAgent) ## POST /api/v1/agents/{agent_id}/pause Operation ID: `pauseAgent` Stop taking calls Switches the agent off (`takingCalls: false`). Its configuration is kept; start it again with startAgent. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Priya", "rosterState": "paused", "status": "published", "takingCalls": false, "unpublishedChanges": false }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Publish the agent's draft (/api-reference/agents/publishAgent) ## POST /api/v1/agents/{agent_id}/publish Operation ID: `publishAgent` Publish the agent's draft Makes the saved draft the version used on calls and clears `unpublishedChanges`. Refused with `agent_state_blocked` when the draft breaks a rule (script too long, voice not available for the language, no usable language-model key, archived agent). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Priya", "rosterState": "paused", "status": "published", "takingCalls": false, "unpublishedChanges": false }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `agent_state_blocked`, `parameter_invalid`. Example (The agent cannot make this change yet.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "agent_state_blocked", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`agent_state_blocked`](/errors/agent_state_blocked) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Place a test call (/api-reference/agents/testCallAgent) ## POST /api/v1/agents/{agent_id}/test-call Operation ID: `testCallAgent` Place a test call Calls `destination` from one of your numbers so you can hear the agent. Not a campaign call and not billed; free plans have a test-call allowance. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Request body `application/json` (required) ```json { "description": "Place a test call from one of your numbers.", "properties": { "destination": { "description": "E.164 or local number to dial.", "minLength": 3, "title": "Destination", "type": "string" }, "dynamicValues": { "additionalProperties": true, "description": "Values for the script's placeholders, e.g. `{\"name\": \"Asha\"}`.", "title": "Dynamicvalues", "type": "object" }, "phoneNumberId": { "description": "Your phone number id to call from.", "minLength": 1, "title": "Phonenumberid", "type": "string" } }, "required": [ "phoneNumberId", "destination" ], "title": "AgentTestCallIn", "type": "object" } ``` Example: ```json { "destination": "+919812345678", "phoneNumberId": "8a1d4c2e-0b7f-4e9a-9c3d-5f6e7a8b9c0d" } ``` ### Responses #### 200 OK Example (example): ```json { "callId": "c2b7e0d4-1f3a-4b5c-8d9e-0a1b2c3d4e5f", "message": "Test call initiated", "phoneNumber": "+919812345678", "success": true } ``` #### 400 Bad request: `agent_test_call_failed`. Example (The test call could not be placed.): ```json { "detail": "The test call could not be placed.", "error": { "code": "agent_test_call_failed", "docUrl": "https://docs.callmitra.ai/errors/agent_test_call_failed", "message": "The test call could not be placed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`, `phone_number_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Phone number not found.): ```json { "detail": "Phone number not found.", "error": { "code": "phone_number_not_found", "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_found", "message": "Phone number not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`agent_test_call_failed`](/errors/agent_test_call_failed) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`phone_number_not_found`](/errors/phone_number_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List tools (/api-reference/agents/listTools) ## GET /api/v1/tools/ Operation ID: `listTools` List tools Actions your agents can take on a call (HTTP requests, functions, tools from connected MCP servers), newest first. Credentials are never returned. ### Responses #### 200 OK Example (example): ```json { "success": true, "tools": [ { "authSecretSet": true, "description": "Book a site visit once the caller picks a date.", "id": "5b6c7d8e-9f01-4a2b-8c3d-4e5f60718293", "isActive": true, "kind": "api_request", "method": "POST", "name": "book_site_visit", "url": "https://example.com/api/visits" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a tool (/api-reference/agents/getTool) ## GET /api/v1/tools/{tool_id} Operation ID: `getTool` Get a tool One tool by id. Credentials are never returned (`authSecretSet` says whether one is stored). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `tool_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "success": true, "tool": { "authSecretSet": true, "description": "Book a site visit once the caller picks a date.", "id": "5b6c7d8e-9f01-4a2b-8c3d-4e5f60718293", "isActive": true, "kind": "api_request", "method": "POST", "name": "book_site_visit", "url": "https://example.com/api/visits" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `tool_not_found`. Example (Tool not found.): ```json { "detail": "Tool not found.", "error": { "code": "tool_not_found", "docUrl": "https://docs.callmitra.ai/errors/tool_not_found", "message": "Tool not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`tool_not_found`](/errors/tool_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List voices (/api-reference/agents/listVoices) ## GET /api/v1/voices/ Operation ID: `listVoices` List voices Voices you can put on an agent, with the providers and languages they belong to. Set `config.tts` to a voice's `provider` and `config.voice` to its `voiceId`. Filters narrow `voices` only; `providers` and `languages` always list the full catalog. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `provider` | query | no | Only voices from this provider, for example `sarvam`. | | `language` | query | no | Only voices that speak this language code, for example `hi-IN`. | ### Responses #### 200 OK Example (example): ```json { "languages": [ { "id": "hi-IN", "name": "Hindi" } ], "providers": [ { "count": 12, "id": "sarvam", "name": "Sarvam", "previewSupported": true } ], "success": true, "voices": [ { "gender": "female", "languageCodes": [ "hi-IN", "en-IN" ], "name": "Anushka", "previewSupported": true, "provider": "sarvam", "providerName": "Sarvam", "sortOrder": 1, "voiceId": "anushka" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Set an agent's post-call webhook (/api-reference/webhooks/setAgentPostCallWebhook) ## PUT /api/v1/agents/{agent_id}/post-call-webhook Operation ID: `setAgentPostCallWebhook` Set an agent's post-call webhook After each of this agent's calls, a summary is POSTed to `url` (used when the campaign has no webhook of its own). `trigger` picks which calls are sent: `every`, `completed` or `voicemail`. Send an empty `url` to turn it off. Omit `secret` to keep the stored one; the secret is never returned (`hasSecret` says whether one is set). The change applies to the live agent at once. A URL that does not point at a public internet address is refused with `agent_state_blocked`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `agent_id` | path | yes | | ### Request body `application/json` (required) ```json { "description": "Where to send each call's summary for this agent.", "properties": { "secret": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Signing secret. Omit to keep the current one.", "title": "Secret" }, "trigger": { "default": "every", "description": "Which calls are sent: every call, completed calls only, or voicemails only.", "enum": [ "every", "completed", "voicemail" ], "title": "Trigger", "type": "string" }, "url": { "default": "", "description": "HTTPS URL. Empty removes the webhook.", "maxLength": 2000, "title": "Url", "type": "string" } }, "title": "PostCallWebhookInput", "type": "object" } ``` Example: ```json { "secret": "whsec_example", "trigger": "completed", "url": "https://example.com/hooks/calls" } ``` ### Responses #### 200 OK Example (example): ```json { "agent": { "id": "3f0c2a9e-6a51-4c6e-9a3e-2d1b7c4e8f10", "name": "Priya", "status": "published" }, "success": true, "webhook": { "hasSecret": true, "trigger": "completed", "url": "https://example.com/hooks/calls" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `agent_state_blocked`, `parameter_invalid`. Example (The agent cannot make this change yet.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "agent_state_blocked", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`agent_state_blocked`](/errors/agent_state_blocked) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List webhook deliveries (/api-reference/webhooks/listWebhookDeliveries) ## GET /api/v1/webhook-deliveries/ Operation ID: `listWebhookDeliveries` List webhook deliveries Newest first. Deliveries are kept for 30 days. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpointId` | query | no | Only deliveries to this endpoint. | | `eventType` | query | no | Only this event type, for example `call.completed`. | | `status` | query | no | `pending`, `processing`, `delivered` or `failed`. | | `cursor` | query | no | `nextCursor` from the previous page. | | `limit` | query | no | Deliveries per page (1-100). | ### Responses #### 200 OK Example (example): ```json { "hasMore": true, "nextCursor": "MjAyNi0xMS0xNVQxMDo0MTo0Ny4xMDYwMDArMDA6MDB8YjJlN2QxYzQ", "success": true, "webhookDeliveries": [ { "attempts": 1, "createdAt": "2026-11-15T10:41:47.106000+00:00", "deliveredAt": "2026-11-15T10:42:07.512000+00:00", "endpointId": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "eventId": "evt_6f1c9e2ab4d84f0e9c3a7b51d2e8f604", "eventType": "call.completed", "id": "b2e7d1c4-9f3a-4e58-8c06-1a7d5e2f9b43", "lastAttemptAt": "2026-11-15T10:42:07.512000+00:00", "lastError": "", "lastStatusCode": 200, "latencyMs": 184, "responseSnippet": "ok", "status": "delivered" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a webhook delivery (/api-reference/webhooks/getWebhookDelivery) ## GET /api/v1/webhook-deliveries/{delivery_id} Operation ID: `getWebhookDelivery` Get a webhook delivery Includes the exact event `payload` that was signed and sent. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `delivery_id` | path | yes | Webhook delivery id. | ### Responses #### 200 OK Example (example): ```json { "success": true, "webhookDelivery": { "attempts": 1, "createdAt": "2026-11-15T10:41:47.106000+00:00", "deliveredAt": "2026-11-15T10:42:07.512000+00:00", "endpointId": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "eventId": "evt_6f1c9e2ab4d84f0e9c3a7b51d2e8f604", "eventType": "call.completed", "id": "b2e7d1c4-9f3a-4e58-8c06-1a7d5e2f9b43", "lastAttemptAt": "2026-11-15T10:42:07.512000+00:00", "lastError": "", "lastStatusCode": 200, "latencyMs": 184, "payload": { "apiVersion": "v1", "createdAt": "2026-11-15T10:41:47.106000Z", "data": { "agentId": "3a8f6d2c-1b7e-4c95-a0d4-5e9b2f7c1a68", "callId": "9c1e5b7a-2d4f-4a86-b3e0-7f6a1c8d2e95", "campaignId": "7d2b9f4e-5a1c-4e83-b6f0-3c8e2a9d1f57", "direction": "outbound", "duration": 143, "endedReason": "customer-ended-call", "leadId": "1f6e3a9c-8b2d-4d75-a4c1-9e7b5f2a3d86", "outcome": "interested", "phone": "+919876543210", "sentiment": "positive", "status": "completed", "summary": "Customer agreed to a demo on Friday at 4 pm." }, "id": "evt_6f1c9e2ab4d84f0e9c3a7b51d2e8f604", "type": "call.completed" }, "responseSnippet": "ok", "status": "delivered" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_delivery_not_found`. Example (Webhook delivery not found.): ```json { "detail": "Webhook delivery not found.", "error": { "code": "webhook_delivery_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_delivery_not_found", "message": "Webhook delivery not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_delivery_not_found`](/errors/webhook_delivery_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Redeliver an event (/api-reference/webhooks/redeliverWebhook) ## POST /api/v1/webhook-deliveries/{delivery_id}/redeliver Operation ID: `redeliverWebhook` Redeliver an event Queues the same event (same `id` and `webhook-id`) to the same endpoint again, due now. Returns the new delivery. Tests and redeliveries share a cap of 10 per endpoint per minute (429 with `Retry-After`). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `delivery_id` | path | yes | Webhook delivery id. | ### Responses #### 200 OK Example (example): ```json { "success": true, "webhookDelivery": { "attempts": 0, "createdAt": "2026-11-15T11:02:00+00:00", "endpointId": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "eventId": "evt_6f1c9e2ab4d84f0e9c3a7b51d2e8f604", "eventType": "call.completed", "id": "e5a8c3f2-6d1b-4b97-9e40-2c7f8a1d6b35", "lastError": "", "nextAttemptAt": "2026-11-15T11:02:00+00:00", "payload": { "apiVersion": "v1", "createdAt": "2026-11-15T10:41:47.106000Z", "data": { "agentId": "3a8f6d2c-1b7e-4c95-a0d4-5e9b2f7c1a68", "callId": "9c1e5b7a-2d4f-4a86-b3e0-7f6a1c8d2e95", "campaignId": "7d2b9f4e-5a1c-4e83-b6f0-3c8e2a9d1f57", "direction": "outbound", "duration": 143, "endedReason": "customer-ended-call", "leadId": "1f6e3a9c-8b2d-4d75-a4c1-9e7b5f2a3d86", "outcome": "interested", "phone": "+919876543210", "sentiment": "positive", "status": "completed", "summary": "Customer agreed to a demo on Friday at 4 pm." }, "id": "evt_6f1c9e2ab4d84f0e9c3a7b51d2e8f604", "type": "call.completed" }, "responseSnippet": "", "status": "pending" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_delivery_not_found`. Example (Webhook delivery not found.): ```json { "detail": "Webhook delivery not found.", "error": { "code": "webhook_delivery_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_delivery_not_found", "message": "Webhook delivery not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `webhook_endpoint_disabled`. Example (The webhook endpoint is disabled.): ```json { "detail": "The webhook endpoint is disabled.", "error": { "code": "webhook_endpoint_disabled", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_disabled", "message": "The webhook endpoint is disabled.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_delivery_not_found`](/errors/webhook_delivery_not_found) - [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List webhook endpoints (/api-reference/webhooks/listWebhookEndpoints) ## GET /api/v1/webhook-endpoints/ Operation ID: `listWebhookEndpoints` List webhook endpoints ### Responses #### 200 OK Example (example): ```json { "hasMore": false, "success": true, "webhookEndpoints": [ { "consecutiveFailures": 0, "createdAt": "2026-11-01T08:15:00+00:00", "description": "CRM sync", "enabled": true, "events": [ "call.completed", "call.escalated", "lead.created" ], "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "lastStatus": "HTTP 200", "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00", "updatedAt": "2026-11-15T10:42:07.512000+00:00", "url": "https://example.com/hooks/call-mitra" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create a webhook endpoint (/api-reference/webhooks/createWebhookEndpoint) ## POST /api/v1/webhook-endpoints/ Operation ID: `createWebhookEndpoint` Create a webhook endpoint Registers a URL that receives the event types in `events` (empty means all). The response carries the signing `secret` (`whsec_...`) once; store it to verify deliveries. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. A concurrent duplicate gets `409 idempotency_request_in_progress`. The success body holds a secret, so it is never stored: retrying a completed request with the same key returns `409 idempotency_key_reused` instead of acting twice. | ### Request body `application/json` (required) ```json { "properties": { "description": { "default": "", "description": "Label shown in the console.", "maxLength": 500, "title": "Description", "type": "string" }, "enabled": { "default": true, "description": "Set false to create the endpoint without sending to it yet.", "title": "Enabled", "type": "boolean" }, "events": { "description": "Event types to receive (see `GET /webhook-event-types`). Empty means every event type.", "items": { "type": "string" }, "maxItems": 50, "title": "Events", "type": "array" }, "url": { "description": "Public `https://` URL that receives events.", "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookEndpointCreate", "type": "object" } ``` Example: ```json { "description": "CRM sync", "events": [ "call.completed", "call.escalated", "lead.created" ], "url": "https://example.com/hooks/call-mitra" } ``` ### Responses #### 200 OK Example (example): ```json { "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw", "success": true, "webhookEndpoint": { "consecutiveFailures": 0, "createdAt": "2026-11-01T08:15:00+00:00", "description": "CRM sync", "enabled": true, "events": [ "call.completed", "call.escalated", "lead.created" ], "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "lastStatus": "HTTP 200", "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00", "updatedAt": "2026-11-15T10:42:07.512000+00:00", "url": "https://example.com/hooks/call-mitra" } } ``` #### 400 Bad request: `bad_request`, `webhook_event_type_unknown`, `webhook_https_required`, `webhook_url_invalid`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more event types are not recognised.): ```json { "detail": "One or more event types are not recognised.", "error": { "code": "webhook_event_type_unknown", "docUrl": "https://docs.callmitra.ai/errors/webhook_event_type_unknown", "message": "One or more event types are not recognised.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The webhook URL must use https.): ```json { "detail": "The webhook URL must use https.", "error": { "code": "webhook_https_required", "docUrl": "https://docs.callmitra.ai/errors/webhook_https_required", "message": "The webhook URL must use https.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The webhook URL is not a valid public URL.): ```json { "detail": "The webhook URL is not a valid public URL.", "error": { "code": "webhook_url_invalid", "docUrl": "https://docs.callmitra.ai/errors/webhook_url_invalid", "message": "The webhook URL is not a valid public URL.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `webhook_workspace_required`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (Webhooks are managed inside a workspace.): ```json { "detail": "Webhooks are managed inside a workspace.", "error": { "code": "webhook_workspace_required", "docUrl": "https://docs.callmitra.ai/errors/webhook_workspace_required", "message": "Webhooks are managed inside a workspace.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `webhook_endpoint_limit_reached`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (This workspace already has the maximum number of webhook endpoints.): ```json { "detail": "This workspace already has the maximum number of webhook endpoints.", "error": { "code": "webhook_endpoint_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_limit_reached", "message": "This workspace already has the maximum number of webhook endpoints.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`webhook_event_type_unknown`](/errors/webhook_event_type_unknown) - [`webhook_https_required`](/errors/webhook_https_required) - [`webhook_url_invalid`](/errors/webhook_url_invalid) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_workspace_required`](/errors/webhook_workspace_required) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`webhook_endpoint_limit_reached`](/errors/webhook_endpoint_limit_reached) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a webhook endpoint (/api-reference/webhooks/getWebhookEndpoint) ## GET /api/v1/webhook-endpoints/{endpoint_id} Operation ID: `getWebhookEndpoint` Get a webhook endpoint ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpoint_id` | path | yes | Webhook endpoint id. | ### Responses #### 200 OK Example (example): ```json { "success": true, "webhookEndpoint": { "consecutiveFailures": 0, "createdAt": "2026-11-01T08:15:00+00:00", "description": "CRM sync", "enabled": true, "events": [ "call.completed", "call.escalated", "lead.created" ], "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "lastStatus": "HTTP 200", "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00", "updatedAt": "2026-11-15T10:42:07.512000+00:00", "url": "https://example.com/hooks/call-mitra" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Update a webhook endpoint (/api-reference/webhooks/updateWebhookEndpoint) ## PATCH /api/v1/webhook-endpoints/{endpoint_id} Operation ID: `updateWebhookEndpoint` Update a webhook endpoint Changes only the fields you send. Re-enabling a disabled endpoint clears its failure count. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpoint_id` | path | yes | Webhook endpoint id. | ### Request body `application/json` (required) ```json { "properties": { "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "New label.", "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Enable or pause deliveries. Enabling clears the failure count and disabled reason.", "title": "Enabled" }, "events": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "Replaces the event filter. Empty means every event type.", "title": "Events" }, "url": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "New endpoint URL.", "title": "Url" } }, "title": "WebhookEndpointUpdate", "type": "object" } ``` Example: ```json { "enabled": true, "events": [] } ``` ### Responses #### 200 OK Example (example): ```json { "success": true, "webhookEndpoint": { "consecutiveFailures": 0, "createdAt": "2026-11-01T08:15:00+00:00", "description": "CRM sync", "enabled": true, "events": [], "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "lastStatus": "HTTP 200", "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00", "updatedAt": "2026-11-15T10:42:07.512000+00:00", "url": "https://example.com/hooks/call-mitra" } } ``` #### 400 Bad request: `webhook_event_type_unknown`, `webhook_https_required`, `webhook_url_invalid`. Example (One or more event types are not recognised.): ```json { "detail": "One or more event types are not recognised.", "error": { "code": "webhook_event_type_unknown", "docUrl": "https://docs.callmitra.ai/errors/webhook_event_type_unknown", "message": "One or more event types are not recognised.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The webhook URL must use https.): ```json { "detail": "The webhook URL must use https.", "error": { "code": "webhook_https_required", "docUrl": "https://docs.callmitra.ai/errors/webhook_https_required", "message": "The webhook URL must use https.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The webhook URL is not a valid public URL.): ```json { "detail": "The webhook URL is not a valid public URL.", "error": { "code": "webhook_url_invalid", "docUrl": "https://docs.callmitra.ai/errors/webhook_url_invalid", "message": "The webhook URL is not a valid public URL.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`webhook_event_type_unknown`](/errors/webhook_event_type_unknown) - [`webhook_https_required`](/errors/webhook_https_required) - [`webhook_url_invalid`](/errors/webhook_url_invalid) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Delete a webhook endpoint (/api-reference/webhooks/deleteWebhookEndpoint) ## DELETE /api/v1/webhook-endpoints/{endpoint_id} Operation ID: `deleteWebhookEndpoint` Delete a webhook endpoint Stops deliveries at once and deletes the endpoint's delivery history. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpoint_id` | path | yes | Webhook endpoint id. | ### Responses #### 200 OK Example (example): ```json { "deleted": true, "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Rotate an endpoint's signing secret (/api-reference/webhooks/rotateWebhookEndpointSecret) ## POST /api/v1/webhook-endpoints/{endpoint_id}/rotate-secret Operation ID: `rotateWebhookEndpointSecret` Rotate an endpoint's signing secret Returns a new `secret` once. For the next 24 hours deliveries carry signatures from both the new and the old secret in `webhook-signature`, so you can switch without dropping events. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpoint_id` | path | yes | Webhook endpoint id. | ### Responses #### 200 OK Example (example): ```json { "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD", "success": true, "webhookEndpoint": { "consecutiveFailures": 0, "createdAt": "2026-11-01T08:15:00+00:00", "description": "CRM sync", "enabled": true, "events": [ "call.completed", "call.escalated", "lead.created" ], "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "lastStatus": "HTTP 200", "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00", "previousSecretExpiresAt": "2026-11-16T10:50:00+00:00", "updatedAt": "2026-11-15T10:42:07.512000+00:00", "url": "https://example.com/hooks/call-mitra" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Send a test event (/api-reference/webhooks/sendTestWebhook) ## POST /api/v1/webhook-endpoints/{endpoint_id}/test Operation ID: `sendTestWebhook` Send a test event Sends a signed `webhook.test` event to the endpoint now, whatever its event filter, and returns the delivery with the endpoint's answer. A failed test is retried like any other delivery. Tests and redeliveries share a cap of 10 per endpoint per minute (429 with `Retry-After`). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `endpoint_id` | path | yes | Webhook endpoint id. | ### Responses #### 200 OK Example (example): ```json { "success": true, "webhookDelivery": { "attempts": 1, "createdAt": "2026-11-15T10:41:47.106000+00:00", "deliveredAt": "2026-11-15T10:42:07.512000+00:00", "endpointId": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "eventId": "evt_0a7e3d91c5b24f6c8e1d2b9a4f7c6e53", "eventType": "webhook.test", "id": "0d9a4e61-3c7b-4f2a-b815-6e2c9d7f0a38", "lastAttemptAt": "2026-11-15T10:42:07.512000+00:00", "lastError": "", "lastStatusCode": 200, "latencyMs": 184, "payload": { "apiVersion": "v1", "createdAt": "2026-11-15T10:45:00.000000Z", "data": { "endpointId": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07", "message": "This is a test event from Call Mitra." }, "id": "evt_0a7e3d91c5b24f6c8e1d2b9a4f7c6e53", "type": "webhook.test" }, "responseSnippet": "ok", "status": "delivered" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `webhook_workspace_required`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (Webhooks are managed inside a workspace.): ```json { "detail": "Webhooks are managed inside a workspace.", "error": { "code": "webhook_workspace_required", "docUrl": "https://docs.callmitra.ai/errors/webhook_workspace_required", "message": "Webhooks are managed inside a workspace.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `webhook_endpoint_not_found`. Example (Webhook endpoint not found.): ```json { "detail": "Webhook endpoint not found.", "error": { "code": "webhook_endpoint_not_found", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_not_found", "message": "Webhook endpoint not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `webhook_endpoint_disabled`. Example (The webhook endpoint is disabled.): ```json { "detail": "The webhook endpoint is disabled.", "error": { "code": "webhook_endpoint_disabled", "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_disabled", "message": "The webhook endpoint is disabled.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`webhook_workspace_required`](/errors/webhook_workspace_required) - [`webhook_endpoint_not_found`](/errors/webhook_endpoint_not_found) - [`webhook_endpoint_disabled`](/errors/webhook_endpoint_disabled) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List event types (/api-reference/webhooks/listWebhookEventTypes) ## GET /api/v1/webhook-event-types/ Operation ID: `listWebhookEventTypes` List event types ### Responses #### 200 OK Example (example): ```json { "eventTypes": [ { "description": "A call ended (any final status). Sent after post-call analysis.", "type": "call.completed" }, { "description": "A lead was created in the console, through the API or by a lead source.", "type": "lead.created" } ], "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # call.completed: a call finished (/api-reference/webhooks/onCallCompleted) ## Webhook callCompleted Operation ID: `onCallCompleted` call.completed: a call finished Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callAnalysis": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "callId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "crmPayload": { "anyOf": [ { "additionalProperties": true, "description": "Everything the call stored for your CRM, including callAnalysis and transfer details.", "properties": {}, "type": "object" }, { "type": "null" } ] }, "customerNumber": { "anyOf": [ { "description": "The number dialled or the caller's number.", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "outbound", "inbound" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Seconds.", "type": "number" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "endedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extractedFields": { "additionalProperties": true, "type": "object" }, "lead": { "anyOf": [ { "properties": { "company": { "type": "string" }, "customFields": { "additionalProperties": true, "description": "Custom field values (text, numbers, booleans or lists). Sensitive and archived fields are left out.", "properties": {}, "type": "object" }, "email": { "type": "string" }, "externalId": { "anyOf": [ { "description": "Your ID for this lead, when you sent one.", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id" ], "type": "object" }, { "type": "null" } ] }, "leadId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchantOutcome": { "description": "Outcome of the lead's or call's latest result.", "enum": [ "qualified", "interested", "callback", "not_interested", "no_response", "no_answer", "busy", "call_failed", "voicemail", "" ], "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcomeCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "description": "The lead's phone, or the number dialled when there is no lead.", "type": "string" }, { "type": "null" } ] }, "providerCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recommendedLeadStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recordingUrl": { "anyOf": [ { "description": "Fetch with your `X-API-Key`.", "format": "uri", "type": "string" }, { "type": "null" } ] }, "sentiment": { "anyOf": [ { "enum": [ "positive", "neutral", "negative" ], "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "description": "Final call status, for example `completed`, `no_answer`, `busy` or `failed`.", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "callId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "call.completed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # call.escalated: a call was transferred to a person (/api-reference/webhooks/onCallEscalated) ## Webhook callEscalated Operation ID: `onCallEscalated` call.escalated: a call was transferred to a person Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "customerNumber": { "anyOf": [ { "description": "The number dialled or the caller's number.", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "outbound", "inbound" ], "type": "string" }, "endedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lead": { "anyOf": [ { "properties": { "company": { "type": "string" }, "customFields": { "additionalProperties": true, "description": "Custom field values (text, numbers, booleans or lists). Sensitive and archived fields are left out.", "properties": {}, "type": "object" }, "email": { "type": "string" }, "externalId": { "anyOf": [ { "description": "Your ID for this lead, when you sent one.", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id" ], "type": "object" }, { "type": "null" } ] }, "leadId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "description": "The lead's phone, or the number dialled when there is no lead.", "type": "string" }, { "type": "null" } ] }, "providerCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transferDialStatus": { "anyOf": [ { "description": "The carrier's answer for the transfer leg, when known.", "type": "string" }, { "type": "null" } ] }, "transferReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transferStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transferTarget": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transferType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "callId" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "call.escalated", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # call.failed: a call ended without connecting (/api-reference/webhooks/onCallFailed) ## Webhook callFailed Operation ID: `onCallFailed` call.failed: a call ended without connecting Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callAnalysis": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "callId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "crmPayload": { "anyOf": [ { "additionalProperties": true, "description": "Everything the call stored for your CRM, including callAnalysis and transfer details.", "properties": {}, "type": "object" }, { "type": "null" } ] }, "customerNumber": { "anyOf": [ { "description": "The number dialled or the caller's number.", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "outbound", "inbound" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Seconds.", "type": "number" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "endedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extractedFields": { "additionalProperties": true, "type": "object" }, "lead": { "anyOf": [ { "properties": { "company": { "type": "string" }, "customFields": { "additionalProperties": true, "description": "Custom field values (text, numbers, booleans or lists). Sensitive and archived fields are left out.", "properties": {}, "type": "object" }, "email": { "type": "string" }, "externalId": { "anyOf": [ { "description": "Your ID for this lead, when you sent one.", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id" ], "type": "object" }, { "type": "null" } ] }, "leadId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchantOutcome": { "description": "Outcome of the lead's or call's latest result.", "enum": [ "qualified", "interested", "callback", "not_interested", "no_response", "no_answer", "busy", "call_failed", "voicemail", "" ], "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcomeCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "description": "The lead's phone, or the number dialled when there is no lead.", "type": "string" }, { "type": "null" } ] }, "providerCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recommendedLeadStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recordingUrl": { "anyOf": [ { "description": "Fetch with your `X-API-Key`.", "format": "uri", "type": "string" }, { "type": "null" } ] }, "sentiment": { "anyOf": [ { "enum": [ "positive", "neutral", "negative" ], "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "description": "Final call status, for example `completed`, `no_answer`, `busy` or `failed`.", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "callId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "call.failed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # callback.completed: a booked callback was made (/api-reference/webhooks/onCallbackCompleted) ## Webhook callbackCompleted Operation ID: `onCallbackCompleted` callback.completed: a booked callback was made Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attempts": { "type": "integer" }, "callbackId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "dialAt": { "description": "The callback time, ISO 8601.", "format": "date-time", "type": "string" }, "kind": { "type": "string" }, "leadId": { "format": "uuid", "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "when": { "description": "The callback time in the lead's time zone, readable.", "type": "string" } }, "required": [ "callbackId", "leadId", "dialAt" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "callback.completed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # callback.failed: a booked callback did not reach the lead (/api-reference/webhooks/onCallbackFailed) ## Webhook callbackFailed Operation ID: `onCallbackFailed` callback.failed: a booked callback did not reach the lead Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attempts": { "type": "integer" }, "callbackId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "dialAt": { "description": "The callback time, ISO 8601.", "format": "date-time", "type": "string" }, "kind": { "type": "string" }, "leadId": { "format": "uuid", "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "when": { "description": "The callback time in the lead's time zone, readable.", "type": "string" } }, "required": [ "callbackId", "leadId", "dialAt" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "callback.failed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # callback.scheduled: a callback was booked (/api-reference/webhooks/onCallbackScheduled) ## Webhook callbackScheduled Operation ID: `onCallbackScheduled` callback.scheduled: a callback was booked Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attempts": { "type": "integer" }, "callbackId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "dialAt": { "description": "The callback time, ISO 8601.", "format": "date-time", "type": "string" }, "kind": { "type": "string" }, "leadId": { "format": "uuid", "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "when": { "description": "The callback time in the lead's time zone, readable.", "type": "string" } }, "required": [ "callbackId", "leadId", "dialAt" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "callback.scheduled", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # campaign.completed: a campaign dialled every lead (/api-reference/webhooks/onCampaignCompleted) ## Webhook campaignCompleted Operation ID: `onCampaignCompleted` campaign.completed: a campaign dialled every lead Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "campaignId": { "format": "uuid", "type": "string" }, "completedAt": { "anyOf": [ { "description": "Only on campaign.completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "outbound", "inbound" ], "type": "string" }, "name": { "type": "string" }, "startedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "campaignId" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "campaign.completed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # campaign.started: a campaign was started (/api-reference/webhooks/onCampaignStarted) ## Webhook campaignStarted Operation ID: `onCampaignStarted` campaign.started: a campaign was started Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "campaignId": { "format": "uuid", "type": "string" }, "completedAt": { "anyOf": [ { "description": "Only on campaign.completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "outbound", "inbound" ], "type": "string" }, "name": { "type": "string" }, "startedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "campaignId" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "campaign.started", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # lead.created: a lead was created (/api-reference/webhooks/onLeadCreated) ## Webhook leadCreated Operation ID: `onLeadCreated` lead.created: a lead was created Sent to webhook endpoints subscribed to this event (or to every event). Sent for leads added one at a time: `createLead`, the console's add-lead form, and each lead a connected lead source delivers (Meta lead ads, Google Ads lead forms, lead-source webhooks). It is not sent for spreadsheet imports, campaign lead uploads or campaigns created with leads, nor for leads made automatically for WhatsApp contacts, unknown inbound callers, outbound calls to a new number or do-not-call entries. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "type": "string" }, "createdAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "customFields": { "additionalProperties": true, "description": "Custom field values (text, numbers, booleans or lists). Sensitive and archived fields are left out.", "properties": {}, "type": "object" }, "email": { "type": "string" }, "externalId": { "anyOf": [ { "description": "Your ID for this lead, when you sent one.", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "leadSourceId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "lead.created", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # lead.updated: a lead was edited (/api-reference/webhooks/onLeadUpdated) ## Webhook leadUpdated Operation ID: `onLeadUpdated` lead.updated: a lead was edited Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "type": "string" }, "createdAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "customFields": { "additionalProperties": true, "description": "Custom field values (text, numbers, booleans or lists). Sensitive and archived fields are left out.", "properties": {}, "type": "object" }, "email": { "type": "string" }, "externalId": { "anyOf": [ { "description": "Your ID for this lead, when you sent one.", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "leadSourceId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "lead.updated", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # ticket.created: a support ticket was opened (/api-reference/webhooks/onTicketCreated) ## Webhook ticketCreated Operation ID: `onTicketCreated` ticket.created: a support ticket was opened Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "description": "`category`, `team`, `tags` and `mergedInto` appear only when the ticket has them. Some changes add extra keys describing the change.", "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "userId": { "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "closedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "leadId": { "format": "uuid", "type": "string" }, "merchantId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mergedInto": { "properties": { "id": { "format": "uuid", "type": "string" }, "ref": { "type": "string" } }, "type": "object" }, "previousStatus": { "description": "Only on ticket.reopened.", "type": "string" }, "priority": { "type": "string" }, "reopenedBy": { "description": "Only on ticket.reopened.", "type": "string" }, "resolvedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "sourceCallId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "team": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ticketId": { "format": "uuid", "type": "string" }, "ticketRef": { "description": "Short reference shown to the customer.", "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ticketId", "leadId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "ticket.created", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # ticket.rated: a customer rated a support ticket (/api-reference/webhooks/onTicketRated) ## Webhook ticketRated Operation ID: `onTicketRated` ticket.rated: a customer rated a support ticket Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "description": "`category`, `team`, `tags` and `mergedInto` appear only when the ticket has them. Some changes add extra keys describing the change.", "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "userId": { "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "closedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "leadId": { "format": "uuid", "type": "string" }, "merchantId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mergedInto": { "properties": { "id": { "format": "uuid", "type": "string" }, "ref": { "type": "string" } }, "type": "object" }, "previousStatus": { "description": "Only on ticket.reopened.", "type": "string" }, "priority": { "type": "string" }, "reopenedBy": { "description": "Only on ticket.reopened.", "type": "string" }, "resolvedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "sourceCallId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "team": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ticketId": { "format": "uuid", "type": "string" }, "ticketRef": { "description": "Short reference shown to the customer.", "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ticketId", "leadId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "ticket.rated", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # ticket.reopened: a support ticket opened again (/api-reference/webhooks/onTicketReopened) ## Webhook ticketReopened Operation ID: `onTicketReopened` ticket.reopened: a support ticket opened again Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "description": "`category`, `team`, `tags` and `mergedInto` appear only when the ticket has them. Some changes add extra keys describing the change.", "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "userId": { "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "closedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "leadId": { "format": "uuid", "type": "string" }, "merchantId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mergedInto": { "properties": { "id": { "format": "uuid", "type": "string" }, "ref": { "type": "string" } }, "type": "object" }, "previousStatus": { "description": "Only on ticket.reopened.", "type": "string" }, "priority": { "type": "string" }, "reopenedBy": { "description": "Only on ticket.reopened.", "type": "string" }, "resolvedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "sourceCallId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "team": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ticketId": { "format": "uuid", "type": "string" }, "ticketRef": { "description": "Short reference shown to the customer.", "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ticketId", "leadId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "ticket.reopened", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # ticket.resolved: a support ticket was resolved (/api-reference/webhooks/onTicketResolved) ## Webhook ticketResolved Operation ID: `onTicketResolved` ticket.resolved: a support ticket was resolved Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "description": "`category`, `team`, `tags` and `mergedInto` appear only when the ticket has them. Some changes add extra keys describing the change.", "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "userId": { "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "closedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "leadId": { "format": "uuid", "type": "string" }, "merchantId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mergedInto": { "properties": { "id": { "format": "uuid", "type": "string" }, "ref": { "type": "string" } }, "type": "object" }, "previousStatus": { "description": "Only on ticket.reopened.", "type": "string" }, "priority": { "type": "string" }, "reopenedBy": { "description": "Only on ticket.reopened.", "type": "string" }, "resolvedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "sourceCallId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "team": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ticketId": { "format": "uuid", "type": "string" }, "ticketRef": { "description": "Short reference shown to the customer.", "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ticketId", "leadId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "ticket.resolved", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # ticket.updated: a support ticket changed (/api-reference/webhooks/onTicketUpdated) ## Webhook ticketUpdated Operation ID: `onTicketUpdated` ticket.updated: a support ticket changed Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "description": "`category`, `team`, `tags` and `mergedInto` appear only when the ticket has them. Some changes add extra keys describing the change.", "properties": { "assignedToUserId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "userId": { "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "closedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "csatScore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "leadId": { "format": "uuid", "type": "string" }, "merchantId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mergedInto": { "properties": { "id": { "format": "uuid", "type": "string" }, "ref": { "type": "string" } }, "type": "object" }, "previousStatus": { "description": "Only on ticket.reopened.", "type": "string" }, "priority": { "type": "string" }, "reopenedBy": { "description": "Only on ticket.reopened.", "type": "string" }, "resolvedAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "sourceCallId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "team": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ticketId": { "format": "uuid", "type": "string" }, "ticketRef": { "description": "Short reference shown to the customer.", "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ticketId", "leadId", "status" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "ticket.updated", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # transfer.failed: a transfer to a person did not connect (/api-reference/webhooks/onTransferFailed) ## Webhook transferFailed Operation ID: `onTransferFailed` transfer.failed: a transfer to a person did not connect Sent to webhook endpoints subscribed to this event (or to every event). A webhook URL set on a campaign or an agent receives the fields of `data` at the top level instead, plus `event` (the type) and `timestamp` (Unix seconds), signed with `X-Signature-SHA256` only. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "agentId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "callId": { "format": "uuid", "type": "string" }, "campaignId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "dialStatus": { "anyOf": [ { "description": "The carrier's answer, for example `no-answer` or `busy`.", "type": "string" }, { "type": "null" } ] }, "leadId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "callId" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "transfer.failed", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # webhook.test: sent by the send test event operation (/api-reference/webhooks/onWebhookTest) ## Webhook webhookTest Operation ID: `onWebhookTest` webhook.test: sent by the send test event operation Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "endpointId": { "format": "uuid", "type": "string" }, "message": { "type": "string" } }, "required": [ "endpointId" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "webhook.test", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # whatsapp.message.received: a customer sent a WhatsApp message (/api-reference/webhooks/onWhatsappMessageReceived) ## Webhook whatsappMessageReceived Operation ID: `onWhatsappMessageReceived` whatsapp.message.received: a customer sent a WhatsApp message Sent to webhook endpoints subscribed to this event (or to every event). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. | | `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. | | `webhook-signature` | header | no | Space-separated `v1,` values (two for 24 hours after a secret rotation). Webhook endpoints only. | | `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). | | `X-Webhook-Event` | header | no | The event type, for example `call.completed`. | | `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. | ### Request body `application/json` (required) ```json { "properties": { "apiVersion": { "const": "v1", "type": "string" }, "createdAt": { "description": "When the event happened, ISO 8601 UTC.", "format": "date-time", "type": "string" }, "data": { "properties": { "contact": { "properties": { "bsuid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "leadId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optInStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "conversationId": { "format": "uuid", "type": "string" }, "entrySource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "properties": { "createdAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "hasMedia": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "mediaFilename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaMime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payload": { "additionalProperties": true, "description": "The message content as WhatsApp sent it (keys unchanged).", "properties": {}, "type": "object" }, "replyToWamid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "description": "`text`, `image`, `button`, `interactive` and so on.", "type": "string" }, "wamid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "phoneId": { "format": "uuid", "type": "string" }, "serviceWindowExpiresAt": { "anyOf": [ { "description": "ISO 8601 timestamp, UTC.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "windowOpen": { "description": "True while you can send free-form replies.", "type": "boolean" } }, "required": [ "conversationId", "message" ], "type": "object" }, "id": { "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.", "type": "string" }, "type": { "const": "whatsapp.message.received", "type": "string" } }, "required": [ "id", "type", "apiVersion", "createdAt", "data" ], "type": "object" } ``` ### Responses #### 2XX Received. Anything else is retried. # List scheduled callbacks (/api-reference/campaigns/listCallbacks) ## GET /api/v1/callbacks Operation ID: `listCallbacks` List scheduled callbacks Callbacks your agents booked during calls and reminder calls from your rules, soonest first. Use `leadId` to see what is booked for one lead. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `status` | query | no | Comma-separated statuses, or `all`. Default `pending,queued,dialing` (still to happen). | | `kind` | query | no | `callback` or `reminder`. | | `leadId` | query | no | Only this lead's callbacks. | | `campaignId` | query | no | Only this campaign's callbacks. | | `agentId` | query | no | Only this agent's callbacks. | | `dateFrom` | query | no | `dialAt` at or after this ISO 8601 time. | | `dateTo` | query | no | `dialAt` at or before this ISO 8601 time. | | `limit` | query | no | Page size, 1 to 200. | | `offset` | query | no | Callbacks to skip. | ### Responses #### 200 OK Schema: ```json { "additionalProperties": true, "description": "One page of callbacks, soonest first.", "properties": { "callbacks": { "description": "Callbacks on this page, by `dialAt`.", "items": { "additionalProperties": true, "description": "A callback or reminder call booked for a lead.", "properties": { "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent that places the call.", "title": "Agentid" }, "attempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calls placed for this booking so far.", "title": "Attempts" }, "callId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest call placed for this booking.", "title": "Callid" }, "campaignId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Campaign whose agent and caller ID place the call.", "title": "Campaignid" }, "campaignName": { "default": "", "description": "Campaign's name.", "title": "Campaignname", "type": "string" }, "channel": { "default": "phone", "description": "How the lead is reached, usually `phone`.", "title": "Channel", "type": "string" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was booked (ISO 8601).", "title": "Createdat" }, "dialAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time the call will be placed; later than `dueAt` when moved into the dial window.", "title": "Dialat" }, "dialAtLocal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`dialAt` in `timezone`, for display.", "title": "Dialatlocal" }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time the lead asked for (ISO 8601, UTC).", "title": "Dueat" }, "id": { "description": "Callback ID.", "title": "Id", "type": "string" }, "kind": { "description": "`callback` (the lead asked to be called) or `reminder` (from a reminder rule).", "title": "Kind", "type": "string" }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Outcome of the latest attempt.", "title": "Lastoutcome" }, "leadId": { "description": "Lead to call back.", "title": "Leadid", "type": "string" }, "leadName": { "default": "", "description": "Lead's name.", "title": "Leadname", "type": "string" }, "leadPhone": { "default": "", "description": "Lead's phone number.", "title": "Leadphone", "type": "string" }, "maxAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calls allowed before it is marked `failed`.", "title": "Maxattempts" }, "note": { "default": "", "description": "Note shown to the agent on the call.", "title": "Note", "type": "string" }, "originCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call during which the callback was booked.", "title": "Origincallid" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the call is booked.", "title": "Purpose" }, "shifted": { "default": false, "description": "True when `dialAt` was moved into the dial window.", "title": "Shifted", "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What booked it: the agent during a call, a person, or a rule.", "title": "Source" }, "status": { "description": "`pending`, `queued`, `dialing`, `done`, `failed`, `cancelled` or `expired`.", "title": "Status", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone used for the booking.", "title": "Timezone" } }, "required": [ "id", "leadId", "kind", "status" ], "title": "ScheduledCallbackItem", "type": "object" }, "title": "Callbacks", "type": "array" }, "total": { "description": "Callbacks matching the filters.", "title": "Total", "type": "integer" } }, "required": [ "callbacks", "total" ], "title": "ScheduledCallbackList", "type": "object" } ``` #### 400 Bad request: `workspace_required`. Example (Merchant workspace required): ```json { "detail": "Merchant workspace required", "error": { "code": "workspace_required", "docUrl": "https://docs.callmitra.ai/errors/workspace_required", "message": "Merchant workspace required", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`workspace_required`](/errors/workspace_required) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List campaigns (/api-reference/campaigns/listCampaigns) ## GET /api/v1/campaigns/ Operation ID: `listCampaigns` List campaigns Campaigns you can see, page by page. Running campaigns include `dialHealth`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `page` | query | no | Page number, from 1. | | `limit` | query | no | Items per page, 1 to 200. | | `agentId` | query | no | Only campaigns of this agent. | ### Responses #### 200 OK Example (example): ```json { "campaigns": [ { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "autoDialEnabled": false, "createdAt": "2026-11-15T10:00:00Z", "direction": "outbound", "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "isActive": false, "name": "December renewals", "phoneNumberId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "settings": { "dialWindowEnd": "18:00", "dialWindowStart": "10:00", "maxCallsPerDay": 200, "maxConcurrentCalls": 2, "pacingSeconds": 5 }, "stats": { "calledLeads": 0, "connectRate": 0, "totalLeads": 0 }, "status": "draft" } ], "hasMore": false, "pagination": { "currentPage": 1, "hasNextPage": false, "hasPreviousPage": false, "itemsPerPage": 25, "totalCapped": false, "totalItems": 1, "totalPages": 1 }, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create an empty campaign (/api-reference/campaigns/createCampaign) ## POST /api/v1/campaigns/ Operation ID: `createCampaign` Create an empty campaign Add leads later with `PUT /campaigns/{campaign_id}/leads`. Without `phoneNumberId` the agent's assigned number is used. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "Campaign fields to create or change. On update, send only the fields to change.", "properties": { "agentId": { "description": "The agent that makes the calls.", "format": "uuid", "title": "Agentid", "type": "string" }, "crmWebhookSecret": { "description": "Secret used to sign those webhooks. Never returned.", "title": "Crmwebhooksecret", "type": "string" }, "crmWebhookUrl": { "description": "Public HTTPS URL that receives this campaign's call results; empty clears it.", "format": "uri", "title": "Crmwebhookurl", "type": "string" }, "description": { "description": "Free-text description.", "title": "Description", "type": "string" }, "direction": { "default": "outbound", "description": "`outbound` (call leads) or `inbound` (answer calls).", "enum": [ "outbound", "inbound" ], "title": "Direction", "type": "string" }, "endDate": { "description": "Planned end date, free text.", "title": "Enddate", "type": "string" }, "isActive": { "description": "Update only: `true` starts the campaign, `false` stops it (same checks as start and stop).", "title": "Isactive", "type": "boolean" }, "isDefaultInbound": { "description": "Inbound only: take calls to the number that no other campaign matches.", "title": "Isdefaultinbound", "type": "boolean" }, "name": { "description": "Campaign name. Defaults to `Untitled`.", "title": "Name", "type": "string" }, "phoneNumberId": { "description": "Caller ID. Required for inbound campaigns. Defaults to the agent's assigned number.", "format": "uuid", "title": "Phonenumberid", "type": "string" }, "phoneNumberIds": { "description": "Every number to call from, in order; the first is the primary caller ID.", "items": { "format": "uuid", "type": "string" }, "title": "Phonenumberids", "type": "array" }, "settings": { "anyOf": [ { "additionalProperties": true, "description": "Dialing rules. On update, send only the keys to change; they merge into the current settings.", "properties": { "autoDialEnabled": { "default": true, "description": "Dial automatically while the campaign is running; false pauses dialing.", "title": "Autodialenabled", "type": "boolean" }, "callInterval": { "default": 7200000, "description": "Milliseconds between attempts to the same lead (2 hours by default).", "minimum": 0, "title": "Callinterval", "type": "integer" }, "dialDaysOfWeek": { "default": [ 0, 1, 2, 3, 4, 5, 6 ], "description": "Days calls are placed: 0 = Monday ... 6 = Sunday.", "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "title": "Dialdaysofweek", "type": "array" }, "dialTimezone": { "default": "Asia/Kolkata", "description": "IANA time zone of the dial window.", "title": "Dialtimezone", "type": "string" }, "dialWindowEnd": { "default": "17:00", "description": "Local time `HH:MM`.", "title": "Dialwindowend", "type": "string" }, "dialWindowStart": { "default": "10:00", "description": "Local time `HH:MM`. Calls are placed only inside the window.", "title": "Dialwindowstart", "type": "string" }, "firstCallDelayMs": { "default": 0, "description": "Wait before a new lead's first call, in milliseconds.", "minimum": 0, "title": "Firstcalldelayms", "type": "integer" }, "maxCallsPerDay": { "default": 50, "description": "Calls the campaign may place per day.", "maximum": 100000, "minimum": 1, "title": "Maxcallsperday", "type": "integer" }, "maxConcurrentCalls": { "default": 1, "description": "Calls the campaign may have in progress at once, 1 to 500. Also limited by your plan's parallel calls and by each number's capacity. Default on create: 1, or twice the number of `phoneNumberIds` when created with leads.", "maximum": 500, "minimum": 1, "title": "Maxconcurrentcalls", "type": "integer" }, "pacingSeconds": { "default": 5, "description": "Seconds to wait between dial rounds, 0 to 3600; 0 dials again as soon as the dialer polls.", "maximum": 3600, "minimum": 0, "title": "Pacingseconds", "type": "integer" }, "retryAttempts": { "default": 3, "description": "Extra attempts per lead after the first call.", "maximum": 10, "minimum": 0, "title": "Retryattempts", "type": "integer" }, "retryIntervalBusyMs": { "default": 1800000, "description": "Milliseconds before retrying a busy lead.", "minimum": 0, "title": "Retryintervalbusyms", "type": "integer" }, "retryIntervalNoAnswerMs": { "description": "Milliseconds before retrying a lead that did not answer; null uses `callInterval`.", "minimum": 0, "title": "Retryintervalnoanswerms", "type": [ "integer", "null" ] }, "retryShortAnsweredCalls": { "default": false, "description": "Retry a lead whose call was answered but ended within seconds.", "title": "Retryshortansweredcalls", "type": "boolean" } }, "title": "CampaignSettings", "type": "object" }, { "type": "null" } ], "description": "Dialing rules; merged into the current ones." }, "startDate": { "description": "Planned start date, free text (for example `2026-12-01`).", "title": "Startdate", "type": "string" }, "status": { "description": "Display status to set, for example `draft`.", "title": "Status", "type": "string" } }, "title": "CampaignInput", "type": "object" } ``` Example: ```json { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "name": "December renewals", "settings": { "maxCallsPerDay": 200, "maxConcurrentCalls": 2 } } ``` ### Responses #### 200 OK Example (example): ```json { "campaign": { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "autoDialEnabled": false, "createdAt": "2026-11-15T10:00:00Z", "direction": "outbound", "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "isActive": false, "name": "December renewals", "phoneNumberId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "settings": { "dialWindowEnd": "18:00", "dialWindowStart": "10:00", "maxCallsPerDay": 200, "maxConcurrentCalls": 2, "pacingSeconds": 5 }, "stats": { "calledLeads": 0, "connectRate": 0, "totalLeads": 0 }, "status": "draft" }, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_default_inbound_exists`, `idempotency_key_reused`, `idempotency_request_in_progress`. Example (Another default inbound campaign already exists for this phone number.): ```json { "detail": "Another default inbound campaign already exists for this phone number.", "error": { "code": "campaign_default_inbound_exists", "docUrl": "https://docs.callmitra.ai/errors/campaign_default_inbound_exists", "message": "Another default inbound campaign already exists for this phone number.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`campaign_default_inbound_exists`](/errors/campaign_default_inbound_exists) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create a campaign with its leads (/api-reference/campaigns/createCampaignWithLeads) ## POST /api/v1/campaigns/create-with-leads Operation ID: `createCampaignWithLeads` Create a campaign with its leads The usual way to start: one request creates the campaign and adds or creates its leads. Start it with `POST /campaigns/{campaign_id}/start`, or send `campaignData.isActive: true` to start it right away (the same checks as start apply). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "A new campaign plus the leads to put on it.", "properties": { "campaignData": { "anyOf": [ { "additionalProperties": true, "description": "Campaign fields to create or change. On update, send only the fields to change.", "properties": { "agentId": { "description": "The agent that makes the calls.", "format": "uuid", "title": "Agentid", "type": "string" }, "crmWebhookSecret": { "description": "Secret used to sign those webhooks. Never returned.", "title": "Crmwebhooksecret", "type": "string" }, "crmWebhookUrl": { "description": "Public HTTPS URL that receives this campaign's call results; empty clears it.", "format": "uri", "title": "Crmwebhookurl", "type": "string" }, "description": { "description": "Free-text description.", "title": "Description", "type": "string" }, "direction": { "default": "outbound", "description": "`outbound` (call leads) or `inbound` (answer calls).", "enum": [ "outbound", "inbound" ], "title": "Direction", "type": "string" }, "endDate": { "description": "Planned end date, free text.", "title": "Enddate", "type": "string" }, "isActive": { "description": "Update only: `true` starts the campaign, `false` stops it (same checks as start and stop).", "title": "Isactive", "type": "boolean" }, "isDefaultInbound": { "description": "Inbound only: take calls to the number that no other campaign matches.", "title": "Isdefaultinbound", "type": "boolean" }, "name": { "description": "Campaign name. Defaults to `Untitled`.", "title": "Name", "type": "string" }, "phoneNumberId": { "description": "Caller ID. Required for inbound campaigns. Defaults to the agent's assigned number.", "format": "uuid", "title": "Phonenumberid", "type": "string" }, "phoneNumberIds": { "description": "Every number to call from, in order; the first is the primary caller ID.", "items": { "format": "uuid", "type": "string" }, "title": "Phonenumberids", "type": "array" }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/CampaignSettings" }, { "type": "null" } ], "description": "Dialing rules; merged into the current ones." }, "startDate": { "description": "Planned start date, free text (for example `2026-12-01`).", "title": "Startdate", "type": "string" }, "status": { "description": "Display status to set, for example `draft`.", "title": "Status", "type": "string" } }, "title": "CampaignInput", "type": "object" }, { "type": "null" } ], "description": "The campaign. `name` and `agentId` are required." }, "copySettingsFromCampaignId": { "description": "Start from another campaign's settings and webhook; `campaignData.settings` overrides them.", "format": "uuid", "title": "Copysettingsfromcampaignid", "type": "string" }, "leadSourceType": { "description": "`bulk_upload` creates the leads in `uploadedLeads`; `existing_leads` adds leads you already have. Optional only for a catch-all inbound campaign.", "enum": [ "bulk_upload", "existing_leads" ], "title": "Leadsourcetype", "type": "string" }, "selectedLeadIds": { "description": "With `existing_leads`: IDs of leads to add.", "items": { "format": "uuid", "type": "string" }, "title": "Selectedleadids", "type": "array" }, "selectedLeadSourceIds": { "description": "With `existing_leads`: add every lead of these sources (used when no lead IDs are given).", "items": { "format": "uuid", "type": "string" }, "title": "Selectedleadsourceids", "type": "array" }, "uploadedLeads": { "anyOf": [ { "items": { "additionalProperties": true, "description": "One lead to create (or match by phone) while creating a campaign.", "properties": { "attributes": { "additionalProperties": true, "description": "Extra fields the agent can use, for example `{\"city\": \"Pune\"}`.", "title": "Attributes", "type": "object" }, "company": { "description": "Company.", "title": "Company", "type": "string" }, "email": { "description": "Email address.", "title": "Email", "type": "string" }, "externalId": { "description": "Your ID for this person.", "title": "Externalid", "type": "string" }, "name": { "description": "Lead name.", "title": "Name", "type": "string" }, "notes": { "description": "Added as one imported note; never replaces existing notes.", "title": "Notes", "type": "string" }, "phone": { "description": "Phone number. Saved in E.164 form when it parses (no country code means India); otherwise saved as sent. A lead you already have with the same number is reused.", "title": "Phone", "type": "string" }, "title": { "description": "Job title.", "title": "Title", "type": "string" } }, "title": "CampaignLeadInput", "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "With `bulk_upload`: the leads to create. Repeated numbers are added once.", "title": "Uploadedleads" } }, "title": "CampaignWithLeadsInput", "type": "object" } ``` Example: ```json { "campaignData": { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "name": "December renewals", "settings": { "maxCallsPerDay": 200 } }, "leadSourceType": "bulk_upload", "uploadedLeads": [ { "attributes": { "city": "Pune" }, "name": "Asha Rao", "phone": "+919876543210" } ] } ``` ### Responses #### 200 OK Example (example): ```json { "campaignId": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "message": "Campaign created", "processedLeads": 1, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`, `resource_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_default_inbound_exists`, `idempotency_key_reused`, `idempotency_request_in_progress`. Example (Another default inbound campaign already exists for this phone number.): ```json { "detail": "Another default inbound campaign already exists for this phone number.", "error": { "code": "campaign_default_inbound_exists", "docUrl": "https://docs.callmitra.ai/errors/campaign_default_inbound_exists", "message": "Another default inbound campaign already exists for this phone number.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `campaign_not_ready`, `parameter_invalid`. Example (The campaign is not ready to start.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "campaign_not_ready", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_ready", "message": "The campaign is not ready to start.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`resource_not_found`](/errors/resource_not_found) - [`campaign_default_inbound_exists`](/errors/campaign_default_inbound_exists) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`campaign_not_ready`](/errors/campaign_not_ready) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a campaign (/api-reference/campaigns/getCampaign) ## GET /api/v1/campaigns/{campaign_id} Operation ID: `getCampaign` Get a campaign ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "campaign": { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "autoDialEnabled": false, "createdAt": "2026-11-15T10:00:00Z", "direction": "outbound", "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "isActive": false, "name": "December renewals", "phoneNumberId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "settings": { "dialWindowEnd": "18:00", "dialWindowStart": "10:00", "maxCallsPerDay": 200, "maxConcurrentCalls": 2, "pacingSeconds": 5 }, "stats": { "calledLeads": 0, "connectRate": 0, "totalLeads": 0 }, "status": "draft" }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Delete a campaign (/api-reference/campaigns/deleteCampaign) ## DELETE /api/v1/campaigns/{campaign_id} Operation ID: `deleteCampaign` Delete a campaign Cancels its scheduled dialing. Its calls are kept and no longer point at the campaign. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "message": "Campaign deleted", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Update a campaign (/api-reference/campaigns/updateCampaign) ## PUT /api/v1/campaigns/{campaign_id} Operation ID: `updateCampaign` Update a campaign Send only the fields to change. `settings` is merged into the current settings. Changing dialing rules on a running campaign re-plans its next dial round. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "Campaign fields to create or change. On update, send only the fields to change.", "properties": { "agentId": { "description": "The agent that makes the calls.", "format": "uuid", "title": "Agentid", "type": "string" }, "crmWebhookSecret": { "description": "Secret used to sign those webhooks. Never returned.", "title": "Crmwebhooksecret", "type": "string" }, "crmWebhookUrl": { "description": "Public HTTPS URL that receives this campaign's call results; empty clears it.", "format": "uri", "title": "Crmwebhookurl", "type": "string" }, "description": { "description": "Free-text description.", "title": "Description", "type": "string" }, "direction": { "default": "outbound", "description": "`outbound` (call leads) or `inbound` (answer calls).", "enum": [ "outbound", "inbound" ], "title": "Direction", "type": "string" }, "endDate": { "description": "Planned end date, free text.", "title": "Enddate", "type": "string" }, "isActive": { "description": "Update only: `true` starts the campaign, `false` stops it (same checks as start and stop).", "title": "Isactive", "type": "boolean" }, "isDefaultInbound": { "description": "Inbound only: take calls to the number that no other campaign matches.", "title": "Isdefaultinbound", "type": "boolean" }, "name": { "description": "Campaign name. Defaults to `Untitled`.", "title": "Name", "type": "string" }, "phoneNumberId": { "description": "Caller ID. Required for inbound campaigns. Defaults to the agent's assigned number.", "format": "uuid", "title": "Phonenumberid", "type": "string" }, "phoneNumberIds": { "description": "Every number to call from, in order; the first is the primary caller ID.", "items": { "format": "uuid", "type": "string" }, "title": "Phonenumberids", "type": "array" }, "settings": { "anyOf": [ { "additionalProperties": true, "description": "Dialing rules. On update, send only the keys to change; they merge into the current settings.", "properties": { "autoDialEnabled": { "default": true, "description": "Dial automatically while the campaign is running; false pauses dialing.", "title": "Autodialenabled", "type": "boolean" }, "callInterval": { "default": 7200000, "description": "Milliseconds between attempts to the same lead (2 hours by default).", "minimum": 0, "title": "Callinterval", "type": "integer" }, "dialDaysOfWeek": { "default": [ 0, 1, 2, 3, 4, 5, 6 ], "description": "Days calls are placed: 0 = Monday ... 6 = Sunday.", "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "title": "Dialdaysofweek", "type": "array" }, "dialTimezone": { "default": "Asia/Kolkata", "description": "IANA time zone of the dial window.", "title": "Dialtimezone", "type": "string" }, "dialWindowEnd": { "default": "17:00", "description": "Local time `HH:MM`.", "title": "Dialwindowend", "type": "string" }, "dialWindowStart": { "default": "10:00", "description": "Local time `HH:MM`. Calls are placed only inside the window.", "title": "Dialwindowstart", "type": "string" }, "firstCallDelayMs": { "default": 0, "description": "Wait before a new lead's first call, in milliseconds.", "minimum": 0, "title": "Firstcalldelayms", "type": "integer" }, "maxCallsPerDay": { "default": 50, "description": "Calls the campaign may place per day.", "maximum": 100000, "minimum": 1, "title": "Maxcallsperday", "type": "integer" }, "maxConcurrentCalls": { "default": 1, "description": "Calls the campaign may have in progress at once, 1 to 500. Also limited by your plan's parallel calls and by each number's capacity. Default on create: 1, or twice the number of `phoneNumberIds` when created with leads.", "maximum": 500, "minimum": 1, "title": "Maxconcurrentcalls", "type": "integer" }, "pacingSeconds": { "default": 5, "description": "Seconds to wait between dial rounds, 0 to 3600; 0 dials again as soon as the dialer polls.", "maximum": 3600, "minimum": 0, "title": "Pacingseconds", "type": "integer" }, "retryAttempts": { "default": 3, "description": "Extra attempts per lead after the first call.", "maximum": 10, "minimum": 0, "title": "Retryattempts", "type": "integer" }, "retryIntervalBusyMs": { "default": 1800000, "description": "Milliseconds before retrying a busy lead.", "minimum": 0, "title": "Retryintervalbusyms", "type": "integer" }, "retryIntervalNoAnswerMs": { "description": "Milliseconds before retrying a lead that did not answer; null uses `callInterval`.", "minimum": 0, "title": "Retryintervalnoanswerms", "type": [ "integer", "null" ] }, "retryShortAnsweredCalls": { "default": false, "description": "Retry a lead whose call was answered but ended within seconds.", "title": "Retryshortansweredcalls", "type": "boolean" } }, "title": "CampaignSettings", "type": "object" }, { "type": "null" } ], "description": "Dialing rules; merged into the current ones." }, "startDate": { "description": "Planned start date, free text (for example `2026-12-01`).", "title": "Startdate", "type": "string" }, "status": { "description": "Display status to set, for example `draft`.", "title": "Status", "type": "string" } }, "title": "CampaignInput", "type": "object" } ``` Example: ```json { "settings": { "dialWindowEnd": "19:00", "pacingSeconds": 10 } } ``` ### Responses #### 200 OK Example (example): ```json { "campaign": { "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "autoDialEnabled": false, "createdAt": "2026-11-15T10:00:00Z", "direction": "outbound", "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "isActive": false, "name": "December renewals", "phoneNumberId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "settings": { "dialWindowEnd": "18:00", "dialWindowStart": "10:00", "maxCallsPerDay": 200, "maxConcurrentCalls": 2, "pacingSeconds": 5 }, "stats": { "calledLeads": 0, "connectRate": 0, "totalLeads": 0 }, "status": "draft" }, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`, `resource_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_default_inbound_exists`, `campaign_not_running`. Example (Another default inbound campaign already exists for this phone number.): ```json { "detail": "Another default inbound campaign already exists for this phone number.", "error": { "code": "campaign_default_inbound_exists", "docUrl": "https://docs.callmitra.ai/errors/campaign_default_inbound_exists", "message": "Another default inbound campaign already exists for this phone number.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign is not active.): ```json { "detail": "Campaign is not active.", "error": { "code": "campaign_not_running", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "message": "Campaign is not active.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `campaign_not_ready`, `parameter_invalid`. Example (The campaign is not ready to start.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "campaign_not_ready", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_ready", "message": "The campaign is not ready to start.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`resource_not_found`](/errors/resource_not_found) - [`campaign_default_inbound_exists`](/errors/campaign_default_inbound_exists) - [`campaign_not_running`](/errors/campaign_not_running) - [`campaign_not_ready`](/errors/campaign_not_ready) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Dialing status (/api-reference/campaigns/getCampaignDialStatus) ## GET /api/v1/campaigns/{campaign_id}/dial-status Operation ID: `getCampaignDialStatus` Dialing status Whether the campaign is placing calls right now and, if not, why and when it will. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "activeCallCount": 0, "activeCalls": [], "autoDialEnabled": true, "callsToday": 48, "dialState": "waiting", "dialTimezone": "Asia/Kolkata", "dialWindowEnd": "18:00", "dialWindowStart": "10:00", "dialingAllowed": false, "inDialWindow": false, "isActive": true, "maxCallsPerDay": 200, "nextWindowOpenAt": "2026-11-16T04:30:00Z", "skipReason": "outside_window", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List a campaign's leads (/api-reference/campaigns/listCampaignLeads) ## GET /api/v1/campaigns/{campaign_id}/leads Operation ID: `listCampaignLeads` List a campaign's leads Active leads of the campaign, newest first, with their per-campaign dialing state. Send `page` to get one page of `limit` leads; without `page` every matching lead is returned in one response, so always send it for large campaigns. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | | `page` | query | no | Page number, from 1. Omit to get every matching lead. | | `limit` | query | no | Leads per page when `page` is sent, 1 to 200. | | `search` | query | no | Matches part of the lead's name, phone, email or your ID for the lead. | | `memberStatus` | query | no | Dialing state in this campaign, for example `not_called`, `calling`, `completed`, `failed`, `no_answer` or `busy`. | | `sentiment` | query | no | Sentiment of the lead's last call in this campaign, for example `positive`, `neutral` or `negative`. | | `rules` | query | no | Filter on lead fields, as a JSON object (URL-encoded). | | `merchantOutcome` | query | no | Outcome of the lead's latest call, for example `interested` or `callback`. | ### Responses #### 200 OK Example (example): ```json { "hasMore": false, "leads": [ { "callSummary": "", "id": "5a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "lastCallId": "", "lastSentiment": "positive", "name": "Asha Rao", "phone": "+919876543210" } ], "pagination": { "currentPage": 1, "hasNextPage": false, "hasPreviousPage": false, "itemsPerPage": 50, "totalItems": 1 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Add or remove leads (/api-reference/campaigns/updateCampaignLeads) ## PUT /api/v1/campaigns/{campaign_id}/leads Operation ID: `updateCampaignLeads` Add or remove leads New leads are dialed automatically if the campaign is running. Removed leads keep their call history. A lead already on the campaign, or a number already on it, is skipped. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "Leads to add to or remove from a campaign.", "properties": { "added": { "description": "Lead IDs to add. Removed leads are added back.", "items": { "format": "uuid", "type": "string" }, "title": "Added", "type": "array" }, "confirmRemovedContacted": { "default": false, "description": "Required to remove leads that were already called; otherwise the request returns 409 `campaign_leads_need_confirmation` with their IDs.", "title": "Confirmremovedcontacted", "type": "boolean" }, "removed": { "description": "Lead IDs to remove.", "items": { "format": "uuid", "type": "string" }, "title": "Removed", "type": "array" } }, "title": "CampaignLeadsChange", "type": "object" } ``` Example: ```json { "added": [ "5a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ], "removed": [] } ``` ### Responses #### 200 OK Example (example): ```json { "added": 1, "campaign": { "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d" }, "dialScheduled": true, "message": "Updated", "reactivated": 0, "removed": 0, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`, `lead_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_leads_need_confirmation`, `lead_call_in_progress`. Example (Some leads were already contacted in this campaign.): ```json { "detail": "Some leads were already contacted in this campaign.", "error": { "code": "campaign_leads_need_confirmation", "docUrl": "https://docs.callmitra.ai/errors/campaign_leads_need_confirmation", "message": "Some leads were already contacted in this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Lead already has an active call.): ```json { "detail": "Lead already has an active call.", "error": { "code": "lead_call_in_progress", "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress", "message": "Lead already has an active call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`lead_not_found`](/errors/lead_not_found) - [`campaign_leads_need_confirmation`](/errors/campaign_leads_need_confirmation) - [`lead_call_in_progress`](/errors/lead_call_in_progress) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Pause automatic dialing (/api-reference/campaigns/pauseCampaignDialing) ## POST /api/v1/campaigns/{campaign_id}/pause-dialing Operation ID: `pauseCampaignDialing` Pause automatic dialing The campaign stays active; resume to continue where it left off. Calls in progress finish. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "cancelledJobs": 1, "message": "Auto-dialing paused", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Resume automatic dialing (/api-reference/campaigns/resumeCampaignDialing) ## POST /api/v1/campaigns/{campaign_id}/resume-dialing Operation ID: `resumeCampaignDialing` Resume automatic dialing Only for a running campaign whose dialing was paused; a stopped campaign needs `POST /campaigns/{campaign_id}/start`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "message": "Auto-dialing resumed", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_not_running`. Example (Campaign is not active.): ```json { "detail": "Campaign is not active.", "error": { "code": "campaign_not_running", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "message": "Campaign is not active.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`campaign_not_running`](/errors/campaign_not_running) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Start a campaign (/api-reference/campaigns/startCampaign) ## POST /api/v1/campaigns/{campaign_id}/start Operation ID: `startCampaign` Start a campaign Starts dialing. Calls are placed only inside the dial window and up to the daily limit. The campaign must have an agent whose prompt the leads can fill and a number that can place calls; otherwise nothing changes and the error says what to fix. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "leadCount": 120, "message": "Campaign started — dialing will proceed automatically on schedule", "processedCount": 120, "success": true, "warnings": [] } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `campaign_not_ready`, `parameter_invalid`. Example (The campaign is not ready to start.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "campaign_not_ready", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_ready", "message": "The campaign is not ready to start.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`campaign_not_ready`](/errors/campaign_not_ready) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Stop a campaign (/api-reference/campaigns/stopCampaign) ## POST /api/v1/campaigns/{campaign_id}/stop Operation ID: `stopCampaign` Stop a campaign Stops the campaign and cancels calls waiting to be placed. A call in progress finishes. Stopping a stopped campaign is allowed and changes nothing. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `campaign_id` | path | yes | Campaign ID. | ### Responses #### 200 OK Example (example): ```json { "campaign": { "id": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "isActive": false }, "cancelledJobs": 1, "message": "Campaign stopped", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List calls (/api-reference/calls/listCalls) ## GET /api/v1/calls/ Operation ID: `listCalls` List calls Newest first. For deep lists pass `cursor` (empty for the first page, then the `nextCursor` you got back): cursor pages skip the total count and stay fast. Without `cursor` the list pages by `page` and counts matches up to 10,000. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `page` | query | no | Page number, from 1. Ignored when `cursor` is sent. | | `limit` | query | no | Items per page, up to 200. | | `cursor` | query | no | Empty for the first page, then the previous response's `nextCursor`. | | `search` | query | no | Matches the phone number, customer name or phone, summary, or call name. | | `agentId` | query | no | Only calls of this agent. | | `leadId` | query | no | Only calls to this lead. | | `campaignId` | query | no | Only calls of this campaign. | | `outcome` | query | no | Only calls with this outcome. | | `sentiment` | query | no | Only calls with this sentiment. | | `channel` | query | no | `instant`, `bulk`, `inbound`, or `browser` (test calls). | | `hasRecording` | query | no | Only calls with (`true`) or without (`false`) a recording. | | `dateFilter` | query | no | `today` = started since 00:00 UTC today; `week` / `month` = started in the last 7 / 30 days (rolling); `all` or omitted = no date filter. | | `includeTests` | query | no | Include browser test calls. | ### Responses #### 200 OK Example (example): ```json { "calls": [ { "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "agentName": "Priya", "billableMinutes": 2, "billedInr": 9, "callType": "manual", "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "Priya instant calls", "channel": "instant", "createdAt": "2026-11-14T10:02:09Z", "duration": 94, "endTime": "2026-11-14T10:03:45Z", "endedReason": "customer-ended-call", "extractedFields": { "delivery_slot": "morning" }, "fromNumber": "+918045671234", "hasRecording": true, "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "isEscalated": false, "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "merchantOutcome": "interested", "metadata": { "crmId": "0065g00000XyZ" }, "outcome": "successful", "outcomeCategory": "interested", "phoneNumber": "+919812345678", "phoneNumberId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "sentiment": "positive", "startTime": "2026-11-14T10:02:11Z", "status": "completed", "summary": "Customer confirmed Friday delivery and asked for a morning slot.", "transcript": "Assistant: Hi Asha, this is Priya from Acme about order A-1042.\nUser: Yes, go ahead.", "updatedAt": "2026-11-14T10:03:52Z" } ], "hasMore": false, "pagination": { "currentPage": 1, "hasNextPage": false, "hasPreviousPage": false, "itemsPerPage": 25, "totalCapped": false, "totalItems": 1, "totalPages": 1 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Place a call (/api-reference/calls/createCall) ## POST /api/v1/calls/ Operation ID: `createCall` Place a call Calls `to` now with the agent, outside any campaign schedule. The number is saved as a lead (or matched to an existing one) and dialed through the agent's instant campaign, one call at a time per agent. Numbers on your do-not-call list are never dialed. The response means the carrier accepted the dial; follow the call with `GET /calls/{callId}` or call webhooks. Send an `Idempotency-Key` header so a retried request does not call twice. Each request dials once. A call that is not answered, is busy or times out is not redialed, and a refused dial is not queued for later: place another call if you want a second attempt. The one exception is a callback the callee asks for and the agent books during the call; that scheduled callback is placed at the agreed time. Toll-fraud limits: `to` must be in your workspace's home country (from your billing address; India when none is set) unless support enabled more countries, and each workspace may place a fixed number of calls per UTC day through this endpoint (`daily_call_limit_reached` with `Retry-After` until 00:00 UTC). Calling hours (TRAI / local quiet hours) are not enforced on direct calls: checking the time of day at the callee is your responsibility. Campaigns apply their own calling windows. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "additionalProperties": false, "description": "Who to call, with which agent, and what to tell the agent.", "properties": { "agentId": { "description": "Agent that speaks on the call. Archived agents cannot call.", "title": "Agentid", "type": "string" }, "fromNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your phone number to call from (`GET /phone-numbers`). Omitted: a free number from the agent's phone numbers.", "title": "Fromnumberid" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead this call belongs to; its phone must match `to`. Omitted: the lead with this number, or a new lead named `name`.", "title": "Leadid" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Your own data (at most 4096 bytes of JSON). Returned as `metadata` on the call (`GET /calls/{callId}`); never spoken.", "title": "Metadata" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Name for a new lead. Ignored when the lead exists.", "title": "Name" }, "to": { "description": "Number to call in E.164 format, e.g. `+919812345678`.", "maxLength": 32, "title": "To", "type": "string" }, "variables": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "description": "Up to 50 values the agent's script can use as `{{name}}`. Keys are letters, digits and underscores and must not start with a digit.", "title": "Variables" } }, "required": [ "agentId", "to" ], "title": "CreateCallRequest", "type": "object" } ``` Example: ```json { "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "metadata": { "crmId": "0065g00000XyZ" }, "name": "Asha Verma", "to": "+919812345678", "variables": { "delivery_date": "Friday", "order_id": "A-1042" } } ``` ### Responses #### 201 OK Example (example): ```json { "call": { "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "Delivery desk Instant", "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "phoneNumber": "+919812345678", "phoneNumberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "providerCallId": "CA5f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c", "status": "queued" }, "success": true } ``` #### 400 Bad request: `bad_request`, `campaign_has_no_agent`, `dial_rejected`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (Campaign has no agent assigned.): ```json { "detail": "Campaign has no agent assigned.", "error": { "code": "campaign_has_no_agent", "docUrl": "https://docs.callmitra.ai/errors/campaign_has_no_agent", "message": "Campaign has no agent assigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The carrier rejected the call.): ```json { "detail": "The carrier rejected the call.", "error": { "code": "dial_rejected", "docUrl": "https://docs.callmitra.ai/errors/dial_rejected", "message": "The carrier rejected the call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `agent_not_found`, `campaign_not_found`, `lead_not_found`, `lead_not_on_campaign`, `phone_number_not_found`. Example (Agent not found.): ```json { "detail": "Agent not found.", "error": { "code": "agent_not_found", "docUrl": "https://docs.callmitra.ai/errors/agent_not_found", "message": "Agent not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead is not on this campaign.): ```json { "detail": "Lead is not on this campaign.", "error": { "code": "lead_not_on_campaign", "docUrl": "https://docs.callmitra.ai/errors/lead_not_on_campaign", "message": "Lead is not on this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Phone number not found.): ```json { "detail": "Phone number not found.", "error": { "code": "phone_number_not_found", "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_found", "message": "Phone number not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_call_limit_reached`, `campaign_dial_busy`, `campaign_no_eligible_leads`, `campaign_not_running`, `carrier_capacity_reached`, `idempotency_key_reused`, `idempotency_request_in_progress`, `lead_call_in_progress`, `number_on_dnc`. Example (Campaign already has an active call in progress.): ```json { "detail": "Campaign already has an active call in progress.", "error": { "code": "campaign_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_call_limit_reached", "message": "Campaign already has an active call in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign dial in progress.): ```json { "detail": "Campaign dial in progress.", "error": { "code": "campaign_dial_busy", "docUrl": "https://docs.callmitra.ai/errors/campaign_dial_busy", "message": "Campaign dial in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (No leads available for calling.): ```json { "detail": "No leads available for calling.", "error": { "code": "campaign_no_eligible_leads", "docUrl": "https://docs.callmitra.ai/errors/campaign_no_eligible_leads", "message": "No leads available for calling.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign is not active.): ```json { "detail": "Campaign is not active.", "error": { "code": "campaign_not_running", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "message": "Campaign is not active.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The phone number or carrier account is at its call limit.): ```json { "detail": "The phone number or carrier account is at its call limit.", "error": { "code": "carrier_capacity_reached", "docUrl": "https://docs.callmitra.ai/errors/carrier_capacity_reached", "message": "The phone number or carrier account is at its call limit.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (Lead already has an active call.): ```json { "detail": "Lead already has an active call.", "error": { "code": "lead_call_in_progress", "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress", "message": "Lead already has an active call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This number is on the DNC list and will not be dialed.): ```json { "detail": "This number is on the DNC list and will not be dialed.", "error": { "code": "number_on_dnc", "docUrl": "https://docs.callmitra.ai/errors/number_on_dnc", "message": "This number is on the DNC list and will not be dialed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `agent_state_blocked`, `destination_not_allowed`, `invalid_phone_number`, `parameter_invalid`, `phone_number_not_dialable`. Example (The agent cannot make this change yet.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "agent_state_blocked", "docUrl": "https://docs.callmitra.ai/errors/agent_state_blocked", "message": "The agent cannot make this change yet.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (Calls to this country are not enabled for your workspace.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "destination_not_allowed", "docUrl": "https://docs.callmitra.ai/errors/destination_not_allowed", "message": "Calls to this country are not enabled for your workspace.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The phone number is not valid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "invalid_phone_number", "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number", "message": "The phone number is not valid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (This phone number cannot place calls.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "phone_number_not_dialable", "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_dialable", "message": "This phone number cannot place calls.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `campaign_daily_cap_reached`, `concurrent_call_limit_reached`, `daily_call_limit_reached`, `rate_limit_exceeded`. Example (Daily call limit reached for this campaign.): ```json { "detail": "Daily call limit reached for this campaign.", "error": { "code": "campaign_daily_cap_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_daily_cap_reached", "message": "Daily call limit reached for this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Merchant concurrent call limit reached.): ```json { "detail": "Merchant concurrent call limit reached.", "error": { "code": "concurrent_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/concurrent_call_limit_reached", "message": "Merchant concurrent call limit reached.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Your workspace reached its daily limit for calls placed through the API.): ```json { "detail": "Your workspace reached its daily limit for calls placed through the API.", "error": { "code": "daily_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/daily_call_limit_reached", "message": "Your workspace reached its daily limit for calls placed through the API.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` #### 502 Error: `dial_failed`. Example (Failed to place outbound call.): ```json { "detail": "Failed to place outbound call.", "error": { "code": "dial_failed", "docUrl": "https://docs.callmitra.ai/errors/dial_failed", "message": "Failed to place outbound call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` #### 503 Service unavailable: `service_unavailable`. Example (The service is temporarily unavailable.): ```json { "detail": "The service is temporarily unavailable.", "error": { "code": "service_unavailable", "docUrl": "https://docs.callmitra.ai/errors/service_unavailable", "message": "The service is temporarily unavailable.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`campaign_has_no_agent`](/errors/campaign_has_no_agent) - [`dial_rejected`](/errors/dial_rejected) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`agent_not_found`](/errors/agent_not_found) - [`campaign_not_found`](/errors/campaign_not_found) - [`lead_not_found`](/errors/lead_not_found) - [`lead_not_on_campaign`](/errors/lead_not_on_campaign) - [`phone_number_not_found`](/errors/phone_number_not_found) - [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) - [`campaign_dial_busy`](/errors/campaign_dial_busy) - [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) - [`campaign_not_running`](/errors/campaign_not_running) - [`carrier_capacity_reached`](/errors/carrier_capacity_reached) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`lead_call_in_progress`](/errors/lead_call_in_progress) - [`number_on_dnc`](/errors/number_on_dnc) - [`agent_state_blocked`](/errors/agent_state_blocked) - [`destination_not_allowed`](/errors/destination_not_allowed) - [`invalid_phone_number`](/errors/invalid_phone_number) - [`parameter_invalid`](/errors/parameter_invalid) - [`phone_number_not_dialable`](/errors/phone_number_not_dialable) - [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) - [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) - [`daily_call_limit_reached`](/errors/daily_call_limit_reached) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) - [`dial_failed`](/errors/dial_failed) - [`service_unavailable`](/errors/service_unavailable) # Calls per day (/api-reference/calls/getCallDailyCounts) ## GET /api/v1/calls/daily-counts Operation ID: `getCallDailyCounts` Calls per day Calls per calendar day for the last `days` days (India Standard Time): total, completed, failed, not answered and average length, plus totals. Days without calls are zeros. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `days` | query | no | Days to cover, ending today: 1 to 90. Default 30. | ### Responses #### 200 OK Example (example): ```json { "daily": [ { "avgDurationSeconds": 80, "completed": 4, "date": "2026-11-14", "failed": 0, "noAnswer": 1, "total": 5 }, { "avgDurationSeconds": 69.6, "completed": 5, "date": "2026-11-15", "failed": 1, "noAnswer": 1, "total": 7 } ], "days": 2, "success": true, "timezone": "Asia/Kolkata", "totals": { "avgDurationSeconds": 74.2, "completed": 9, "failed": 1, "noAnswer": 2, "total": 12 } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Call performance (/api-reference/calls/getCallPerformance) ## GET /api/v1/calls/performance Operation ID: `getCallPerformance` Call performance Totals, connect rate, conversion, outcome and channel split, calls per hour and an agent leaderboard for the last 7, 30 or 90 days, with the range before it for comparison. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `rangeDays` | query | no | Days to cover, ending today: 7, 30 or 90 (any other value means 30). | | `agentId` | query | no | Only calls of this agent. | | `channel` | query | no | Only calls of this channel. | | `includeTests` | query | no | Also count test calls placed from the console. Default false. | ### Responses #### 200 OK Example (example): ```json { "byChannel": { "bulk": 230, "inbound": 50, "instant": 140 }, "byHour": { "10": 64, "11": 88, "12": 71, "15": 90, "16": 107 }, "byOutcome": { "busy": 22, "call_failed": 40, "callback": 22, "interested": 41, "no_answer": 160, "not_interested": 95, "qualified": 40 }, "funnel": { "calls": 420, "connected": 260, "qualified": 81 }, "includeTests": false, "kpis": { "avgLengthSeconds": 83.5, "calls": 420, "connectRate": 0.62, "conversion": 0.31, "leads": 388, "minutesUsed": 512, "successRate": 0.58 }, "leaderboard": [ { "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "calls": 300, "connected": 190, "minutes": 380, "name": "Priya", "qualified": 62 }, { "agentId": "7c2e9a10-3b4d-4e5f-8a6b-9c0d1e2f3a4b", "calls": 120, "connected": 70, "minutes": 132, "name": "Arjun", "qualified": 19 } ], "prior": { "calls": 365, "connectRate": 0.59, "conversion": 0.27 }, "rangeDays": 30, "recent": { "last24h": 26, "lastHour": 3, "today": 18 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a call (/api-reference/calls/getCall) ## GET /api/v1/calls/{call_id} Operation ID: `getCall` Get a call Status, transcript, summary, outcome, cost and the details the agent collected. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `call_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "call": { "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "agentName": "Priya", "billableMinutes": 2, "billedInr": 9, "callType": "manual", "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "Priya instant calls", "channel": "instant", "createdAt": "2026-11-14T10:02:09Z", "duration": 94, "endTime": "2026-11-14T10:03:45Z", "endedReason": "customer-ended-call", "extractedFields": { "delivery_slot": "morning" }, "fromNumber": "+918045671234", "hasRecording": true, "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "isEscalated": false, "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "merchantOutcome": "interested", "metadata": { "crmId": "0065g00000XyZ" }, "outcome": "successful", "outcomeCategory": "interested", "phoneNumber": "+919812345678", "phoneNumberId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "sentiment": "positive", "startTime": "2026-11-14T10:02:11Z", "status": "completed", "summary": "Customer confirmed Friday delivery and asked for a morning slot.", "transcript": "Assistant: Hi Asha, this is Priya from Acme about order A-1042.\nUser: Yes, go ahead.", "updatedAt": "2026-11-14T10:03:52Z", "whatsappSent": [ { "createdAt": "2026-11-14T10:03:10Z", "error": "", "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a", "kind": "template", "status": "delivered", "statusAt": "2026-11-14T10:03:14Z", "template": "order_confirmation" } ] }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `call_not_found`. Example (Call not found.): ```json { "detail": "Call not found.", "error": { "code": "call_not_found", "docUrl": "https://docs.callmitra.ai/errors/call_not_found", "message": "Call not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`call_not_found`](/errors/call_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Download a call recording (/api-reference/calls/getCallRecording) ## GET /api/v1/calls/{call_id}/recording Operation ID: `getCallRecording` Download a call recording The call's audio (MP3, or WAV for a call that is still being converted). Check `hasRecording` on the call first. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `call_id` | path | yes | | ### Responses #### 200 OK Schema: ```json { "format": "binary", "type": "string" } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `call_not_found`, `call_recording_not_found`. Example (Call not found.): ```json { "detail": "Call not found.", "error": { "code": "call_not_found", "docUrl": "https://docs.callmitra.ai/errors/call_not_found", "message": "Call not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (No recording is available for this call.): ```json { "detail": "No recording is available for this call.", "error": { "code": "call_recording_not_found", "docUrl": "https://docs.callmitra.ai/errors/call_recording_not_found", "message": "No recording is available for this call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 410 Error: `call_recording_deleted`. Example (This recording was deleted under the data retention policy.): ```json { "detail": "This recording was deleted under the data retention policy.", "error": { "code": "call_recording_deleted", "docUrl": "https://docs.callmitra.ai/errors/call_recording_deleted", "message": "This recording was deleted under the data retention policy.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`call_not_found`](/errors/call_not_found) - [`call_recording_not_found`](/errors/call_recording_not_found) - [`call_recording_deleted`](/errors/call_recording_deleted) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a call transcript (/api-reference/calls/getCallTranscript) ## GET /api/v1/calls/{call_id}/transcript Operation ID: `getCallTranscript` Get a call transcript The conversation as text and as ordered turns, plus the tools the agent called. Empty while nothing has been said; final once the call has ended. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `call_id` | path | yes | | ### Responses #### 200 OK Example (example): ```json { "callId": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "status": "completed", "success": true, "toolInvocations": [], "transcript": "Assistant: Hi, this is Asha from Acme.\nUser: Hi, yes.", "turns": [ { "role": "assistant", "text": "Hi, this is Asha from Acme." }, { "role": "user", "text": "Hi, yes." } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `call_not_found`. Example (Call not found.): ```json { "detail": "Call not found.", "error": { "code": "call_not_found", "docUrl": "https://docs.callmitra.ai/errors/call_not_found", "message": "Call not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`call_not_found`](/errors/call_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Call a lead in a campaign now (/api-reference/calls/callNow) ## POST /api/v1/instant/call-now Operation ID: `callNow` Call a lead in a campaign now Places the call immediately, outside the dial schedule, with the campaign's agent and numbers. Numbers on do-not-call are never dialed. To call any number without a campaign, use `POST /calls`. ### Request body `application/json` (required) ```json { "properties": { "campaignId": { "description": "A running campaign the lead belongs to; its agent and numbers are used.", "title": "Campaignid", "type": "string" }, "leadId": { "description": "Lead to call. It must be on the campaign and not on do-not-call.", "title": "Leadid", "type": "string" } }, "required": [ "leadId", "campaignId" ], "title": "CallNowIn", "type": "object" } ``` Example: ```json { "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d" } ``` ### Responses #### 200 OK Example (example): ```json { "call": { "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "campaignName": "November renewals", "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65", "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d", "leadName": "Asha Verma", "phoneNumber": "+919812345678", "phoneNumberId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "providerCallId": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6", "status": "initiated" }, "success": true } ``` #### 400 Bad request: `bad_request`, `campaign_has_no_agent`, `dial_rejected`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (Campaign has no agent assigned.): ```json { "detail": "Campaign has no agent assigned.", "error": { "code": "campaign_has_no_agent", "docUrl": "https://docs.callmitra.ai/errors/campaign_has_no_agent", "message": "Campaign has no agent assigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The carrier rejected the call.): ```json { "detail": "The carrier rejected the call.", "error": { "code": "dial_rejected", "docUrl": "https://docs.callmitra.ai/errors/dial_rejected", "message": "The carrier rejected the call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`, `lead_not_found`, `lead_not_on_campaign`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead is not on this campaign.): ```json { "detail": "Lead is not on this campaign.", "error": { "code": "lead_not_on_campaign", "docUrl": "https://docs.callmitra.ai/errors/lead_not_on_campaign", "message": "Lead is not on this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_call_limit_reached`, `campaign_dial_busy`, `campaign_no_eligible_leads`, `campaign_not_running`, `carrier_capacity_reached`, `lead_call_in_progress`, `number_on_dnc`. Example (Campaign already has an active call in progress.): ```json { "detail": "Campaign already has an active call in progress.", "error": { "code": "campaign_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_call_limit_reached", "message": "Campaign already has an active call in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign dial in progress.): ```json { "detail": "Campaign dial in progress.", "error": { "code": "campaign_dial_busy", "docUrl": "https://docs.callmitra.ai/errors/campaign_dial_busy", "message": "Campaign dial in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (No leads available for calling.): ```json { "detail": "No leads available for calling.", "error": { "code": "campaign_no_eligible_leads", "docUrl": "https://docs.callmitra.ai/errors/campaign_no_eligible_leads", "message": "No leads available for calling.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign is not active.): ```json { "detail": "Campaign is not active.", "error": { "code": "campaign_not_running", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "message": "Campaign is not active.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The phone number or carrier account is at its call limit.): ```json { "detail": "The phone number or carrier account is at its call limit.", "error": { "code": "carrier_capacity_reached", "docUrl": "https://docs.callmitra.ai/errors/carrier_capacity_reached", "message": "The phone number or carrier account is at its call limit.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Lead already has an active call.): ```json { "detail": "Lead already has an active call.", "error": { "code": "lead_call_in_progress", "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress", "message": "Lead already has an active call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This number is on the DNC list and will not be dialed.): ```json { "detail": "This number is on the DNC list and will not be dialed.", "error": { "code": "number_on_dnc", "docUrl": "https://docs.callmitra.ai/errors/number_on_dnc", "message": "This number is on the DNC list and will not be dialed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `campaign_daily_cap_reached`, `concurrent_call_limit_reached`, `rate_limit_exceeded`. Example (Daily call limit reached for this campaign.): ```json { "detail": "Daily call limit reached for this campaign.", "error": { "code": "campaign_daily_cap_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_daily_cap_reached", "message": "Daily call limit reached for this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Merchant concurrent call limit reached.): ```json { "detail": "Merchant concurrent call limit reached.", "error": { "code": "concurrent_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/concurrent_call_limit_reached", "message": "Merchant concurrent call limit reached.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` #### 502 Error: `dial_failed`. Example (Failed to place outbound call.): ```json { "detail": "Failed to place outbound call.", "error": { "code": "dial_failed", "docUrl": "https://docs.callmitra.ai/errors/dial_failed", "message": "Failed to place outbound call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`campaign_has_no_agent`](/errors/campaign_has_no_agent) - [`dial_rejected`](/errors/dial_rejected) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`lead_not_found`](/errors/lead_not_found) - [`lead_not_on_campaign`](/errors/lead_not_on_campaign) - [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) - [`campaign_dial_busy`](/errors/campaign_dial_busy) - [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) - [`campaign_not_running`](/errors/campaign_not_running) - [`carrier_capacity_reached`](/errors/carrier_capacity_reached) - [`lead_call_in_progress`](/errors/lead_call_in_progress) - [`number_on_dnc`](/errors/number_on_dnc) - [`parameter_invalid`](/errors/parameter_invalid) - [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) - [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) - [`dial_failed`](/errors/dial_failed) # Call a lead now (/api-reference/calls/callLeadNow) ## POST /api/v1/leads/{lead_id}/call-now Operation ID: `callLeadNow` Call a lead now Calls the lead right away through the first running campaign it belongs to, using that campaign's agent and caller ID. The lead's do-not-call flag, the campaign's daily cap and your concurrent call limit still apply; each refusal has its own error code. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | ### Responses #### 200 OK Example (example): ```json { "call": { "campaignId": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d", "campaignName": "December renewals", "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "leadId": "5d2f8a1e-3b4c-4d6e-9f0a-1b2c3d4e5f60", "leadName": "Asha Rao", "phoneNumber": "+919876543210", "phoneNumberId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "status": "initiated" }, "success": true } ``` #### 400 Bad request: `bad_request`, `campaign_has_no_agent`, `dial_rejected`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (Campaign has no agent assigned.): ```json { "detail": "Campaign has no agent assigned.", "error": { "code": "campaign_has_no_agent", "docUrl": "https://docs.callmitra.ai/errors/campaign_has_no_agent", "message": "Campaign has no agent assigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (The carrier rejected the call.): ```json { "detail": "The carrier rejected the call.", "error": { "code": "dial_rejected", "docUrl": "https://docs.callmitra.ai/errors/dial_rejected", "message": "The carrier rejected the call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 402 Payment required: `payment_required`. Example (Your account does not have enough balance or an active plan for this request.): ```json { "detail": "Your account does not have enough balance or an active plan for this request.", "error": { "code": "payment_required", "docUrl": "https://docs.callmitra.ai/errors/payment_required", "message": "Your account does not have enough balance or an active plan for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "billing_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`, `lead_not_found`, `lead_not_on_campaign`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Lead is not on this campaign.): ```json { "detail": "Lead is not on this campaign.", "error": { "code": "lead_not_on_campaign", "docUrl": "https://docs.callmitra.ai/errors/lead_not_on_campaign", "message": "Lead is not on this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `campaign_call_limit_reached`, `campaign_dial_busy`, `campaign_no_eligible_leads`, `campaign_not_running`, `carrier_capacity_reached`, `lead_call_in_progress`, `number_on_dnc`. Example (Campaign already has an active call in progress.): ```json { "detail": "Campaign already has an active call in progress.", "error": { "code": "campaign_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_call_limit_reached", "message": "Campaign already has an active call in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign dial in progress.): ```json { "detail": "Campaign dial in progress.", "error": { "code": "campaign_dial_busy", "docUrl": "https://docs.callmitra.ai/errors/campaign_dial_busy", "message": "Campaign dial in progress.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (No leads available for calling.): ```json { "detail": "No leads available for calling.", "error": { "code": "campaign_no_eligible_leads", "docUrl": "https://docs.callmitra.ai/errors/campaign_no_eligible_leads", "message": "No leads available for calling.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Campaign is not active.): ```json { "detail": "Campaign is not active.", "error": { "code": "campaign_not_running", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_running", "message": "Campaign is not active.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The phone number or carrier account is at its call limit.): ```json { "detail": "The phone number or carrier account is at its call limit.", "error": { "code": "carrier_capacity_reached", "docUrl": "https://docs.callmitra.ai/errors/carrier_capacity_reached", "message": "The phone number or carrier account is at its call limit.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Lead already has an active call.): ```json { "detail": "Lead already has an active call.", "error": { "code": "lead_call_in_progress", "docUrl": "https://docs.callmitra.ai/errors/lead_call_in_progress", "message": "Lead already has an active call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (This number is on the DNC list and will not be dialed.): ```json { "detail": "This number is on the DNC list and will not be dialed.", "error": { "code": "number_on_dnc", "docUrl": "https://docs.callmitra.ai/errors/number_on_dnc", "message": "This number is on the DNC list and will not be dialed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `lead_has_no_campaign`, `parameter_invalid`. Example (Lead is not on a campaign.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "lead_has_no_campaign", "docUrl": "https://docs.callmitra.ai/errors/lead_has_no_campaign", "message": "Lead is not on a campaign.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `campaign_daily_cap_reached`, `concurrent_call_limit_reached`, `rate_limit_exceeded`. Example (Daily call limit reached for this campaign.): ```json { "detail": "Daily call limit reached for this campaign.", "error": { "code": "campaign_daily_cap_reached", "docUrl": "https://docs.callmitra.ai/errors/campaign_daily_cap_reached", "message": "Daily call limit reached for this campaign.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Merchant concurrent call limit reached.): ```json { "detail": "Merchant concurrent call limit reached.", "error": { "code": "concurrent_call_limit_reached", "docUrl": "https://docs.callmitra.ai/errors/concurrent_call_limit_reached", "message": "Merchant concurrent call limit reached.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` #### 502 Error: `dial_failed`. Example (Failed to place outbound call.): ```json { "detail": "Failed to place outbound call.", "error": { "code": "dial_failed", "docUrl": "https://docs.callmitra.ai/errors/dial_failed", "message": "Failed to place outbound call.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`campaign_has_no_agent`](/errors/campaign_has_no_agent) - [`dial_rejected`](/errors/dial_rejected) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`payment_required`](/errors/payment_required) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`lead_not_found`](/errors/lead_not_found) - [`lead_not_on_campaign`](/errors/lead_not_on_campaign) - [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) - [`campaign_dial_busy`](/errors/campaign_dial_busy) - [`campaign_no_eligible_leads`](/errors/campaign_no_eligible_leads) - [`campaign_not_running`](/errors/campaign_not_running) - [`carrier_capacity_reached`](/errors/carrier_capacity_reached) - [`lead_call_in_progress`](/errors/lead_call_in_progress) - [`number_on_dnc`](/errors/number_on_dnc) - [`lead_has_no_campaign`](/errors/lead_has_no_campaign) - [`parameter_invalid`](/errors/parameter_invalid) - [`campaign_daily_cap_reached`](/errors/campaign_daily_cap_reached) - [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) - [`dial_failed`](/errors/dial_failed) # List custom lead fields (/api-reference/leads/listLeadFields) ## GET /api/v1/lead-fields/catalog Operation ID: `listLeadFields` List custom lead fields Every custom field defined in the workspace. Send values for these keys in a lead's `attributes` object on createLead and updateLead; pushLead takes them as top-level fields. `valueType` says how they are stored and compared in audience rules. ### Responses #### 200 OK Example (example): ```json { "fields": [ { "id": "6f1c2a9e-3b7d-4e21-9c55-0d8a7b3e4f10", "key": "city", "label": "City", "valueType": "text" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List leads (/api-reference/leads/listLeads) ## GET /api/v1/leads/ Operation ID: `listLeads` List leads Newest first by default. Page with `page` and `limit`, or for deep lists pass `cursor` (empty first, then `nextCursor`): cursor pages skip the count and stay fast. Without `cursor` matches are counted up to 10,000 unless `includeTotal=true`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `page` | query | no | Page number, from 1. Ignored when `cursor` is sent. | | `limit` | query | no | Items per page, up to 200. | | `search` | query | no | Matches part of the name, phone, email, company, title or external id. | | `status` | query | no | Only leads with this pipeline status key (your workspace's statuses). | | `leadSourceId` | query | no | Only leads from this lead source. | | `campaignId` | query | no | Only leads in this campaign. | | `dateFilter` | query | no | Created since 00:00 UTC today (`today`), or since 00:00 UTC 7 days ago (`week`) or 30 days ago (`month`). `all` (or no value) applies no date filter. | | `sortBy` | query | no | | | `sortOrder` | query | no | | | `includeStats` | query | no | Add `stats` (total, byStatus, recentlyAdded, notCalled) for the filter. | | `includeTotal` | query | no | Count every match exactly. By default the count stops at 10,000 (`pagination.totalCapped` says when there are more). | | `cursor` | query | no | Empty for the first page, then the previous response's `nextCursor`. Only with the default sort (newest first); skips the count. | | `assignedTo` | query | no | `me`, `unassigned`, or a team member's user ID. | | `tag` | query | no | Only leads with this tag. | ### Responses #### 200 OK Example (example): ```json { "hasMore": false, "leads": [ { "attributes": { "city": "Pune" }, "callAttempts": 0, "callStatus": "not_called", "campaignIds": [], "campaignNames": [], "company": "Rao Traders", "createdAt": "2026-11-15T10:00:00+00:00", "dncOptOut": false, "email": "asha@example.com", "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d", "name": "Asha Rao", "phone": "+919876543210", "source": "website", "status": "new", "tags": [], "title": "Owner", "updatedAt": "2026-11-15T10:00:00+00:00" } ], "pagination": { "currentPage": 1, "hasNextPage": false, "hasPreviousPage": false, "itemsPerPage": 25, "totalCapped": false, "totalItems": 1, "totalPages": 1 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create a lead (/api-reference/leads/createLead) ## POST /api/v1/leads/ Operation ID: `createLead` Create a lead Creates one lead and optionally adds it to campaigns. The phone is stored in E.164 form (a 10-digit number gets `+91`, as in a CSV upload); a number that cannot be read is refused with `invalid_phone_number`. The number is not checked for duplicates. Values that could not be saved as sent (an unknown status, a mistyped field) come back in `warnings`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "A new lead. Every field is optional; send at least a phone number to call it.", "properties": { "attributes": { "additionalProperties": true, "description": "Profile facts, for example `{\"city\": \"Pune\"}`. Typed by your lead fields.", "title": "Attributes", "type": "object" }, "campaignIds": { "description": "Add the lead to these campaigns.", "items": { "type": "string" }, "title": "Campaignids", "type": "array" }, "company": { "default": "", "description": "Company name.", "title": "Company", "type": "string" }, "email": { "default": "", "description": "Email address.", "title": "Email", "type": "string" }, "leadSourceId": { "default": "", "description": "ID of an existing lead source.", "title": "Leadsourceid", "type": "string" }, "name": { "default": "", "description": "Full name.", "title": "Name", "type": "string" }, "notes": { "default": "", "description": "Saved as the lead's first note.", "title": "Notes", "type": "string" }, "phone": { "default": "", "description": "Phone number, saved in E.164 form: `+919876543210`, `9876543210` and `098765 43210` all save as `+919876543210` (a number without a country code is taken as Indian). A value that is not a phone number returns 422 `invalid_phone_number`.", "title": "Phone", "type": "string" }, "source": { "default": "", "description": "Free-text source label, for example `website`.", "title": "Source", "type": "string" }, "status": { "default": "new", "description": "Pipeline status key. An unknown key saves as `new` with a warning.", "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "", "description": "Job title.", "title": "Title" } }, "title": "LeadCreate", "type": "object" } ``` Example: ```json { "attributes": { "city": "Pune" }, "company": "Rao Traders", "email": "asha@example.com", "name": "Asha Rao", "phone": "9876543210" } ``` ### Responses #### 200 OK Example (example): ```json { "lead": { "attributes": { "city": "Pune" }, "callAttempts": 0, "callStatus": "not_called", "campaignIds": [], "campaignNames": [], "company": "Rao Traders", "createdAt": "2026-11-15T10:00:00+00:00", "dncOptOut": false, "email": "asha@example.com", "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d", "name": "Asha Rao", "phone": "+919876543210", "source": "website", "status": "new", "tags": [], "title": "Owner", "updatedAt": "2026-11-15T10:00:00+00:00" }, "success": true, "warnings": [] } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `campaign_not_found`. Example (Campaign not found.): ```json { "detail": "Campaign not found.", "error": { "code": "campaign_not_found", "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found", "message": "Campaign not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `invalid_phone_number`, `parameter_invalid`. Example (The phone number is not valid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "invalid_phone_number", "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number", "message": "The phone number is not valid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`campaign_not_found`](/errors/campaign_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`invalid_phone_number`](/errors/invalid_phone_number) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Act on many leads (/api-reference/leads/bulkLeadAction) ## POST /api/v1/leads/bulk Operation ID: `bulkLeadAction` Act on many leads Change status, assignee, tags or do-not-call for up to 500 leads, or delete them. IDs outside your workspace are skipped, not reported. `updated` counts the leads that changed. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "One action applied to up to 500 leads.", "properties": { "action": { "description": "`status` sets `value` as the status; `assign` assigns to user `value` (empty unassigns); `tag` / `untag` add or remove tag `value`; `dnc` / `undnc` set or clear do-not-call (`value` is the reason); `delete` deletes the leads.", "enum": [ "status", "assign", "tag", "untag", "dnc", "undnc", "delete" ], "title": "Action", "type": "string" }, "ids": { "description": "Lead IDs, 1 to 500.", "items": { "format": "uuid", "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Ids", "type": "array" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Argument for the action, see `action`.", "title": "Value" } }, "required": [ "ids", "action" ], "title": "LeadBulkAction", "type": "object" } ``` Example: ```json { "action": "tag", "ids": [ "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d" ], "value": "vip" } ``` ### Responses #### 200 OK Example (example): ```json { "success": true, "updated": 1 } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a lead (/api-reference/leads/getLead) ## GET /api/v1/leads/{lead_id} Operation ID: `getLead` Get a lead One lead with its campaigns, owner and the text of its latest notes. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | ### Responses #### 200 OK Example (example): ```json { "lead": { "attributes": { "city": "Pune" }, "callAttempts": 0, "callStatus": "not_called", "campaignIds": [], "campaignNames": [], "company": "Rao Traders", "createdAt": "2026-11-15T10:00:00+00:00", "dncOptOut": false, "email": "asha@example.com", "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d", "name": "Asha Rao", "phone": "+919876543210", "source": "website", "status": "new", "tags": [], "title": "Owner", "updatedAt": "2026-11-15T10:00:00+00:00" }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Delete a lead (/api-reference/leads/deleteLead) ## DELETE /api/v1/leads/{lead_id} Operation ID: `deleteLead` Delete a lead Permanently deletes the lead. Past calls stay in call history. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | ### Responses #### 200 OK Example (example): ```json { "message": "Lead deleted", "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Update a lead (/api-reference/leads/updateLead) ## PUT /api/v1/leads/{lead_id} Operation ID: `updateLead` Update a lead Changes only the fields you send. Send `If-Match` with the lead's `updatedAt` to refuse the write (`lead_changed`) when someone changed the lead after you read it. A new `phone` is stored in E.164 form like on create. Campaign IDs you cannot access are skipped. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `If-Match` | header | no | | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "Send only the fields to change.", "properties": { "assignedToUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A team member's user ID, or null to unassign.", "title": "Assignedtouserid" }, "attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Profile facts to set; a null value clears that fact. Other facts stay.", "title": "Attributes" }, "campaignIds": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "Replaces the lead's campaigns: campaigns missing from the list are removed.", "title": "Campaignids" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name.", "title": "Company" }, "dismissIssues": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "Attribute keys whose kept-aside values (`attributeIssues`) should be dropped.", "title": "Dismississues" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address.", "title": "Email" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "description": "Your business id for this person.", "title": "Externalid" }, "leadSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of a lead source, or empty to clear.", "title": "Leadsourceid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name.", "title": "Name" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deprecated: adds one note (never replaces notes). Use `POST /leads/{leadId}/notes`.", "title": "Notes" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number, saved in E.164 form: `+919876543210`, `9876543210` and `098765 43210` all save as `+919876543210` (a number without a country code is taken as Indian). A value that is not a phone number returns 422 `invalid_phone_number`.", "title": "Phone" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text source label.", "title": "Source" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline status key.", "title": "Status" }, "tags": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "Replaces the lead's tags.", "title": "Tags" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone such as `Asia/Kolkata` for dial windows.", "title": "Timezone" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title.", "title": "Title" } }, "title": "LeadUpdate", "type": "object" } ``` Example: ```json { "attributes": { "city": "Mumbai" }, "status": "qualified", "tags": [ "vip" ] } ``` ### Responses #### 200 OK Schema: ```json { "additionalProperties": true, "description": "The lead after the change.", "properties": { "lead": { "additionalProperties": true, "description": "A person you can call, with their latest call state and profile facts.", "properties": { "assignedToUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Team member who owns the lead, or null.", "title": "Assignedtouserid" }, "assigneeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "That team member's name.", "title": "Assigneename" }, "attributeIssues": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Values that did not fit their field's type, kept aside: `{key: {raw, reason, at}}`.", "title": "Attributeissues" }, "attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Current profile facts, for example `{\"ward_no\": \"8\", \"age\": 31}`.", "title": "Attributes" }, "callAttempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calls attempted so far.", "title": "Callattempts" }, "callStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest dialing state, for example `not_called`, `calling`, `called`, `no_answer`.", "title": "Callstatus" }, "campaignCallStatus": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Per-campaign dialing state keyed by campaign ID: status, attempts, lastAttempt, nextScheduled.", "title": "Campaigncallstatus" }, "campaignIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Campaigns the lead is in.", "title": "Campaignids" }, "campaignNames": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Names of those campaigns, same order.", "title": "Campaignnames" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name.", "title": "Company" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the lead was created.", "format": "date-time", "title": "Createdat" }, "dncOptOut": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when the number must never be dialed.", "title": "Dncoptout" }, "dncReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the lead is on do-not-call.", "title": "Dncreason" }, "dncUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When do-not-call last changed.", "format": "date-time", "title": "Dncupdatedat" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address.", "title": "Email" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your business id (EPIC, patient id, order id). Unique inside a lead source.", "title": "Externalid" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead ID.", "title": "Id" }, "lastCallAttempt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the last call was attempted.", "format": "date-time", "title": "Lastcallattempt" }, "lastContactDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last time the lead was reached.", "format": "date-time", "title": "Lastcontactdate" }, "leadSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead source the lead belongs to, or empty.", "title": "Leadsourceid" }, "merchantOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Outcome of the latest result, for example `interested`, `callback` or `no_answer`.", "title": "Merchantoutcome" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name.", "title": "Name" }, "nextCallScheduled": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the next automatic attempt is due.", "format": "date-time", "title": "Nextcallscheduled" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deprecated: use the notes endpoints. The latest 20 notes as text, newest first; only on single-lead responses.", "title": "Notes" }, "notesCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Live notes on the lead.", "title": "Notescount" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number as stored.", "title": "Phone" }, "pinnedNotePreview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the newest pinned note.", "title": "Pinnednotepreview" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the lead came from.", "title": "Source" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline status key, one of your workspace's statuses (default `new`).", "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tags on the lead.", "title": "Tags" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title.", "title": "Title" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last change. Send it as `If-Match` on update to avoid overwriting someone's edit.", "format": "date-time", "title": "Updatedat" } }, "title": "Lead", "type": "object" }, "success": { "default": true, "description": "Always true on a 2xx response.", "title": "Success", "type": "boolean" }, "warnings": { "anyOf": [ { "items": { "additionalProperties": true, "description": "A value that was not saved as sent; the rest of the write succeeded.", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Field key, for example `status` or an attribute key.", "title": "Key" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Field label.", "title": "Label" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What happened to the value.", "title": "Reason" }, "value": { "description": "The value you sent.", "title": "Value" } }, "title": "FieldWarning", "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Values saved differently than sent (for example an unknown status).", "title": "Warnings" } }, "required": [ "lead" ], "title": "LeadResult", "type": "object" } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `lead_changed`. Example (This lead changed since you opened it.): ```json { "detail": "This lead changed since you opened it.", "error": { "code": "lead_changed", "docUrl": "https://docs.callmitra.ai/errors/lead_changed", "message": "This lead changed since you opened it.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `invalid_phone_number`, `parameter_invalid`. Example (The phone number is not valid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "invalid_phone_number", "docUrl": "https://docs.callmitra.ai/errors/invalid_phone_number", "message": "The phone number is not valid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`lead_changed`](/errors/lead_changed) - [`invalid_phone_number`](/errors/invalid_phone_number) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Lead timeline (/api-reference/leads/getLeadTimeline) ## GET /api/v1/leads/{lead_id}/timeline Operation ID: `getLeadTimeline` Lead timeline Calls, WhatsApp messages and orders, tickets, notes, lead changes and callbacks for one lead, newest first. Page with `cursor`; the first page also lists open callbacks. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `cursor` | query | no | `nextCursor` from the previous page. | | `limit` | query | no | Items per page, 1 to 100 (default 30). | | `types` | query | no | Comma list of `call`, `whatsapp`, `ticket`, `note`, `change`, `callback`. | ### Responses #### 200 OK Schema: ```json { "additionalProperties": true, "description": "One page of a lead's timeline, newest first.", "properties": { "hasMore": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when another page follows.", "title": "Hasmore" }, "items": { "description": "Events on this page.", "items": { "additionalProperties": true, "description": "One event on a lead's timeline.", "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it happened.", "format": "date-time", "title": "At" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detail text: call summary, message text, note body.", "title": "Body" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path of the matching console page, when there is one.", "title": "Href" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the call, message, note or other source row.", "title": "Id" }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Source-specific fields, such as call status.", "title": "Meta" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One-line summary, for example `Outbound call · 2m 05s`.", "title": "Title" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source: `call`, `whatsapp`, `order`, `ticket`, `note`, `change` or `callback`.", "title": "Type" } }, "title": "TimelineItem", "type": "object" }, "title": "Items", "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last.", "title": "Nextcursor" }, "success": { "default": true, "description": "Always true on a 2xx response.", "title": "Success", "type": "boolean" }, "upcomingCallbacks": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "First page only: open callbacks and reminders, soonest first (callbackId, kind, channel, status, dueAt, dialAt, purpose, note, overdue).", "title": "Upcomingcallbacks" } }, "required": [ "items" ], "title": "LeadTimeline", "type": "object" } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List do-not-call numbers (/api-reference/do-not-call/listDoNotCall) ## GET /api/v1/leads/dnc Operation ID: `listDoNotCall` List do-not-call numbers The 500 most recently changed leads marked do-not-call, newest first. The list stops at 500 entries; `hasMore` is true when older entries were left out. The dialer never calls these numbers. ### Responses #### 200 OK Example (example): ```json { "entries": [ { "createdAt": "2026-11-01T09:30:00Z", "dncOptOut": true, "dncReason": "Asked not to be called", "dncUpdatedAt": "2026-11-15T10:00:00Z", "id": "5d2f8a1e-3b4c-4d6e-9f0a-1b2c3d4e5f60", "name": "Asha Rao", "phone": "+919876543210", "status": "new" } ], "hasMore": false, "success": true, "total": 1 } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Add numbers to do-not-call (/api-reference/do-not-call/addDoNotCall) ## POST /api/v1/leads/dnc Operation ID: `addDoNotCall` Add numbers to do-not-call Marks existing leads with these numbers as do-not-call and creates entries for new numbers. Numbers that are not Indian mobiles are skipped; if none is valid the request fails with `dnc_no_valid_numbers`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "Numbers to put on the do-not-call list.", "properties": { "phones": { "description": "Indian mobile numbers, one per line or separated by commas. Invalid ones are skipped.", "maxLength": 20000, "minLength": 8, "title": "Phones", "type": "string" }, "reason": { "default": "", "description": "Why, shown on each entry.", "maxLength": 255, "title": "Reason", "type": "string" } }, "required": [ "phones" ], "title": "DncAdd", "type": "object" } ``` Example: ```json { "phones": "9876543210\n+919812345678", "reason": "Asked not to be called" } ``` ### Responses #### 200 OK Example (example): ```json { "added": 1, "entries": [ { "createdAt": "2026-11-01T09:30:00Z", "dncOptOut": true, "dncReason": "Asked not to be called", "dncUpdatedAt": "2026-11-15T10:00:00Z", "id": "5d2f8a1e-3b4c-4d6e-9f0a-1b2c3d4e5f60", "name": "Asha Rao", "phone": "+919876543210", "status": "new" }, { "createdAt": "2026-11-01T09:30:00Z", "dncOptOut": true, "dncReason": "Asked not to be called", "dncUpdatedAt": "2026-11-15T10:00:00Z", "id": "6e3a9b2f-4c5d-4e7f-8a1b-2c3d4e5f6a71", "name": "", "phone": "+919812345678", "status": "new" } ], "success": true, "updated": 1 } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `dnc_no_valid_numbers`, `parameter_invalid`. Example (Add at least one Indian mobile number.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "dnc_no_valid_numbers", "docUrl": "https://docs.callmitra.ai/errors/dnc_no_valid_numbers", "message": "Add at least one Indian mobile number.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`dnc_no_valid_numbers`](/errors/dnc_no_valid_numbers) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Remove a number from do-not-call (/api-reference/do-not-call/removeDoNotCall) ## DELETE /api/v1/leads/dnc/{lead_id} Operation ID: `removeDoNotCall` Remove a number from do-not-call Clears the do-not-call flag on the lead so campaigns may call it again. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | ID of the lead (entry) to clear. | ### Responses #### 200 OK Example (example): ```json { "lead": { "createdAt": "2026-11-01T09:30:00Z", "dncOptOut": false, "dncUpdatedAt": "2026-11-15T10:00:00Z", "id": "5d2f8a1e-3b4c-4d6e-9f0a-1b2c3d4e5f60", "name": "Asha Rao", "phone": "+919876543210", "status": "new" }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List a lead's notes (/api-reference/lead-notes/listLeadNotes) ## GET /api/v1/leads/{lead_id}/notes Operation ID: `listLeadNotes` List a lead's notes The first page carries the lead's summary note (`brief`) and pinned notes; `items` are the other notes, newest first. Follow `nextCursor` for older notes. Replaces the deprecated `notes` text field. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `view` | query | no | `all`, `mine` (notes you wrote), `ai` (AI-written) or `imported`. | | `cursor` | query | no | `nextCursor` from the previous page. | | `limit` | query | no | Items per page, 1 to 50 (default 30). | ### Responses #### 200 OK Example (example): ```json { "hasMore": false, "items": [ { "authorKind": "api", "body": "Asked for a call back after 6pm.", "createdAt": "2026-05-04T10:15:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": false, "updatedAt": "2026-05-04T10:15:00Z", "version": 1 } ], "notesCount": 2, "pinned": [ { "authorKind": "api", "body": "Asked for a call back after 6pm.", "createdAt": "2026-05-04T10:15:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": true, "pinnedAt": "2026-05-04T11:05:00Z", "updatedAt": "2026-05-04T10:15:00Z", "version": 2 } ] } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Add a note (/api-reference/lead-notes/createLeadNote) ## POST /api/v1/leads/{lead_id}/notes Operation ID: `createLeadNote` Add a note A note added with an API key is authored `api` and is kept like a note a person wrote. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "A new note.", "properties": { "body": { "description": "Note text, up to 10000 characters.", "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "kind": { "default": "note", "description": "`note`, or `follow_up` for a to-do.", "enum": [ "note", "follow_up" ], "title": "Kind", "type": "string" } }, "required": [ "body" ], "title": "LeadNoteCreate", "type": "object" } ``` Example: ```json { "body": "Asked for a call back after 6pm.", "kind": "note" } ``` ### Responses #### 201 OK Example (example): ```json { "note": { "authorKind": "api", "body": "Asked for a call back after 6pm.", "createdAt": "2026-05-04T10:15:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": false, "updatedAt": "2026-05-04T10:15:00Z", "version": 1 }, "notesCount": 4, "success": true } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Edit a note (/api-reference/lead-notes/updateLeadNote) ## PATCH /api/v1/leads/{lead_id}/notes/{note_id} Operation ID: `updateLeadNote` Edit a note Send the `version` you read. If someone changed the note since, you get 409 `lead_note_changed` with the current note in `detail.note`. Only the author or a workspace manager can edit a person's note. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `note_id` | path | yes | Note ID, from `GET /leads/{leadId}/notes`. | ### Request body `application/json` (required) ```json { "description": "New text for a note.", "properties": { "body": { "description": "Note text, up to 10000 characters.", "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "version": { "description": "The note's `version` when you read it.", "minimum": 1, "title": "Version", "type": "integer" } }, "required": [ "body", "version" ], "title": "LeadNoteEdit", "type": "object" } ``` Example: ```json { "body": "Call back after 6pm on weekdays.", "version": 1 } ``` ### Responses #### 200 OK Example (example): ```json { "note": { "authorKind": "api", "body": "Call back after 6pm on weekdays.", "createdAt": "2026-05-04T10:15:00Z", "editedAt": "2026-05-04T11:00:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": false, "updatedAt": "2026-05-04T11:00:00Z", "version": 2 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`, `lead_note_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Note not found.): ```json { "detail": "Note not found.", "error": { "code": "lead_note_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_note_not_found", "message": "Note not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `lead_note_changed`. Example (This note was changed by someone else.): ```json { "detail": "This note was changed by someone else.", "error": { "code": "lead_note_changed", "docUrl": "https://docs.callmitra.ai/errors/lead_note_changed", "message": "This note was changed by someone else.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`lead_note_not_found`](/errors/lead_note_not_found) - [`lead_note_changed`](/errors/lead_note_changed) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Delete a note (/api-reference/lead-notes/deleteLeadNote) ## DELETE /api/v1/leads/{lead_id}/notes/{note_id} Operation ID: `deleteLeadNote` Delete a note Only the author or a workspace manager can delete a person's note. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `note_id` | path | yes | Note ID, from `GET /leads/{leadId}/notes`. | ### Responses #### 200 OK Example (example): ```json { "notesCount": 3, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`, `lead_note_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Note not found.): ```json { "detail": "Note not found.", "error": { "code": "lead_note_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_note_not_found", "message": "Note not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`lead_note_not_found`](/errors/lead_note_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Pin a note (/api-reference/lead-notes/pinLeadNote) ## POST /api/v1/leads/{lead_id}/notes/{note_id}/pin Operation ID: `pinLeadNote` Pin a note At most three notes per lead can be pinned; a fourth returns 409 `lead_note_pin_limit`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `note_id` | path | yes | Note ID, from `GET /leads/{leadId}/notes`. | ### Responses #### 200 OK Example (example): ```json { "note": { "authorKind": "api", "body": "Asked for a call back after 6pm.", "createdAt": "2026-05-04T10:15:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": true, "pinnedAt": "2026-05-04T11:05:00Z", "updatedAt": "2026-05-04T10:15:00Z", "version": 2 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`, `lead_note_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Note not found.): ```json { "detail": "Note not found.", "error": { "code": "lead_note_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_note_not_found", "message": "Note not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `lead_note_pin_limit`. Example (A lead can have at most 3 pinned notes.): ```json { "detail": "A lead can have at most 3 pinned notes.", "error": { "code": "lead_note_pin_limit", "docUrl": "https://docs.callmitra.ai/errors/lead_note_pin_limit", "message": "A lead can have at most 3 pinned notes.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`lead_note_not_found`](/errors/lead_note_not_found) - [`lead_note_pin_limit`](/errors/lead_note_pin_limit) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Unpin a note (/api-reference/lead-notes/unpinLeadNote) ## DELETE /api/v1/leads/{lead_id}/notes/{note_id}/pin Operation ID: `unpinLeadNote` Unpin a note ### Parameters | Name | In | Required | Description | |---|---|---|---| | `lead_id` | path | yes | Lead ID. | | `note_id` | path | yes | Note ID, from `GET /leads/{leadId}/notes`. | ### Responses #### 200 OK Example (example): ```json { "note": { "authorKind": "api", "body": "Asked for a call back after 6pm.", "createdAt": "2026-05-04T10:15:00Z", "id": "8a1f3c2e-5b7d-4e0a-9c61-2d4b8e7f0a13", "kind": "note", "leadId": "3f2c9d6e-1a4b-4c8d-9e0f-7a6b5c4d3e21", "pinned": false, "updatedAt": "2026-05-04T10:15:00Z", "version": 3 }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `lead_not_found`, `lead_note_not_found`. Example (Lead not found.): ```json { "detail": "Lead not found.", "error": { "code": "lead_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_not_found", "message": "Lead not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Note not found.): ```json { "detail": "Note not found.", "error": { "code": "lead_note_not_found", "docUrl": "https://docs.callmitra.ai/errors/lead_note_not_found", "message": "Note not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`lead_not_found`](/errors/lead_not_found) - [`lead_note_not_found`](/errors/lead_note_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List phone numbers (/api-reference/phone-numbers/listPhoneNumbers) ## GET /api/v1/phone-numbers/ Operation ID: `listPhoneNumbers` List phone numbers Every number in your workspace with its carrier, call capacity and the agent using it. Credentials are never returned, only whether each one is saved. ### Responses #### 200 OK Example (example): ```json { "phoneNumbers": [ { "assignedAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "assignedAgentName": "Priya - Sales", "e164": "+918065522999", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "inboundAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "label": "Main line", "lastSyncedAt": "2026-01-15T09:30:00+00:00", "maxConcurrentCalls": 50, "metadata": {}, "name": "Main line", "number": "+918065522999", "plivoAuthTokenSet": true, "provider": "plivo", "providerResourceId": "MAXXXXXXXXXXXXXXXXXX", "sipDomain": "", "sipOutboundProxy": "", "sipPasswordSet": false, "sipUsername": "", "twilioAccountSid": "", "twilioAuthTokenSet": false, "vobizAuthTokenSet": false } ], "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a phone number (/api-reference/phone-numbers/getPhoneNumber) ## GET /api/v1/phone-numbers/{phone_id} Operation ID: `getPhoneNumber` Get a phone number One number with its carrier, call capacity and the agent using it. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `phone_id` | path | yes | The number's `id` from `GET /phone-numbers`. | ### Responses #### 200 OK Example (example): ```json { "phoneNumber": { "assignedAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "assignedAgentName": "Priya - Sales", "e164": "+918065522999", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "inboundAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "label": "Main line", "lastSyncedAt": "2026-01-15T09:30:00+00:00", "maxConcurrentCalls": 50, "metadata": {}, "name": "Main line", "number": "+918065522999", "plivoAuthTokenSet": true, "provider": "plivo", "providerResourceId": "MAXXXXXXXXXXXXXXXXXX", "sipDomain": "", "sipOutboundProxy": "", "sipPasswordSet": false, "sipUsername": "", "twilioAccountSid": "", "twilioAuthTokenSet": false, "vobizAuthTokenSet": false }, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `phone_number_not_found`. Example (Phone number not found.): ```json { "detail": "Phone number not found.", "error": { "code": "phone_number_not_found", "docUrl": "https://docs.callmitra.ai/errors/phone_number_not_found", "message": "Phone number not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`phone_number_not_found`](/errors/phone_number_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List SIP trunks (/api-reference/phone-numbers/listSipTrunks) ## GET /api/v1/sip-trunks Operation ID: `listSipTrunks` List SIP trunks Your own SIP providers connected to the calling gateway, the numbers on each, and the gateway address to give your provider. Passwords are never returned. ### Responses #### 200 OK Example (example): ```json { "gateway": { "allowIp": "sip.callmitra.example", "enabled": true, "host": "sip.callmitra.example", "inboundUri": "sip:@sip.callmitra.example:5060", "port": 5060 }, "success": true, "trunks": [ { "authMode": "digest", "authRealm": "", "codecs": [ "ulaw", "alaw" ], "dtmfMode": "rfc4733", "fromDomain": "", "fromUser": "", "hasPassword": true, "host": "sip.provider.example", "id": "5b0c2d4e-8f1a-4b3c-9d2e-7f6a5b4c3d21", "inboundIps": [ "203.0.113.10" ], "isActive": true, "lastError": "", "maxConcurrentCalls": 10, "name": "Acme SIP", "numberFormat": "e164", "numbers": [ { "e164": "+918045671234", "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "inboundAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "label": "Support line" } ], "outboundProxy": "", "port": 5060, "register": true, "status": "active", "syncedAt": "2026-11-12T09:30:00Z", "techPrefix": "", "transport": "udp", "username": "acme01" } ] } ``` #### 400 Bad request: `workspace_required`. Example (Merchant workspace required): ```json { "detail": "Merchant workspace required", "error": { "code": "workspace_required", "docUrl": "https://docs.callmitra.ai/errors/workspace_required", "message": "Merchant workspace required", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`workspace_required`](/errors/workspace_required) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a SIP trunk (/api-reference/phone-numbers/getSipTrunk) ## GET /api/v1/sip-trunks/{trunk_id} Operation ID: `getSipTrunk` Get a SIP trunk One SIP trunk with its settings, sync status and numbers. The password is never returned. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `trunk_id` | path | yes | The trunk's `id` from `GET /sip-trunks`. | ### Responses #### 200 OK Example (example): ```json { "success": true, "trunk": { "authMode": "digest", "authRealm": "", "codecs": [ "ulaw", "alaw" ], "dtmfMode": "rfc4733", "fromDomain": "", "fromUser": "", "hasPassword": true, "host": "sip.provider.example", "id": "5b0c2d4e-8f1a-4b3c-9d2e-7f6a5b4c3d21", "inboundIps": [ "203.0.113.10" ], "isActive": true, "lastError": "", "maxConcurrentCalls": 10, "name": "Acme SIP", "numberFormat": "e164", "numbers": [ { "e164": "+918045671234", "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "inboundAgentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23", "label": "Support line" } ], "outboundProxy": "", "port": 5060, "register": true, "status": "active", "syncedAt": "2026-11-12T09:30:00Z", "techPrefix": "", "transport": "udp", "username": "acme01" } } ``` #### 400 Bad request: `workspace_required`. Example (Merchant workspace required): ```json { "detail": "Merchant workspace required", "error": { "code": "workspace_required", "docUrl": "https://docs.callmitra.ai/errors/workspace_required", "message": "Merchant workspace required", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `sip_trunk_not_found`. Example (SIP trunk not found.): ```json { "detail": "SIP trunk not found.", "error": { "code": "sip_trunk_not_found", "docUrl": "https://docs.callmitra.ai/errors/sip_trunk_not_found", "message": "SIP trunk not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`workspace_required`](/errors/workspace_required) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`sip_trunk_not_found`](/errors/sip_trunk_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List tickets (/api-reference/tickets/listTickets) ## GET /api/v1/tickets/ Operation ID: `listTickets` List tickets Newest change first by default. Filter by status, type, priority, lead, category, team or tag. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `page` | query | no | Page number, from 1. | | `limit` | query | no | Tickets per page (1-200). | | `search` | query | no | Ticket ref, words in the subject or description, or the lead's name or phone. | | `status` | query | no | `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`; `open` also matches `in_progress` and `waiting_on_customer`. | | `type` | query | no | `support` or `sales_followup`. | | `leadId` | query | no | Only this lead's tickets. | | `sourceCallId` | query | no | Only tickets opened from this call. | | `unassigned` | query | no | Only tickets nobody is assigned to. | | `priority` | query | no | `low`, `normal`, `high` or `urgent`. | | `tag` | query | no | Only tickets with this tag. | | `categoryId` | query | no | Category id, or `none` for tickets without one. | | `teamId` | query | no | Team id, or `none` for tickets without one. | | `sort` | query | no | `updated` (default), `created`, `due`, `priority` or `status`. | | `dir` | query | no | `asc` or `desc`. | ### Responses #### 200 OK Example (example): ```json { "pagination": { "currentPage": 1, "hasNextPage": false, "hasPreviousPage": false, "itemsPerPage": 25, "totalCapped": false, "totalItems": 1, "totalPages": 1 }, "sort": { "dir": "desc", "key": "updated" }, "success": true, "tickets": [ { "activityCount": 1, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "normal", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "open", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T09:30:00+00:00", "version": 1 } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Create a ticket (/api-reference/tickets/createTicket) ## POST /api/v1/tickets/ Operation ID: `createTicket` Create a ticket Opens a ticket for `leadId` (or the lead behind `waConversationId`). Category and source decide its team; the team's rules may assign it automatically. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "properties": { "assignedToUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assign one team member (user id).", "title": "Assignedtouserid" }, "assignedUserIds": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "Assign several team members; wins over `assignedToUserId`.", "title": "Assigneduserids" }, "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category id from `GET /tickets/categories`.", "title": "Categoryid" }, "description": { "default": "", "description": "Details.", "maxLength": 20000, "title": "Description", "type": "string" }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolution due time (ISO 8601).", "title": "Dueat" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The lead (customer) the ticket is about.", "title": "Leadid" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`low`, `normal`, `high` or `urgent`. Default: the category's priority, else `normal`.", "title": "Priority" }, "sourceCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The call this ticket came from.", "title": "Sourcecallid" }, "subject": { "description": "One-line summary.", "maxLength": 512, "minLength": 1, "title": "Subject", "type": "string" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "description": "Up to 20 tags.", "title": "Tags" }, "type": { "default": "support", "description": "`support` or `sales_followup`.", "title": "Type", "type": "string" }, "waConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Open it from a WhatsApp conversation instead; its contact's lead is used.", "title": "Waconversationid" } }, "required": [ "subject" ], "title": "TicketCreateBody", "type": "object" } ``` Example: ```json { "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "description": "Customer says the parcel was marked delivered but never arrived.", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ] } ``` ### Responses #### 200 OK Example (example): ```json { "success": true, "ticket": { "activities": [ { "activityType": "created", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T09:30:00+00:00", "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "payload": { "category": "Delivery", "priority": "normal", "subject": "Order #1042 not delivered", "team": "Customer care", "type": "support" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "activityCount": 1, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "canEdit": true, "canManageAssignees": true, "canReopenClosed": false, "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "hasOlderActivities": false, "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "normal", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "open", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T09:30:00+00:00", "version": 1 } } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List ticket categories (/api-reference/tickets/listTicketCategories) ## GET /api/v1/tickets/categories Operation ID: `listTicketCategories` List ticket categories Categories to file tickets under (`categoryId`), in display order. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `includeInactive` | query | no | Include categories that are switched off (default true). | ### Responses #### 200 OK Example (example): ```json { "categories": [ { "defaultPriority": "normal", "defaultTeamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "id": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "isActive": true, "name": "Delivery", "sortOrder": 0 }, { "defaultPriority": "high", "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e", "isActive": true, "name": "Refunds", "sortOrder": 1 } ], "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List ticket teams (/api-reference/tickets/listTicketTeams) ## GET /api/v1/tickets/teams Operation ID: `listTicketTeams` List ticket teams Teams tickets are routed to (`teamId`), sorted by name. ### Responses #### 200 OK Example (example): ```json { "success": true, "teams": [ { "assignmentMode": "round_robin", "id": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "isDefault": true, "members": [ { "available": true, "email": "priya@example.com", "isLead": true, "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "name": "Customer care" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Get a ticket (/api-reference/tickets/getTicket) ## GET /api/v1/tickets/{ticket_id} Operation ID: `getTicket` Get a ticket The ticket with its latest activities (notes, replies and changes). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `ticket_id` | path | yes | Ticket id. | ### Responses #### 200 OK Example (example): ```json { "success": true, "ticket": { "activities": [ { "activityType": "priority_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T10:05:00+00:00", "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "payload": { "from": "normal", "to": "high" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" }, { "activityType": "status_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T10:05:00+00:00", "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "payload": { "from": "open", "source": "console", "to": "in_progress" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" }, { "activityType": "status_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T11:20:00+00:00", "id": "5f6a7b8c-9d0e-4f1a-9b2c-4d5e6f7a8b9d", "payload": { "from": "in_progress", "source": "console", "to": "waiting_on_customer" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" }, { "activityType": "comment", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T11:20:00+00:00", "id": "3d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f7a", "payload": { "note": "Courier confirmed the parcel is at the local hub; asked them to redeliver tomorrow." }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "activitiesCursor": "2026-01-15T10:05:00+00:00|2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "activityCount": 5, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "canEdit": true, "canManageAssignees": true, "canReopenClosed": false, "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "hasOlderActivities": true, "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "high", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "waiting_on_customer", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T11:20:00+00:00", "version": 3 } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Update a ticket (/api-reference/tickets/updateTicket) ## PATCH /api/v1/tickets/{ticket_id} Operation ID: `updateTicket` Update a ticket Changes only the fields you send. Send `version` to make sure you do not overwrite someone's change. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `ticket_id` | path | yes | Ticket id. | ### Request body `application/json` (required) ```json { "properties": { "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category id; `null` clears it.", "title": "Categoryid" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Details.", "title": "Description" }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolution due time (ISO 8601).", "title": "Dueat" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`low`, `normal`, `high` or `urgent`.", "title": "Priority" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`. Reopening a closed ticket needs a manager.", "title": "Status" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One-line summary.", "title": "Subject" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "description": "Replaces the tags (up to 20).", "title": "Tags" }, "teamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Team id; `null` takes the ticket out of its team.", "title": "Teamid" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`support` or `sales_followup`.", "title": "Type" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The `version` you last read; if the ticket changed since, the request fails with 409. Leave out to skip.", "title": "Version" } }, "title": "TicketUpdateBody", "type": "object" } ``` Example: ```json { "priority": "high", "status": "in_progress", "version": 1 } ``` ### Responses #### 200 OK Example (example): ```json { "activities": [ { "activityType": "priority_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T10:05:00+00:00", "id": "2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f", "payload": { "from": "normal", "to": "high" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" }, { "activityType": "status_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T10:05:00+00:00", "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "payload": { "from": "open", "source": "console", "to": "in_progress" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "changed": [ "priority", "status" ], "success": true, "ticket": { "activityCount": 3, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "canEdit": true, "canManageAssignees": true, "canReopenClosed": false, "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "high", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "in_progress", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T10:05:00+00:00", "version": 2 } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `ticket_edit_forbidden`, `ticket_reopen_forbidden`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You can only update tickets assigned to you or unassigned.): ```json { "detail": "You can only update tickets assigned to you or unassigned.", "error": { "code": "ticket_edit_forbidden", "docUrl": "https://docs.callmitra.ai/errors/ticket_edit_forbidden", "message": "You can only update tickets assigned to you or unassigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (Only a manager can reopen a closed ticket.): ```json { "detail": "Only a manager can reopen a closed ticket.", "error": { "code": "ticket_reopen_forbidden", "docUrl": "https://docs.callmitra.ai/errors/ticket_reopen_forbidden", "message": "Only a manager can reopen a closed ticket.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `ticket_merged`, `ticket_version_conflict`. Example (The ticket was merged into another ticket.): ```json { "detail": "The ticket was merged into another ticket.", "error": { "code": "ticket_merged", "docUrl": "https://docs.callmitra.ai/errors/ticket_merged", "message": "The ticket was merged into another ticket.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The ticket was changed since you read it.): ```json { "detail": "The ticket was changed since you read it.", "error": { "code": "ticket_version_conflict", "docUrl": "https://docs.callmitra.ai/errors/ticket_version_conflict", "message": "The ticket was changed since you read it.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden) - [`ticket_reopen_forbidden`](/errors/ticket_reopen_forbidden) - [`resource_not_found`](/errors/resource_not_found) - [`ticket_merged`](/errors/ticket_merged) - [`ticket_version_conflict`](/errors/ticket_version_conflict) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # List ticket activities (/api-reference/tickets/listTicketActivities) ## GET /api/v1/tickets/{ticket_id}/activities Operation ID: `listTicketActivities` List ticket activities Older activities of a ticket, page by page: pass the previous page's `activitiesCursor` as `before`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `ticket_id` | path | yes | Ticket id. | | `before` | query | no | `activitiesCursor` from the ticket or the previous page. | | `limit` | query | no | Activities per page. | ### Responses #### 200 OK Example (example): ```json { "activities": [ { "activityType": "created", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T09:30:00+00:00", "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "payload": { "category": "Delivery", "priority": "normal", "subject": "Order #1042 not delivered", "team": "Customer care", "type": "support" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "hasOlderActivities": false, "success": true } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Add a note to a ticket (/api-reference/tickets/addTicketNote) ## POST /api/v1/tickets/{ticket_id}/activities Operation ID: `addTicketNote` Add a note to a ticket A note your team sees on the ticket; the customer does not. Optionally moves the ticket's status. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `ticket_id` | path | yes | Ticket id. | | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "description": "A private team note, never sent to the customer; a note may be just attachments.", "properties": { "attachmentIds": { "description": "Files already uploaded to the ticket (console only).", "items": { "type": "string" }, "maxItems": 5, "title": "Attachmentids", "type": "array" }, "note": { "default": "", "description": "Note text, visible to your team only.", "maxLength": 8000, "title": "Note", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Also move the ticket to this status: `open`, `in_progress`, `waiting_on_customer`, `resolved` or `closed`.", "title": "Status" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The `version` you last read; if the ticket changed since, the request fails with 409. Leave out to skip.", "title": "Version" } }, "title": "TicketActivityBody", "type": "object" } ``` Example: ```json { "note": "Courier confirmed the parcel is at the local hub; asked them to redeliver tomorrow.", "status": "waiting_on_customer", "version": 2 } ``` ### Responses #### 200 OK Example (example): ```json { "activities": [ { "activityType": "status_change", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T11:20:00+00:00", "id": "5f6a7b8c-9d0e-4f1a-9b2c-4d5e6f7a8b9d", "payload": { "from": "in_progress", "source": "console", "to": "waiting_on_customer" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" }, { "activityType": "comment", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T11:20:00+00:00", "id": "3d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f7a", "payload": { "note": "Courier confirmed the parcel is at the local hub; asked them to redeliver tomorrow." }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "changed": [ "status", "activities" ], "success": true, "ticket": { "activityCount": 5, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "canEdit": true, "canManageAssignees": true, "canReopenClosed": false, "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "high", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "waiting_on_customer", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T11:20:00+00:00", "version": 3 } } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `ticket_edit_forbidden`, `ticket_reopen_forbidden`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You can only update tickets assigned to you or unassigned.): ```json { "detail": "You can only update tickets assigned to you or unassigned.", "error": { "code": "ticket_edit_forbidden", "docUrl": "https://docs.callmitra.ai/errors/ticket_edit_forbidden", "message": "You can only update tickets assigned to you or unassigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (Only a manager can reopen a closed ticket.): ```json { "detail": "Only a manager can reopen a closed ticket.", "error": { "code": "ticket_reopen_forbidden", "docUrl": "https://docs.callmitra.ai/errors/ticket_reopen_forbidden", "message": "Only a manager can reopen a closed ticket.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `ticket_attachment_unavailable`, `ticket_merged`, `ticket_version_conflict`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (An attachment was already sent or removed.): ```json { "detail": "An attachment was already sent or removed.", "error": { "code": "ticket_attachment_unavailable", "docUrl": "https://docs.callmitra.ai/errors/ticket_attachment_unavailable", "message": "An attachment was already sent or removed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The ticket was merged into another ticket.): ```json { "detail": "The ticket was merged into another ticket.", "error": { "code": "ticket_merged", "docUrl": "https://docs.callmitra.ai/errors/ticket_merged", "message": "The ticket was merged into another ticket.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The ticket was changed since you read it.): ```json { "detail": "The ticket was changed since you read it.", "error": { "code": "ticket_version_conflict", "docUrl": "https://docs.callmitra.ai/errors/ticket_version_conflict", "message": "The ticket was changed since you read it.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden) - [`ticket_reopen_forbidden`](/errors/ticket_reopen_forbidden) - [`resource_not_found`](/errors/resource_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`ticket_attachment_unavailable`](/errors/ticket_attachment_unavailable) - [`ticket_merged`](/errors/ticket_merged) - [`ticket_version_conflict`](/errors/ticket_version_conflict) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Reply to the customer (/api-reference/tickets/replyToTicket) ## POST /api/v1/tickets/{ticket_id}/replies Operation ID: `replyToTicket` Reply to the customer Sends a reply to the ticket's customer on WhatsApp. Within 24 hours of the customer's last message send `text`; after that send `templateEvent` to use the approved template set up for that ticket event. The reply is queued and recorded on the ticket. Retrying with the same `clientId` returns the first reply (with `replayed: true`) instead of sending again. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `ticket_id` | path | yes | Ticket id. | ### Request body `application/json` (required) ```json { "properties": { "attachmentIds": { "description": "Files already uploaded to the ticket (console only).", "items": { "type": "string" }, "maxItems": 5, "title": "Attachmentids", "type": "array" }, "clientId": { "description": "Your unique id for this reply (8-64 chars); a retry with it never sends twice.", "maxLength": 64, "minLength": 8, "title": "Clientid", "type": "string" }, "templateEvent": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "Ticket event (e.g. `waiting_on_customer`) whose approved template to send instead of text.", "title": "Templateevent" }, "text": { "default": "", "description": "Reply text (inside the 24-hour window).", "maxLength": 4096, "title": "Text", "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The ticket `version` you last read (optional).", "title": "Version" } }, "required": [ "clientId" ], "title": "TicketReplyBody", "type": "object" } ``` Example: ```json { "clientId": "crm-reply-88213", "text": "Hi Asha, your parcel is at our local hub and will be redelivered tomorrow before 6 pm.", "version": 3 } ``` ### Responses #### 200 OK Example (example): ```json { "activities": [ { "activityType": "reply", "actorName": "Priya Nair", "actorUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "createdAt": "2026-01-15T11:25:00+00:00", "id": "4e5f6a7b-8c9d-4e0f-8a1b-3c4d5e6f7a8b", "payload": { "clientId": "crm-reply-88213", "jobIds": [ "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" ], "mode": "text", "note": "Hi Asha, your parcel is at our local hub and will be redelivered tomorrow before 6 pm.", "phoneId": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c" }, "ticketId": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90" } ], "changed": [ "activities" ], "success": true, "ticket": { "activityCount": 6, "assignedToUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "assigneeEmail": "priya@example.com", "assigneeName": "Priya Nair", "assigneeNames": [ "Priya Nair" ], "assignees": [ { "assignedAt": "2026-01-15T09:30:02+00:00", "email": "priya@example.com", "name": "Priya Nair", "userId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f" } ], "canEdit": true, "canManageAssignees": true, "canReopenClosed": false, "categoryId": "3b9f1d7e-6c2a-4e85-a0d4-7f1e2c3b4a56", "categoryName": "Delivery", "createdAt": "2026-01-15T09:30:00+00:00", "createdByUserId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "description": "Customer says the parcel was marked delivered but never arrived.", "dueAt": "2026-01-16T09:30:00+00:00", "firstResponseAt": "2026-01-15T11:25:00+00:00", "id": "5f0c9a3e-2b7d-4c61-9e84-1d6a7b3c2f90", "leadId": "a41e7c2d-8f35-4b09-b6d2-93c0e5f1a7b8", "leadName": "Asha Verma", "leadPhone": "+919812345678", "merchantId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "overdue": false, "priority": "high", "ref": "T-5F0C9A3E", "sla": { "firstResponse": { "dueAt": "2026-01-15T13:30:00+00:00", "state": "ok", "warnAt": "2026-01-15T12:30:00+00:00" }, "paused": false, "resolution": { "dueAt": "2026-01-16T09:30:00+00:00", "state": "ok", "warnAt": "2026-01-16T05:30:00+00:00" } }, "source": "manual", "status": "waiting_on_customer", "subject": "Order #1042 not delivered", "tags": [ "order-1042" ], "teamId": "e7a1c3d5-9b2f-4d68-8a0c-2e4f6a8b0c1d", "teamName": "Customer care", "type": "support", "updatedAt": "2026-01-15T11:25:00+00:00", "version": 4 } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `ticket_edit_forbidden`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You can only update tickets assigned to you or unassigned.): ```json { "detail": "You can only update tickets assigned to you or unassigned.", "error": { "code": "ticket_edit_forbidden", "docUrl": "https://docs.callmitra.ai/errors/ticket_edit_forbidden", "message": "You can only update tickets assigned to you or unassigned.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `ticket_attachment_unavailable`, `ticket_merged`, `ticket_reply_blocked`, `ticket_version_conflict`. Example (An attachment was already sent or removed.): ```json { "detail": "An attachment was already sent or removed.", "error": { "code": "ticket_attachment_unavailable", "docUrl": "https://docs.callmitra.ai/errors/ticket_attachment_unavailable", "message": "An attachment was already sent or removed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The ticket was merged into another ticket.): ```json { "detail": "The ticket was merged into another ticket.", "error": { "code": "ticket_merged", "docUrl": "https://docs.callmitra.ai/errors/ticket_merged", "message": "The ticket was merged into another ticket.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The reply cannot be sent to the customer.): ```json { "detail": "The reply cannot be sent to the customer.", "error": { "code": "ticket_reply_blocked", "docUrl": "https://docs.callmitra.ai/errors/ticket_reply_blocked", "message": "The reply cannot be sent to the customer.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The ticket was changed since you read it.): ```json { "detail": "The ticket was changed since you read it.", "error": { "code": "ticket_version_conflict", "docUrl": "https://docs.callmitra.ai/errors/ticket_version_conflict", "message": "The ticket was changed since you read it.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`ticket_edit_forbidden`](/errors/ticket_edit_forbidden) - [`resource_not_found`](/errors/resource_not_found) - [`ticket_attachment_unavailable`](/errors/ticket_attachment_unavailable) - [`ticket_merged`](/errors/ticket_merged) - [`ticket_reply_blocked`](/errors/ticket_reply_blocked) - [`ticket_version_conflict`](/errors/ticket_version_conflict) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Push a lead (/api-reference/lead-intake-webhook/pushLead) ## POST /api/v1/webhooks/leads/{webhook_token} Operation ID: `pushLead` Push a lead Send the integration key in `X-Lead-Webhook-Key` (or as `?key=`). Limited to 300 requests per minute per IP. Errors return `{"success": false, "error": "..."}`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `webhook_token` | path | yes | The token in your integration's URL. | ### Request body `application/json` (required) ```json { "additionalProperties": true, "description": "Any other top-level fields are kept on the lead as additional data. Phone or email is required.", "properties": { "company": { "type": "string" }, "email": { "type": "string" }, "is_test": { "description": "Check the connection without creating a lead.", "type": "boolean" }, "lead_id": { "description": "Your ID for this lead. A repeat with the same ID is ignored. Without it, repeats are recognised by phone, email and name.", "type": "string" }, "name": { "type": "string" }, "phone": { "description": "Phone number, for example `+919876543210`. Saved in E.164 form when it parses (no country code means India); otherwise saved as sent.", "type": "string" }, "title": { "type": "string" } }, "type": "object" } ``` Example: ```json { "city": "Pune", "email": "asha@example.com", "lead_id": "form-8812", "name": "Asha Rao", "phone": "9876543210" } ``` ### Responses #### 200 OK Example (example): ```json { "campaignAttached": true, "externalLeadId": "form-8812", "leadId": "5a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "success": true } ``` #### 400 The payload was rejected, for example no phone or email. Example (example): ```json { "error": "Lead must include phone or email", "success": false } ``` #### 401 The integration key is missing or wrong. Example (example): ```json { "error": "invalid webhook key", "success": false } ``` #### 404 No active integration has this token. Example (example): ```json { "error": "integration not found", "success": false } ``` #### 429 More than the allowed requests per minute from this IP. Example (example): ```json { "error": "rate limit", "success": false } ``` #### 500 The lead could not be saved; `error` says why. Retry: repeats are dropped. Example (example): ```json { "error": "database unavailable", "success": false } ``` # List WhatsApp templates (/api-reference/whatsapp/listWhatsAppTemplates) ## GET /api/v1/whatsapp/message-templates Operation ID: `listWhatsAppTemplates` List WhatsApp templates Templates of your WhatsApp Business accounts, to pick `template.name` and `template.language`. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `phoneId` | query | no | Only templates usable from this sending number. | | `status` | query | no | Filter by review status, e.g. `APPROVED`. | | `category` | query | no | `MARKETING`, `UTILITY` or `AUTHENTICATION`. | | `q` | query | no | Part of the template name. | ### Responses #### 200 OK Example (example): ```json { "templates": [ { "category": "UTILITY", "components": [ { "text": "Hi {{1}}, your order {{2}} is on its way.", "type": "BODY" }, { "text": "Reply STOP to opt out", "type": "FOOTER" } ], "id": "2e8d4f6a-1b3c-4d5e-9f7a-8b9c0d1e2f3a", "language": "en", "lastSyncedAt": "2026-01-15T08:00:00+00:00", "name": "order_update", "parameterFormat": "POSITIONAL", "qualityScore": "GREEN", "status": "APPROVED" } ] } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error) # Send a WhatsApp message (/api-reference/whatsapp/sendWhatsAppMessage) ## POST /api/v1/whatsapp/messages Operation ID: `sendWhatsAppMessage` Send a WhatsApp message Sends a template, text, media, interactive, location or contacts message to `to` (or `contactId`) from `phoneId` or your default number. Templates can be sent any time; every other type needs the customer to have messaged you in the last 24 hours. A refusal by WhatsApp after the message was created returns 200 with `status: failed` and `error`; a temporary refusal returns 429 or 503 with `Retry-After`, and nothing was delivered. ### Parameters | Name | In | Required | Description | |---|---|---|---| | `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. | ### Request body `application/json` (required) ```json { "properties": { "contactId": { "default": "", "description": "Id of an existing WhatsApp contact, instead of `to`.", "title": "Contactid", "type": "string" }, "content": { "description": "For `interactive`, `location` or `contacts`: the object the WhatsApp Cloud API takes under that key.", "title": "Content" }, "media": { "anyOf": [ { "properties": { "caption": { "default": "", "description": "Caption shown under an image, video or document.", "maxLength": 1024, "title": "Caption", "type": "string" }, "filename": { "default": "", "description": "File name shown for a document.", "maxLength": 240, "title": "Filename", "type": "string" }, "id": { "default": "", "description": "WhatsApp media id of a file you already uploaded.", "maxLength": 128, "title": "Id", "type": "string" }, "link": { "default": "", "description": "Public https URL of the file.", "maxLength": 2000, "title": "Link", "type": "string" } }, "title": "WhatsAppMediaRef", "type": "object" }, { "type": "null" } ], "description": "Required for media types: `link` or `id`." }, "optIn": { "anyOf": [ { "properties": { "source": { "description": "Where consent was collected, e.g. `checkout`.", "maxLength": 64, "minLength": 1, "title": "Source", "type": "string" }, "text": { "default": "", "description": "The consent wording the customer agreed to.", "maxLength": 2000, "title": "Text", "type": "string" } }, "required": [ "source" ], "title": "WhatsAppOptIn", "type": "object" }, { "type": "null" } ], "description": "Record the recipient's opt-in with this send (needed before marketing templates)." }, "phoneId": { "default": "", "description": "Your sending WhatsApp number's id. Leave out to use your default number.", "title": "Phoneid", "type": "string" }, "template": { "anyOf": [ { "properties": { "components": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Advanced: WhatsApp Cloud API `components` sent as-is instead of `values`.", "title": "Components" }, "language": { "description": "Template language code, e.g. `en` or `en_US`.", "maxLength": 16, "minLength": 2, "title": "Language", "type": "string" }, "name": { "description": "Template name exactly as approved.", "maxLength": 512, "minLength": 1, "title": "Name", "type": "string" }, "values": { "additionalProperties": true, "description": "Values for the template's variables: `body` as a list in order (or `{\"1\": ...}`), plus `header` and `buttons` when the template has them.", "title": "Values", "type": "object" } }, "required": [ "name", "language" ], "title": "WhatsAppTemplateRef", "type": "object" }, { "type": "null" } ], "description": "Required for `type=template`." }, "text": { "default": "", "description": "Message text for `type=text`.", "maxLength": 4096, "title": "Text", "type": "string" }, "to": { "default": "", "description": "Recipient in international format, e.g. `+919812345678`. Or send `contactId`.", "maxLength": 32, "title": "To", "type": "string" }, "type": { "default": "template", "description": "`template`, `text`, `image`, `video`, `audio`, `document`, `sticker`, `interactive`, `location` or `contacts`. Everything except `template` needs an open 24-hour window.", "title": "Type", "type": "string" } }, "title": "WhatsAppMessageSend", "type": "object" } ``` Example: ```json { "template": { "language": "en", "name": "order_update", "values": { "body": [ "Asha", "#1042" ] } }, "to": "+919812345678", "type": "template" } ``` ### Responses #### 200 OK Example (example): ```json { "conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44", "createdAt": "2026-01-15T09:30:00+00:00", "id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10", "status": "accepted", "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2" } ``` #### 400 Bad request: `bad_request`. Example (The request could not be processed.): ```json { "detail": "The request could not be processed.", "error": { "code": "bad_request", "docUrl": "https://docs.callmitra.ai/errors/bad_request", "message": "The request could not be processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`, `whatsapp_template_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` Example (Template not found.): ```json { "detail": "Template not found.", "error": { "code": "whatsapp_template_not_found", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_found", "message": "Template not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `whatsapp_client_message_id_reused`, `whatsapp_marketing_opted_out`, `whatsapp_number_not_connected`, `whatsapp_opt_in_required`, `whatsapp_recipient_opted_out`, `whatsapp_template_not_approved`, `whatsapp_window_closed`. Example (This Idempotency-Key was already used with a different request body.): ```json { "detail": "This Idempotency-Key was already used with a different request body.", "error": { "code": "idempotency_key_reused", "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request body.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (A request with this Idempotency-Key is still being processed.): ```json { "detail": "A request with this Idempotency-Key is still being processed.", "error": { "code": "idempotency_request_in_progress", "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still being processed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "idempotency_error" } } ``` Example (This message id was already used for a different conversation.): ```json { "detail": "This message id was already used for a different conversation.", "error": { "code": "whatsapp_client_message_id_reused", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_client_message_id_reused", "message": "This message id was already used for a different conversation.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The recipient stopped marketing messages.): ```json { "detail": "The recipient stopped marketing messages.", "error": { "code": "whatsapp_marketing_opted_out", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_marketing_opted_out", "message": "The recipient stopped marketing messages.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (No connected WhatsApp number.): ```json { "detail": "No connected WhatsApp number.", "error": { "code": "whatsapp_number_not_connected", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_number_not_connected", "message": "No connected WhatsApp number.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (Marketing templates need a recorded opt-in.): ```json { "detail": "Marketing templates need a recorded opt-in.", "error": { "code": "whatsapp_opt_in_required", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_opt_in_required", "message": "Marketing templates need a recorded opt-in.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The recipient opted out of WhatsApp messages.): ```json { "detail": "The recipient opted out of WhatsApp messages.", "error": { "code": "whatsapp_recipient_opted_out", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_recipient_opted_out", "message": "The recipient opted out of WhatsApp messages.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The template is not approved.): ```json { "detail": "The template is not approved.", "error": { "code": "whatsapp_template_not_approved", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_template_not_approved", "message": "The template is not approved.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` Example (The 24-hour customer service window is closed.): ```json { "detail": "The 24-hour customer service window is closed.", "error": { "code": "whatsapp_window_closed", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_window_closed", "message": "The 24-hour customer service window is closed.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "conflict_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`, `whatsapp_upstream_throttled`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` Example (WhatsApp is limiting messages from this number right now.): ```json { "detail": "WhatsApp is limiting messages from this number right now.", "error": { "code": "whatsapp_upstream_throttled", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_throttled", "message": "WhatsApp is limiting messages from this number right now.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` #### 503 Service unavailable: `whatsapp_upstream_unavailable`. Example (WhatsApp could not take the message right now.): ```json { "detail": "WhatsApp could not take the message right now.", "error": { "code": "whatsapp_upstream_unavailable", "docUrl": "https://docs.callmitra.ai/errors/whatsapp_upstream_unavailable", "message": "WhatsApp could not take the message right now.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`bad_request`](/errors/bad_request) - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`whatsapp_template_not_found`](/errors/whatsapp_template_not_found) - [`idempotency_key_reused`](/errors/idempotency_key_reused) - [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) - [`whatsapp_client_message_id_reused`](/errors/whatsapp_client_message_id_reused) - [`whatsapp_marketing_opted_out`](/errors/whatsapp_marketing_opted_out) - [`whatsapp_number_not_connected`](/errors/whatsapp_number_not_connected) - [`whatsapp_opt_in_required`](/errors/whatsapp_opt_in_required) - [`whatsapp_recipient_opted_out`](/errors/whatsapp_recipient_opted_out) - [`whatsapp_template_not_approved`](/errors/whatsapp_template_not_approved) - [`whatsapp_window_closed`](/errors/whatsapp_window_closed) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) - [`internal_error`](/errors/internal_error) - [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable) # Get a WhatsApp message (/api-reference/whatsapp/getWhatsAppMessage) ## GET /api/v1/whatsapp/messages/{message_id} Operation ID: `getWhatsAppMessage` Get a WhatsApp message Current delivery status of a message you sent. Poll it to follow `queued` → `sent` → `delivered` → `read` (or `failed`). ### Parameters | Name | In | Required | Description | |---|---|---|---| | `message_id` | path | yes | The `id` returned when the message was sent. | ### Responses #### 200 OK Example (example): ```json { "conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44", "createdAt": "2026-01-15T09:30:00+00:00", "id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10", "status": "delivered", "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2" } ``` #### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`. Example (The API key has expired.): ```json { "detail": "The API key has expired.", "error": { "code": "api_key_expired", "docUrl": "https://docs.callmitra.ai/errors/api_key_expired", "message": "The API key has expired.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (The API key is invalid or has been revoked.): ```json { "detail": "The API key is invalid or has been revoked.", "error": { "code": "invalid_api_key", "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key", "message": "The API key is invalid or has been revoked.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` Example (Authentication required.): ```json { "detail": "Authentication required.", "error": { "code": "unauthenticated", "docUrl": "https://docs.callmitra.ai/errors/unauthenticated", "message": "Authentication required.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "authentication_error" } } ``` #### 403 Forbidden: `api_key_scope_denied`, `permission_denied`. Example (The API key does not have the scope required for this request.): ```json { "detail": "The API key does not have the scope required for this request.", "error": { "code": "api_key_scope_denied", "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied", "message": "The API key does not have the scope required for this request.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` Example (You do not have permission to perform this action.): ```json { "detail": "You do not have permission to perform this action.", "error": { "code": "permission_denied", "docUrl": "https://docs.callmitra.ai/errors/permission_denied", "message": "You do not have permission to perform this action.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "permission_error" } } ``` #### 404 Not found: `resource_not_found`. Example (The requested resource was not found.): ```json { "detail": "The requested resource was not found.", "error": { "code": "resource_not_found", "docUrl": "https://docs.callmitra.ai/errors/resource_not_found", "message": "The requested resource was not found.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "not_found_error" } } ``` #### 422 Invalid parameters: `parameter_invalid`. Example (One or more parameters are invalid.): ```json { "detail": [ { "loc": [ "body", "phone" ], "msg": "Field required", "type": "missing" } ], "error": { "code": "parameter_invalid", "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid", "message": "One or more parameters are invalid.", "param": "phone", "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "invalid_request_error" } } ``` #### 429 Too many requests: `rate_limit_exceeded`. Example (Too many requests. Slow down and retry later.): ```json { "detail": "Too many requests. Slow down and retry later.", "error": { "code": "rate_limit_exceeded", "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded", "message": "Too many requests. Slow down and retry later.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "rate_limit_error" } } ``` #### 500 Server error: `internal_error`. Example (Something went wrong on our side.): ```json { "detail": "Something went wrong on our side.", "error": { "code": "internal_error", "docUrl": "https://docs.callmitra.ai/errors/internal_error", "message": "Something went wrong on our side.", "param": null, "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69", "type": "api_error" } } ``` ### Error codes - [`api_key_expired`](/errors/api_key_expired) - [`invalid_api_key`](/errors/invalid_api_key) - [`unauthenticated`](/errors/unauthenticated) - [`api_key_scope_denied`](/errors/api_key_scope_denied) - [`permission_denied`](/errors/permission_denied) - [`resource_not_found`](/errors/resource_not_found) - [`parameter_invalid`](/errors/parameter_invalid) - [`rate_limit_exceeded`](/errors/rate_limit_exceeded) - [`internal_error`](/errors/internal_error)