Telephony API
Rent phone numbers in India and other countries (India needs KYC), link them to a voice-agent bot, place, bridge and hang up outbound PSTN calls, and fetch recordings and transcripts — all with your cm_ key.
Overview
The Telephony API is a full lifecycle for CallMissed Numbers: pick a country, submit an India KYC (compliance) application if you want an Indian number, search available numbers, buy one (a paid action that draws your real credit balance), manage it, and place outbound PSTN calls answered by your AI voice agent.
Base path: https://api.callmissed.com/api/v1/telephony
The journey is ordered. You cannot buy an Indian number until you hold an accepted KYC application, and you cannot place a call until you own an active number. Numbers outside India need no KYC application. Follow the flow below top to bottom.
- 1
Submit KYC
Upload your business documents and details once
- 2
CallMissed
Reviews the application; poll or sync until it is
- 3
Buy & call
Search a number, buy it (paid), link a bot, place calls
Authentication. Every endpoint accepts both a JWT (Authorization: Bearer <jwt>) and an API key (Authorization: Bearer cm_<key>). API-key callers need the telephony:read scope for search/list/get and telephony:write for every write: buy, release, patch, the AI-call declaration, KYC submit/sync, placing, bridging and hanging up calls, and voicemail drops. Those writes additionally require an owner/admin role when called with a JWT.
Availability. Numbers are sold in India and in the countries
GET /numbers/countriesreturns. Telephony is enabled per tenant. When the feature is not enabled for your tenant, the routes are unmounted and every call returns404.
1. Submit KYC (Compliance)
Every rented Indian number must be backed by an accepted KYC application. Submission is a multipart form carrying your business details plus the two mandatory documents:
- Registration certificate — Certificate of Incorporation (CIN) or Udyam certificate
- GST certificate
Files must be PDF, JPEG, or PNG, up to 5 MB each. The legal business name must match exactly on both documents or the application is rejected upstream.
POST /compliance · scope telephony:write (owner/admin for JWT)
Form fields:
| Field | Type | Required | Notes |
|---|---|---|---|
alias | string (1–128) | Yes | A label for this application |
business_name | string (1–100) | Yes | Legal name, exactly as printed on both documents |
registration_number | string (1–64) | Yes | CIN or Udyam number |
email | string (3–254) | Yes | Business contact email |
address_line1 | string (1–255) | Yes | |
address_line2 | string (0–255) | No | |
city | string (1–100) | Yes | |
state | string (1–100) | Yes | |
postal_code | string (1–16) | Yes | |
registration_cert | file | Yes | COI or Udyam certificate (PDF/JPEG/PNG, ≤ 5 MB) |
gst_cert | file | Yes | GST certificate (PDF/JPEG/PNG, ≤ 5 MB) |
curl -X POST https://api.callmissed.com/api/v1/telephony/compliance \
-H "Authorization: Bearer cm_your_api_key" \
-F 'alias=Acme India KYC' \
-F 'business_name=ACME TECHNOLOGIES PRIVATE LIMITED' \
-F 'registration_number=U72900KA2020PTC000000' \
-F '[email protected]' \
-F 'address_line1=123 MG Road' \
-F 'address_line2=Suite 400' \
-F 'city=Bengaluru' \
-F 'state=Karnataka' \
-F 'postal_code=560001' \
-F '[email protected]' \
-F '[email protected]'import httpx
BASE = "https://api.callmissed.com/api/v1/telephony"
headers = {"Authorization": "Bearer cm_your_api_key"}
data = {
"alias": "Acme India KYC",
"business_name": "ACME TECHNOLOGIES PRIVATE LIMITED",
"registration_number": "U72900KA2020PTC000000",
"email": "[email protected]",
"address_line1": "123 MG Road",
"address_line2": "Suite 400",
"city": "Bengaluru",
"state": "Karnataka",
"postal_code": "560001",
}
files = {
"registration_cert": ("coi.pdf", open("coi.pdf", "rb"), "application/pdf"),
"gst_cert": ("gst.pdf", open("gst.pdf", "rb"), "application/pdf"),
}
resp = httpx.post(f"{BASE}/compliance", headers=headers, data=data, files=files)
application = resp.json()
print(application["id"], application["status"]) # e.g. "...", "submitted"Response (200 OK) — a compliance application:
{
"id": "3f9a1c20-7d8e-4b1a-9c2f-5e6a7b8c9d0e",
"tenant_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"alias": "Acme India KYC",
"country_iso": "IN",
"number_type": "local",
"user_type": "business",
"status": "submitted",
"plivo_compliance_id": null,
"rejection_reason": null,
"business_name": "ACME TECHNOLOGIES PRIVATE LIMITED",
"registration_number": "U72900KA2020PTC000000",
"created_at": "2026-04-19T12:00:00Z"
}Status codes
| Code | Meaning |
|---|---|
200 | Application created and submitted |
403 | Missing telephony:write scope, or JWT caller is not an owner/admin |
413 | A document exceeds the 5 MB limit |
422 | A document is missing, empty, or not a PDF/JPEG/PNG |
404 | Telephony not enabled for your tenant |
2. Check KYC Status
Applications move through draft → submitted → accepted / rejected, and an accepted application can later become suspended or expired. Only an accepted application can back a number purchase.
| Endpoint | Scope | Purpose |
|---|---|---|
GET /compliance | telephony:read | List your applications |
GET /compliance/{application_id} | telephony:read | Get one application + status |
POST /compliance/{application_id}/sync | telephony:write (owner/admin for JWT) | Refresh status from the carrier |
GET /compliance accepts limit (1–200, default 50) and offset (≥ 0). It returns an array of applications, newest first. POST /compliance/{application_id}/sync pulls the latest status and, if rejected, populates rejection_reason.
# List applications
curl https://api.callmissed.com/api/v1/telephony/compliance \
-H "Authorization: Bearer cm_your_api_key"
# Refresh one application's status
curl -X POST https://api.callmissed.com/api/v1/telephony/compliance/{application_id}/sync \
-H "Authorization: Bearer cm_your_api_key"Once status is accepted, the application's plivo_compliance_id field holds the compliance reference you pass as compliance_application_id when buying a number (step 4). Note this is that field's value, not the application's id. A GET/sync on an application you do not own returns 404.
3. Search Available Numbers
Countries
GET /numbers/countries · scope telephony:read
The countries you can buy numbers in, India first. available: false means the country is listed but not open for purchase yet.
curl https://api.callmissed.com/api/v1/telephony/numbers/countries \
-H "Authorization: Bearer cm_your_api_key"[
{ "country_iso": "IN", "calling_code": "91", "available": true },
{ "country_iso": "US", "calling_code": "1", "available": true }
]Document requirements
GET /compliance/requirements?country_iso=DE&number_type=local · scope telephony:read
Every country asks for different documents. This returns them for a country and number type. country_iso is required and must be India or a country from /numbers/countries, else 422. number_type is local (default), mobile or tollfree. documents_required: false means none are needed. proof_required: true means the document needs a file upload as well as its fields. Field type is string, date (written in the field's format, e.g. YYYY-DD-MM), enum (one of options) or geo-country (a two-letter code).
{
"country_iso": "DE",
"number_type": "local",
"documents_required": true,
"documents": [
{
"document_type_id": "919c5624-c14d-4330-bba5-12ecb46a8a3b",
"name": "Business registration",
"description": "Business Registration information",
"proof_required": true,
"fields": [
{ "field_name": "unique_identification_number", "name": "Unique Identification Number",
"type": "string", "required": true, "min_length": 1, "max_length": 50,
"format": null, "options": [], "help_text": null },
{ "field_name": "date_of_issue", "name": "Date of Issue", "type": "date",
"required": true, "min_length": null, "max_length": null,
"format": "YYYY-DD-MM", "options": [], "help_text": null }
]
}
]
}Submit documents for a country outside India
POST /compliance/country · multipart · scope telephony:write (owner/admin for JWT)
Files the documents from the requirements above. The body is checked against that country's live requirements, so it must contain every listed document exactly once, every required field, and a file for each document with proof_required: true.
| Field | Required | Notes |
|---|---|---|
country_iso, number_type | Yes | The market the application is for |
alias | Yes | Your name for the application |
business_name, email, address_line1, city, postal_code, business_country | Yes | Your business; business_country is a two-letter code |
address_line2, state, registration_number | No | |
documents | Yes | JSON list, one entry per document: [{"document_type_id": "...", "data_fields": {"<field_name>": "value"}}] |
documents[N].file | Per document | The file for the document at index N (PDF/JPEG/PNG, ≤ 5 MB) |
curl -X POST https://api.callmissed.com/api/v1/telephony/compliance/country \
-H "Authorization: Bearer cm_your_api_key" \
-F country_iso=DE -F number_type=local -F alias="Acme DE" \
-F business_name="Acme GmbH" -F [email protected] \
-F address_line1="1 Hauptstrasse" -F city=Berlin -F postal_code=10115 -F business_country=DE \
-F 'documents=[{"document_type_id":"a10fb4bb-0271-4b80-918e-c21ef7072508","data_fields":{"business_name":"Acme GmbH","address_line_1":"1 Hauptstrasse","city":"Berlin","postal_code":"10115","country":"DE"}},{"document_type_id":"919c5624-c14d-4330-bba5-12ecb46a8a3b","data_fields":{"unique_identification_number":"HRB 12345","business_name":"Acme GmbH","date_of_issue":"2020-15-01","country":"DE"}}]' \
-F 'documents[1][email protected]'It returns the application, like Check KYC Status. Poll or sync it until status is accepted, then pass its plivo_compliance_id when buying a number from that country and number type. 422 means the body does not match the country's requirements, or the country needs no documents.
Search
Search for numbers before buying. Rates are returned after your tenant markup, with 18% GST added on top. rental_credits is the total you will be charged per month; rental_base_credits and rental_gst_credits break it down.
GET /numbers/search · scope telephony:read
Query parameters
| Param | Values | Default |
|---|---|---|
country_iso | 2-letter ISO from /numbers/countries | IN |
type | local / mobile / tollfree | — |
pattern | digit substring to match (max 32 chars) | — |
limit | 1–20 | 20 |
curl "https://api.callmissed.com/api/v1/telephony/numbers/search?country_iso=IN&type=local&pattern=80802&limit=10" \
-H "Authorization: Bearer cm_your_api_key"Response (200 OK) — an array of search hits:
[
{
"number": "+919309963483",
"number_type": "local",
"country": "IN",
"region": "Mumbai",
"monthly_rental_rate_usd": 2.5,
"rental_base_credits": 250,
"rental_gst_credits": 45,
"gst_rate": 0.18,
"rental_credits": 295,
"voice_enabled": true,
"sms_enabled": false,
"compliance_required": true,
"setup_credits": 0
}
]compliance_required is true when the number needs documents before activation. For Indian numbers, that is your KYC application; elsewhere, an accepted country application. setup_credits is a one-time fee added to the first payment only (GST included); it is 0 for most numbers.
4. Buy a Number
Rent one of the searched numbers. This is a paid action: the first month (rental plus 18% GST, plus any one-time setup_credits) is drawn from your real (paid) credit balance. The signup bonus does not cover the purchase; if your paid balance is short, you get a 402 telling you to top up. Renewals are different. They draw on your whole credit balance, free credits included (see Billing).
POST /numbers · scope telephony:write (owner/admin for JWT)
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
e164 | string | Yes | The number to buy, e.g. +919309963483 |
country_iso | string | No | The number's country, as searched. Default IN |
compliance_application_id | string | Indian numbers, and numbers with compliance_required: true | The plivo_compliance_id of your accepted application for that country and number type. Ignored for numbers that need no documents |
The purchase runs in a strict, money-safe order: for an Indian number it verifies your KYC application is accepted (else 409), confirms the number is still available and prices it live (else 422), deducts the rental credits, and only then rents the number. If the rent fails, the credits are refunded automatically.
curl -X POST https://api.callmissed.com/api/v1/telephony/numbers \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"e164": "+919309963483",
"compliance_application_id": "your-accepted-compliance-reference"
}'import httpx
BASE = "https://api.callmissed.com/api/v1/telephony"
headers = {"Authorization": "Bearer cm_your_api_key"}
resp = httpx.post(
f"{BASE}/numbers",
headers=headers,
json={
"e164": "+919309963483",
"compliance_application_id": "your-accepted-compliance-reference",
},
)
if resp.status_code == 402:
print("Top up your paid balance before buying a number")
elif resp.status_code == 409:
print("Your KYC application is not accepted yet")
else:
number = resp.json()
print(number["id"], number["status"]) # e.g. "...", "active"Response (200 OK) — the rented number:
{
"id": "9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d",
"tenant_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"e164": "+919309963483",
"country_iso": "IN",
"number_type": "local",
"status": "active",
"bot_id": null,
"outbound_bot_id": null,
"alias": null,
"monthly_rental_rate_usd": 2.5,
"rental_credits": 295,
"added_on": "2026-04-19",
"renewal_date": "2026-05-19",
"config": null,
"metadata": null,
"a2p_declared_at": null,
"a2p_series": null,
"a2p_tsp_reference": null,
"created_at": "2026-04-19T12:00:00Z",
"release_on": null
}Status codes
| Code | Meaning |
|---|---|
200 | Number rented and active |
402 | Insufficient real balance — top up to buy |
403 | Missing telephony:write scope, or JWT caller is not an owner/admin |
409 | KYC not accepted, you already hold this number, or (outside India) the number needs documents and no accepted application for its country and type was given |
422 | Number no longer available, e164 is malformed or not from country_iso, or the country is not offered |
503 | The country is listed but not open for purchase yet |
404 | Telephony not enabled for your tenant |
5. Manage Numbers
| Endpoint | Scope | Purpose |
|---|---|---|
GET /numbers | telephony:read | List your rented numbers |
GET /numbers/{number_id} | telephony:read | Get one number |
PATCH /numbers/{number_id} | telephony:write (owner/admin for JWT) | Update alias / linked bot / per-number call config |
DELETE /numbers/{number_id}?confirm=true | telephony:write (owner/admin for JWT) | Release a number (permanent) |
GET /numbers accepts status (e.g. active), limit (1–200, default 50), and offset (0–100000), newest first. PATCH updates only the fields you send; a bot_id or outbound_bot_id that is not yours returns 404. bot_id is the agent that answers inbound calls. It also places outbound calls from the number unless you set outbound_bot_id to a different agent; set outbound_bot_id back to null to use one agent for both again. A number with no agent (or an agent that is switched off) and no call menu, call flow, call queue or agent squad answers with a short "Sorry, this number isn't taking calls right now. Please try again later." and then hangs up. That call is billed like any other short inbound call: carriage for its length, plus the ₹1 a minute platform fee at its 30-second minimum. A number moves through pending → active → suspended (unpaid) → released.
# List your rented numbers
curl https://api.callmissed.com/api/v1/telephony/numbers \
-H "Authorization: Bearer cm_your_api_key"
# Get one
curl https://api.callmissed.com/api/v1/telephony/numbers/{number_id} \
-H "Authorization: Bearer cm_your_api_key"
# Update the alias and link a voice-agent bot
curl -X PATCH https://api.callmissed.com/api/v1/telephony/numbers/{number_id} \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{"alias": "Support line", "bot_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"}'Per-number call overrides
The optional config object holds per-number call-handling overrides that win over the linked bot's config on this number's calls — so two numbers can share one bot yet greet and speak differently. The object replaces the stored overrides on every write (send the full set each time; {} clears every override). A key set to null or "" is dropped, so the bot's own value applies again. Unknown keys return 422.
| Key | Type | Notes |
|---|---|---|
voice_model | string (≤ 100) | Voice LLM model id |
voice | string (≤ 64) | Voice / speaker id |
language | string (≤ 16) | e.g. hi-IN |
stt_model | string (≤ 64) | Speech-to-text model id |
tts_model | string (≤ 64) | Text-to-speech model id |
tts_provider | string (≤ 32) | TTS provider id |
tts_engine | string (≤ 32) | TTS engine id |
greeting | string (≤ 500) | Opening line spoken on the call |
system_prompt | string (≤ 8000) | Overrides the bot's persona for this number |
max_call_duration_seconds | integer | 30–14400 |
allow_interruptions | boolean | false turns barge-in off on this number, e.g. for a scripted disclosure. A speech-to-speech model always lets the caller interrupt, so false is ignored on one |
tools | array of strings | Up to 20 agent tool names |
queue_id | string | The call queue this number routes through. Normally set by attaching a queue; keep it in the set you send, or the binding is cleared |
menu_id / flow_id | string | Accepted only as null or "", to clear an old binding. Any other value returns 422, because inbound menus and flows are not available yet |
curl -X PATCH https://api.callmissed.com/api/v1/telephony/numbers/{number_id} \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{"config": {"greeting": "Namaste! Aap Support line par pahunche hain.", "language": "hi-IN", "max_call_duration_seconds": 600}}'Release a number
curl -X DELETE "https://api.callmissed.com/api/v1/telephony/numbers/{number_id}?confirm=true" \
-H "Authorization: Bearer cm_your_api_key"confirm=true is required — releasing a number is permanent, stops its monthly rental charge, and is not refunded. Requires telephony:write (owner/admin for JWT). Returns 204 No Content on success, 400 if confirm is omitted, and 404 if the number is not found or not owned by your tenant.
Renew a number now
curl -X POST "https://api.callmissed.com/api/v1/telephony/numbers/{number_id}/renew" \
-H "Authorization: Bearer cm_your_api_key"Pays the next monthly rental straight away instead of waiting for the automatic renewal. It works for a suspended number, which is reactivated immediately, and for an active number whose renewal_date is within the next 7 days. The charge is rental_credits, drawn from your whole credit balance (free credits included), and renewal_date moves forward 30 days. Requires telephony:write (owner/admin for JWT). Returns the updated number (200), 402 if your balance can't cover the rental, 409 if the number is not due for renewal, and 404 if the number is not found or not owned by your tenant.
A suspended number carries release_on, the date it is released if the rental is still unpaid. It is null for every other status.
Declare a number for AI calls (India)
TRAI requires a business making automated or AI calls to declare that use, and the caller IDs it uses, to its telecom provider first (press release 119/2026). After you have made that declaration with your provider, record it on the number. Only Indian numbers can be declared; any other returns 422. Campaigns check it before they dial; see TRAI readiness.
curl -X PUT https://api.callmissed.com/api/v1/telephony/numbers/{number_id}/a2p-declaration \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{"series": "1600", "tsp_reference": "DECL-2026-0042", "confirm_declared_to_tsp": true}'| Field | Type | Required | Notes |
|---|---|---|---|
series | 140 | 1600 | 1601 | standard | Yes | 140, 1600 and 1601 are TRAI's commercial-call series; standard is an ordinary number |
tsp_reference | string (≤64) | No | Your telecom provider's reference for the declaration |
confirm_declared_to_tsp | boolean | Yes | Must be true. You confirm the declaration was made to your provider |
Returns the number with a2p_declared_at, a2p_series and a2p_tsp_reference set. Declaring again updates them. confirm_declared_to_tsp: false returns 422, and so does a tsp_reference with characters other than letters, digits and _ . / -. DELETE on the same path withdraws the declaration and returns the number. Both need telephony:write (owner/admin for JWT). A released number returns 409.
6. Place a Call
Originate an outbound PSTN call from one of your active numbers. Link a bot_id to have your AI voice agent handle the call; if you omit it, the number's outbound agent is used (outbound_bot_id, or bot_id when the number uses one agent for both).
POST /calls · scope telephony:write (owner/admin for JWT)
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
from_number_id | UUID | Yes | An active number you own |
to_e164 | string | Yes | The destination, e.g. +919000000000 |
bot_id | UUID | No | Voice-agent bot to answer the call |
reason | string (≤ 500) | No | Plain-language purpose; spoken on the outbound greeting |
greeting_mode | outbound | inbound | No | Default follows the call: the agent introduces itself and states reason. inbound makes it greet in character from its own greeting, as it would answer an inbound caller, and not speak reason (still stored on the call). Useful for test calls to yourself |
variables | object | No | Per-call {{token}} values, merged over the agent's declared input-variable defaults and rendered into its greeting and prompt. Up to 50 entries; keys match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$; each value ≤ 200 characters |
status_callback_url | string (≤ 2048) | No | A public https URL we POST this call's lifecycle payload to on every status change — the same shape as the account-level call.* webhook events. Internal or private addresses are refused with 400 |
send_digits | string (≤ 32) | No | Keys pressed for you once the callee answers, for example an extension or PIN. Characters 0-9, *, #, and w (a 0.5 second wait). Anything else is refused with 422 |
curl -X POST https://api.callmissed.com/api/v1/telephony/calls \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from_number_id": "9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d",
"to_e164": "+919000000000",
"bot_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"reason": "Confirming your appointment for tomorrow"
}'Response (200 OK) — the created call (status advances via webhooks):
{
"id": "5e6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
"tenant_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"phone_number_id": "9c2b7e30-1d8a-4c5f-9b3d-2f4a6e8b1c2d",
"bot_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"voice_session_id": "7f8a9b0c-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
"direction": "outbound",
"status": "initiated",
"remote_e164": "+919000000000",
"bill_duration_seconds": null,
"billed_duration_seconds": null,
"duration_seconds": null,
"cost_credits": null,
"ai_cost_credits": null,
"hangup_cause_code": null,
"hangup_source": null,
"recording_id": null,
"amd_result": null,
"end_reason": null,
"tool_call_count": null,
"followed_up_at": null,
"metadata": null,
"created_at": "2026-04-19T12:00:00Z"
}Status codes
| Code | Meaning |
|---|---|
200 | Call created and dialing |
400 | status_callback_url is not a valid public https URL |
402 | Insufficient credits to reserve the call |
403 | Missing telephony:write scope, JWT caller is not an owner/admin, the destination is on your do-not-call list, or the destination country / number range is not allowed |
404 | from_number_id not found/active, or an explicit bot_id not found |
409 | The bot_id agent is switched off (This agent is switched off. Switch it on to place calls.). Nothing is dialled or charged; switch the agent on (POST /api/v1/bots/{bot_id}/toggle) and retry |
422 | to_e164 is malformed, variables breaks the limits above, send_digits has a character outside 0-9 * # w or is longer than 32, or the agent declares a required input variable you did not supply |
429 | The phone calls at once limit for your plan is reached (Free 1, Starter 5, Pro 10, Enterprise 20, Scale 30; Business and Corporate are custom, agreed with [email protected]), or a burst of calls that looks like toll fraud or robocalling was held |
Phone menus (agent setting). To let an agent press keys itself while it talks to someone else's automated menu, set dtmf_send_enabled to true in the agent's config (off by default). Set ivr_navigation to true as well and the agent also recognises a recorded menu, waits through long prompts and tries again when a menu repeats itself; it has no effect without dtmf_send_enabled. Both apply to phone calls only.
The call row carries two costs. cost_credits is the phone-line leg only: it is filled in after the call by reconciliation (typically within the hour) and stays null for inbound calls. ai_cost_credits is the voice agent (STT, LLM and TTS) for the same call. duration_seconds is the best duration available right now, filled the moment the call ends. amd_result is the answering-machine verdict (human, machine or unknown; null when detection did not run), end_reason says how the agent's session ended (null until it has), and tool_call_count is how many tools the agent ran during the call (see the turn tool_calls in the voice session transcript). The list, get, follow-up and hang-up responses fill both; the response to placing a call leaves them null.
7. List & Fetch Calls
| Endpoint | Scope | Purpose |
|---|---|---|
GET /calls | telephony:read | List your calls |
GET /calls/export | telephony:read (owner/admin for JWT) | Download calls with their post-call analysis as CSV or Excel |
GET /calls/{call_id} | telephony:read | Get one call |
GET /calls/{call_id}/recording | telephony:read | Signed recording URL |
GET /calls/{call_id}/transcript | telephony:read | What was said on the call, as JSON, text or subtitles |
DELETE /calls/{call_id} | telephony:write (owner/admin for JWT) | Hang up a live call |
POST /calls/{call_id}/follow-up | telephony:write | Mark a missed call followed up, or reopen it |
GET /calls query parameters
| Param | Values | Default |
|---|---|---|
direction | inbound / outbound | — |
status | initiated / ringing / in_progress / completed / failed / no_answer / busy, or several comma-separated (no_answer,busy,failed) | — |
q | Up to 64 characters. Digits match the other party's number; anything else matches your CRM contacts' names | — |
from | ISO 8601 timestamp: calls started at or after it | — |
to | ISO 8601 timestamp: calls started before it | — |
bot_id | UUID of one of your agents | — |
follow_up | open (not yet followed up) / done | — |
analysis | URL-encoded JSON list of up to 8 filters on the post-call analysis, all of which must match. See below | — |
sort | created_at, or an analysis field such as rating (numbers first, then text, calls without a value last) | created_at |
sort_dir | asc / desc | desc |
view_id | UUID of a saved call view. Its filters and sort apply; parameters you pass override them, and analysis filters are added to the view's. Also needs crm_views:read | — |
limit | 1–200 | 50 |
offset | 0–100000 | 0 |
curl "https://api.callmissed.com/api/v1/telephony/calls?direction=outbound&status=completed&limit=50&offset=0" \
-H "Authorization: Bearer cm_your_api_key"Returns an array of calls, newest first. GET /calls/{call_id} fetches a single call (404 if not owned).
Filter on what the agent captured
Each analysis filter is {"field", "op", "value"}. field is one of the agent's analysis variables, or call.sentiment, call.disposition or call.goal_met.
op | Matches | value |
|---|---|---|
eq / neq | Equal / not equal. Text ignores case. neq also matches calls with no value | text, number or boolean |
lt / lte / gt / gte | Numeric comparison. Values stored as text never match | number |
contains | Text contains, ignoring case | text, up to 200 characters |
is_empty / not_empty | No value captured (including calls that were not analysed) / a value captured | — |
# Calls rated 2 or lower, worst first
curl -G "https://api.callmissed.com/api/v1/telephony/calls" \
--data-urlencode 'analysis=[{"field":"rating","op":"lte","value":2}]' \
-d sort=rating -d sort_dir=asc \
-H "Authorization: Bearer cm_your_api_key"A malformed analysis or sort returns 422.
Saved call views. Save a filter set once with POST /api/v1/crm/saved-views and entity_type: "call" (Saved views), then list its calls with view_id. They also appear in the console under Voice, Call log.
Export call results (CSV or Excel)
GET /calls/export downloads every call that matches the filters, newest first, with the call's post-call analysis. It takes the same direction, status, q, from, to, bot_id and follow_up filters as GET /calls (no limit / offset), plus:
| Param | Values | Default |
|---|---|---|
format | csv (UTF-8 with a byte-order mark, so Excel shows Hindi, Tamil and other scripts correctly) / xlsx | csv, or the template's format |
bot_ids | Comma-separated agent ids, up to 50, for several agents at once. In xlsx each agent gets its own sheet with its own fields; in csv the calls share one table. 404 if any is not yours | — |
header_style | readable (headers and values in plain words, for people) / raw (machine keys and unformatted values, for integrations) | raw with an API key (cm_*); readable from the console |
export_columns | The exact columns of the file, in order, comma-separated (up to 60). See "Choosing columns" below | every built-in column and every analysis field |
template_id | A saved export template: its columns, format and header style, unless you pass them yourself. Also needs crm_views:read | — |
timezone | IANA zone used for call times in the readable style | your workspace time zone, else Asia/Kolkata |
campaign_id | UUID of an outbound campaign: only the calls it placed | — |
days | 1–90. The window ending at to (default now), used when from is not set | 30, or the whole campaign with campaign_id |
analysis | The same analysis filters as GET /calls | — |
view_id | A saved call view: its filters apply, and its columns become the analysis columns. Also needs crm_views:read | — |
columns | Comma-separated analysis fields (up to 12) to export instead of every field, in that order | — |
The window between from and to can be at most 90 days (422 otherwise). With campaign_id there is no window limit: leave out from and days to get every call the campaign placed, however old. The file holds at most 50,000 rows; export a shorter window for more.
Header styles. readable is written for a person opening the file. raw is the stable machine format; use it when code reads the file. The default depends on who is calling: an API key gets raw, the file integrations have read since this endpoint shipped, while the console and the export_call_results agent tool default to readable. (Note, 2026-11-13: the 2026-11-12 release briefly made readable the API default as well; that is reverted. Pass header_style explicitly if your code must not depend on the default.)
readable | raw | |
|---|---|---|
| Headers | Call time (IST), Phone number, Star rating | call_time_utc, phone_number, star_rating |
| Call time | 12 Nov 2026, 4:05 PM in the timezone | ISO 8601, UTC |
| Duration | 2m 05s | seconds, as a number |
| True / false | Yes / No | true / false |
| Status, direction, end reason, sentiment, outcome, enum fields | In words: No answer, Call back later | As stored: no_answer, call_back_later |
| A star rating field | 4 / 5 | 4 |
| Default column order | Call time, Agent, Phone number, Channel, Direction, Duration, Status, How it ended, Summary, Sentiment, Outcome, Goal met, the analysis fields, Call ID | call_id, call_time_utc, agent, phone_number, direction, duration_seconds, status, end_reason, analysis_status, summary, sentiment, disposition, goal_met, the analysis fields, channel |
The zone in the readable call-time header is the zone's standard-time name all year (Call time (EST) for America/New_York in July too, GMT for Europe/London, AEST for Australia/Sydney), so a scheduled export never adds a second call-time column to its sheet when the clocks change; the values themselves follow daylight saving. No two columns share a header: when an analysis field is named like a built-in column in the same file (a field called summary, status or call_id), the built-in keeps its header and the field's header says which field it is, Summary (summary) in readable and summary__field in raw. A Google Sheet tab filled by a scheduled export gets the same headers.
A missing value is an empty cell in both styles. phone_number is the other party. The file has one row per phone call and per WhatsApp call an agent answered or placed; channel is phone or whatsapp (Phone / WhatsApp in readable). In raw it is the last column (added 2026-11-14), so no column your code already reads has moved. analysis_status is pending / completed / failed, empty when the call was not answered.
Analysis fields. With bot_id, these are that agent's analysis_variables in the order they are declared (404 if the agent is not yours); with bot_ids, the chosen agents' fields; with neither, every agent's. Fields a call extracted that no agent declares any more come last. A whole-number rating reads 4, not 4.0.
Choosing columns. export_columns lists exactly the columns you want, in the order you want them. Each entry is one of:
| Key | readable header | raw header |
|---|---|---|
call.time | Call time (zone) | call_time_utc |
call.agent | Agent | agent |
call.number | Phone number | phone_number |
call.direction | Direction | direction |
call.channel | Channel | channel |
call.duration | Duration | duration_seconds |
call.status | Status | status |
call.end_reason | How it ended | end_reason |
call.analysis_status | Analysis | analysis_status |
call.summary | Summary | summary |
call.sentiment | Sentiment | sentiment |
call.disposition | Outcome | disposition |
call.goal_met | Goal met | goal_met |
call.recording | Recording: a console link to the call when it has a recording, else empty | recording_link |
call.id | Call ID | call_id |
an analysis field name, e.g. star_rating | The name in words: Star rating | the name |
* | Every analysis field you did not name, in the usual order | the same |
An unknown call. key or a malformed name is a 422. In an Excel file for several agents, a named analysis field appears only on the sheets of the agents that declare it.
Export templates. Save a column list, a format and a header style once and reuse them with template_id. A template is a saved view with entity_type: "call_export"; see Export templates.
In CSV, a cell that starts with =, +, -, @, a tab or a carriage return is prefixed with ' so spreadsheets do not run it as a formula, which is why phone numbers appear as '+91…. In xlsx, numbers and true/false values are typed cells and text is always stored as text, so nothing needs the prefix.
curl "https://api.callmissed.com/api/v1/telephony/calls/export?bot_id={bot_id}&days=30&format=xlsx" \
-H "Authorization: Bearer cm_your_api_key" \
-o call-results.xlsx
# Two agents, chosen columns, machine keys
curl "https://api.callmissed.com/api/v1/telephony/calls/export?bot_ids={bot_a},{bot_b}&export_columns=call.time,call.agent,call.number,*,call.id&header_style=raw" \
-H "Authorization: Bearer cm_your_api_key" \
-o call-results.csvGET /calls and GET /calls/{call_id} also carry each call's post-call analysis as analysis (status, summary, sentiment, disposition, goal_met, extracted), or null until it has run.
Scheduled exports
Send the same call results on a timetable instead of downloading them by hand. A scheduled export goes out every day (yesterday's calls) or every week (the seven days before the run day), to people in your workspace by email, to a Google Sheet tab, or both. These endpoints live under /api/v1/scheduled-exports, not under /api/v1/telephony.
| Endpoint | Scope | What it does |
|---|---|---|
GET /api/v1/scheduled-exports | telephony:read | List exports with their recipients, next run and last run |
POST /api/v1/scheduled-exports | telephony:write | Create an export |
PATCH /api/v1/scheduled-exports/{id} | telephony:write | Change it. {"enabled": false} pauses, true resumes |
DELETE /api/v1/scheduled-exports/{id} | telephony:write | Delete it and its run history |
GET /api/v1/scheduled-exports/{id}/runs | telephony:read | Run history, newest first (limit, offset) |
POST /api/v1/scheduled-exports/{id}/run | telephony:write | Send now: queue one delivery of the latest closed period (202) |
GET /api/v1/scheduled-exports/runs/{run_id}/download | telephony:read | The file for one delivery, in the export's format |
Create and update take:
| Field | Type | Notes |
|---|---|---|
name | string | Required on create, up to 120 characters |
frequency | daily / weekly | Required on create |
weekday | 0–6 | Weekly only, required then. 0 is Monday |
hour | 0–23 | Hour of the day it goes out, in timezone_name. Default 9 |
timezone_name | string | IANA zone. Default Asia/Kolkata. Periods are whole days in this zone |
bot_id | UUID | Only this agent's calls |
campaign_id | UUID | Only this outbound campaign's calls |
view_id | UUID | Only the calls a saved call-log view matches, with that view's columns. The view must be shared with your workspace. Not together with bot_id or campaign_id (422) |
format | xlsx / csv | The file behind the email link. Default xlsx |
template_id | UUID | An export template shared with your workspace: the columns of the file and of the sheet, in order. null goes back to the default columns |
header_style | readable / raw | How headers and values are written, as on GET /calls/export. Default readable. Exports created before header styles existed stay raw |
recipient_emails | string[] | Up to 20. Each must be an active member of your workspace (422 otherwise) |
recipient_user_ids | UUID[] | The same recipients by user id |
integration_id, spreadsheet_id, sheet | UUID, string, string | A Google Sheets connection of yours, a spreadsheet you allowed on it, and an existing tab. All three or none |
enabled | boolean | false pauses the export |
Leave out bot_id, campaign_id and view_id to cover every call. With view_id, the export keeps the view's filters and columns but not its date range: each delivery covers the export's own period. If the view is later deleted or made private, the next run fails with an error that says so, and nothing is sent. An export needs at least one destination: a recipient or a sheet (422 otherwise).
Recipients get an email with a link, not an attachment: the file holds callers' phone numbers, so it is downloaded by a signed-in workspace member. On a sheet, each call is one row under the tab's header and carries its call id (call_id, or Call ID in the readable style; it is added even when a template leaves it out); a call that is already on the tab is not added again, your own columns are left alone, and a field the tab has no column for gets a new column at the end. Columns are the same as GET /calls/export. A tab keeps the header style it started with: changing header_style on an export that writes to a sheet is a 422 unless you point it at another tab in the same request. If the template is later deleted or made private, the next run fails with an error that says so.
Each run in the history has status (queued, running, succeeded, failed), period_start, period_end, row_count, emails_sent, sheet_rows_added and, when it failed, an error sentence that says what to change.
curl -X POST "https://api.callmissed.com/api/v1/scheduled-exports" \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly feedback",
"frequency": "weekly",
"weekday": 0,
"hour": 9,
"timezone_name": "Asia/Kolkata",
"bot_id": "{bot_id}",
"recipient_emails": ["[email protected]"]
}'Follow up a missed call
curl -X POST https://api.callmissed.com/api/v1/telephony/calls/{call_id}/follow-up \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{"done": true}'Stamps followed_up_at on the call (send "done": false to clear it) and returns the call. Marking a call that is already done keeps its first timestamp. List the calls still waiting with GET /calls?direction=inbound&status=no_answer,busy,failed&follow_up=open.
Recordings
If a call was recorded, fetch a short-lived signed URL for its audio:
curl https://api.callmissed.com/api/v1/telephony/calls/{call_id}/recording \
-H "Authorization: Bearer cm_your_api_key"Response (200 OK):
{ "url": "https://media.callmissed.com/recordings/....?token=..." }The URL is time-limited — fetch it on demand rather than storing it. Returns 404 if the call has no recording, and 503 if recording storage is temporarily unavailable.
Transcripts
GET/api/v1/telephony/calls/{call_id}/transcript
What was said on a phone call, by call id. Scope telephony:read. It is the same transcript as GET /v1/voice/sessions/{session_id}/transcript, reached from the call, so an integration that holds a call_id (from the call list or a call.completed webhook) does not need the session id. Transcripts are saved whether or not the call is recorded.
| Parameter | In | Type | Required | Constraints |
|---|---|---|---|---|
call_id | path | UUID | Yes | A call in your account |
format | query | string | No | json (default), txt or srt |
curl "https://api.callmissed.com/api/v1/telephony/calls/5e6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c/transcript?format=json" \
-H "Authorization: Bearer cm_your_api_key"Response (200 OK), format=json — an array of turns in the order they were spoken:
[
{
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"turn_index": 0,
"user_transcript": "Hi, I wanted to check on my order.",
"agent_response": "Sure, can you tell me the order number?",
"interrupted": false,
"stt_ms": 180,
"first_token_ms": 420,
"tts_ttfb_ms": 160,
"eou_delay_ms": 300,
"first_audio_ms": 910,
"total_ms": 4200,
"llm_model": "gpt-4o",
"tool_calls": null,
"created_at": "2026-11-17T06:40:12.118000Z"
}
]| Field | Type | Meaning |
|---|---|---|
turn_index | integer | Position of the turn in the call, from 0 |
user_transcript | string | null | What the caller said on this turn |
agent_response | string | null | What the agent said in reply |
interrupted | boolean | The caller spoke over the agent's reply |
stt_ms, first_token_ms, tts_ttfb_ms, eou_delay_ms, first_audio_ms, total_ms | integer | null | Timings in milliseconds; null when a stage was not measured |
llm_model | string | null | The model that answered the turn |
tool_calls | array | null | The tools the agent ran on the turn, in order, each {id, name, args, result, ok, ms}; null when it ran none |
created_at | datetime | When the turn was stored |
format | Content-Type | Body |
|---|---|---|
json | application/json | The array above. An answered call with no stored turns returns [] |
txt | text/plain | Session:, Started: and Ended: header lines, then alternating User: / Agent: lines |
srt | application/x-subrip | SubRip subtitles, one cue per User: / Agent: line, timed from the turn durations |
| Status | detail | What to do next |
|---|---|---|
403 | API key missing required scope: telephony:read | Add the scope to the key |
404 | Call not found | The id is not a call in your account. Check the id |
404 | No transcript available | The call exists but no agent answered it (not answered, busy, failed, or bridged without an agent). There is nothing to fetch; do not retry |
422 | Validation error | call_id is not a UUID, or format is not json, txt or srt |
Turns are stored as the call goes, so a request made while the call is live returns the turns so far. For the finished transcript, fetch after call.completed.
Hang up a call
curl -X DELETE https://api.callmissed.com/api/v1/telephony/calls/{call_id} \
-H "Authorization: Bearer cm_your_api_key"Ends a live call and returns the call, now completed. Idempotent: hanging up a call that has already ended returns it unchanged. 404 if the call is not yours.
8. Click-to-call (bridge a person to a contact)
POST /click-to-call · scope telephony:write (owner/admin for JWT)
Rings your phone first, and once you pick up, dials the contact and puts you both on one line. No AI agent joins. Both legs are outbound calls from your active number and are billed as such; if you do not answer, nothing is charged and the contact is never dialled.
| Field | Type | Required | Notes |
|---|---|---|---|
destination | string | One of these two | The contact's number, in E.164 |
contact_id | UUID | One of these two | A CRM contact of yours; its phone number is dialled |
agent_number | string | No | The phone to ring first, in E.164. Omit to use the operator phone set in your account settings |
bot_id | UUID | No | Picks which of your numbers is used as the caller ID, and is recorded on both call rows |
curl -X POST https://api.callmissed.com/api/v1/telephony/click-to-call \
-H "Authorization: Bearer cm_your_api_key" \
-H "Content-Type: application/json" \
-d '{"agent_number": "+919000000001", "destination": "+919000000002"}'Response (200 OK):
{
"status": "bridged",
"room_name": "…",
"agent_call_id": "5e6a7b8c-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
"destination_call_id": "6f7a8b9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
"destination_e164": "+919000000002",
"contact_id": null
}bridged means both legs connected. A leg answered by voicemail also counts as connected, so it does not prove a person is listening. Both call ids work with GET /calls/{call_id} and DELETE /calls/{call_id}.
| Code | Meaning |
|---|---|
402 | Insufficient credits to reserve both legs |
403 | The destination is on your do-not-call list, or not an allowed destination |
404 | bot_id or contact_id not found |
409 | No agent_number and no operator phone configured, or no active number to call from |
422 | Neither destination nor contact_id given, or a number is not valid E.164 |
429 | Too many calls in progress (a bridge or live transfer counts as one call, and may use one line above your plan's limit) |
503 | Nobody answered your phone, so the contact was not dialled |
9. Voicemail drop
POST /calls/{call_id}/voicemail-drop · scope telephony:write (owner/admin for JWT)
Prepares the voicemail message for a call and returns where its audio is. Body: {"template_id": "<uuid>"}, or {} to use the template the call's campaign or agent is configured with. Templates are managed on the Call Handling API.
{
"action": "voicemail_drop",
"template_id": "2f8a7c10-5b6d-4e3f-8a1b-7c9d0e1f2a3b",
"audio_url": "https://…",
"hangup_after": true
}A text-only template is turned into speech, cached and billed the first time it is used. audio_url is short-lived. 404 if the call or template is not yours, 409 if no template is configured for the call or it has nothing to say, 503 if speech synthesis or audio storage is unavailable.
Scopes
| Scope | Grants |
|---|---|
telephony:read | Search numbers, list/get numbers, list/get compliance applications, list/get calls, fetch recording URLs and call transcripts, list BYO providers and connections |
telephony:write | Buy/release/update numbers, the AI-call declaration, submit & sync compliance applications, place / bridge / hang up calls, voicemail drops, BYO connections and imports |
Every telephony:write action also requires an owner/admin role when called with a JWT (an API key carrying telephony:write is sufficient on its own).
Billing
| Charge | When |
|---|---|
| Number rental | Monthly, in credits, per active number (rental_credits, 18% GST included). The first month is paid from your real balance, not the signup bonus. Each renewal on renewal_date draws on your whole credit balance, free credits included. |
| Call usage | Reserved when a call is placed, then settled to the real cost from the call record after the call completes. |
Releasing a number stops its monthly rental charge (no refund for the current period). Ensure sufficient credits before buying numbers or placing calls, or those calls return 402.
Renewal reminders. For the 7 days before a number's renewal_date, the account owner gets one email a day if the credit balance can't cover the rentals due. If a renewal still can't be paid, the number is suspended (calls stop) and you get a daily reminder until it is renewed or released at release_on. Add credits or pick a plan, then call renew to bring it back immediately.
Webhooks
Telephony call-lifecycle and recording-ready events are delivered to the endpoints you configure via the Webhooks API. For one call, status_callback_url on POST /calls delivers the same lifecycle payload to a URL of your choice. Payloads are HMAC-SHA256 signed — verify the X-CallMissed-Signature header exactly as shown on the Webhooks page before trusting a payload.