NaCaller API
Place the call from your own software.
A small REST API for the things you do all day: place an AI voice call, start a campaign from a list, and read back what happened, with the outcome, a summary, the transcript and a recording link. It follows the same rules as the dashboard: do-not-call, calling hours and your own wallet.
Quick start
Three requests to your first call.
Base URL: https://api.nacaller.com/api/v1. Everything is JSON over HTTPS. The API is read and start only: you can place calls and campaigns and read results, but agents are written in the dashboard.
- In the dashboard, open Settings, then Developers, and create a key. It is shown once.
- List your agents and pick the one that should call.
- Place the call, then read it back by its id.
export NACALLER_API_KEY=nc_live_… # from Settings, Developers
# 1. find the agent you want to use
curl https://api.nacaller.com/api/v1/agents -H "Authorization: Bearer $NACALLER_API_KEY"
# 2. place a call
curl -X POST https://api.nacaller.com/api/v1/calls -H "Authorization: Bearer $NACALLER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id":"<id from step 1>","phone":"+919876543210"}'
# 3. read what happened
curl https://api.nacaller.com/api/v1/calls/<id from step 2> -H "Authorization: Bearer $NACALLER_API_KEY"Authentication
One header, and a key that is yours alone.
Send the key as a bearer token on every request:
Authorization: Bearer nc_live_…- Keys start with
nc_live_. Create, list and revoke them under Settings → Developers. - We show a key once, when you create it. We keep only a one-way fingerprint, so a lost key cannot be recovered: revoke it and make another.
- Revoking is immediate. Keep keys on your server, in an environment variable such as
NACALLER_API_KEY, never in a web page or a mobile app. - A key sees only its owner’s agents, calls and campaigns, and spends only its owner’s wallet. Up to 10 active keys per account.
Only the SHA-256 of your key is stored.
A suspended, unapproved or unverified account cannot use a key.
300 requests a minute and a daily call limit on every key.
POST /v1/calls
Place a call
Starts an outbound call with one of your agents. The contact is saved on your account if it is new. The call goes through the same checks as a call from the dashboard, then rings.
| Field | Notes |
|---|---|
agent_id | Required. An id from GET /v1/agents. |
phone | Required. A mobile number: +919876543210 or 10 digits. |
name | Optional. Used the first time the contact is saved. |
variables | Optional. Up to 20 text fields, such as fee_amount, that fill {{fee_amount}} in the agent’s script. |
language | Optional. A language code such as te, hi or en. Defaults to the agent’s own. |
Returns 201 as soon as the call is accepted. Poll GET /v1/calls/{id} or use a webhook for the result. Calls only go out between 9 am and 9 pm India time (outside_calling_hours), and a number that opted out is refused (contact_opted_out).
curl -X POST https://api.nacaller.com/api/v1/calls \
-H "Authorization: Bearer $NACALLER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e",
"phone": "+919876543210",
"name": "Suresh",
"variables": { "fee_amount": "4500", "due_date": "15 Oct" }
}'{
"id": "5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30",
"status": "initiated",
"agent_id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e",
"to": "+919876543210"
}GET /v1/calls
List calls
Your calls, newest first. Light on purpose: no transcript or recording here. Fetch one call for those.
| Query | Notes |
|---|---|
status | Optional. For example Completed, No Answer, Busy, Failed. |
agent_id | Optional. Only this agent’s calls. |
campaign_id | Optional. Only this campaign’s calls. |
limit / cursor | See Pagination. |
curl "https://api.nacaller.com/api/v1/calls?limit=2&status=Completed" \
-H "Authorization: Bearer $NACALLER_API_KEY"{
"data": [
{
"id": "5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30",
"agent_id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e",
"campaign_id": null,
"direction": "outbound",
"to": "+919876543210",
"status": "Completed",
"outcome": "interested",
"outcome_reason": "Asked for a site visit on Saturday.",
"hangup_cause": null,
"summary": "Suresh wants to visit the flat on Saturday and asked about the payment plan.",
"sentiment": { "label": "Positive", "score": 0.86 },
"lead_score": 82,
"duration_seconds": 94,
"captured": { "budget": "50 lakh" },
"tags": ["site visit", "hot"],
"started_at": "2026-10-07T05:14:02.000Z",
"answered_at": "2026-10-07T05:14:09.000Z",
"completed_at": "2026-10-07T05:15:43.000Z"
}
],
"has_more": true,
"next_cursor": "NWQyZjZhMWMtOTNiMC00ZjBlLThhNzctMmM5ZTRkMWI2YTMw"
}GET /v1/calls/{id}
Get one call
Everything about one call: outcome, summary, sentiment, lead score, duration, captured details, the transcript and a recording link.
The recording link is signed and lasts 10 minutes. It plays the audio and needs no key, so you can hand it straight to a browser, but it stops working after recording_url_expires_at. Fetch the call again for a fresh one. It is null when the call has no recording.
curl https://api.nacaller.com/api/v1/calls/5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30 \
-H "Authorization: Bearer $NACALLER_API_KEY"{
"id": "5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30",
"status": "Completed",
"outcome": "interested",
"summary": "Suresh wants to visit the flat on Saturday.",
"sentiment": { "label": "Positive", "score": 0.86 },
"lead_score": 82,
"duration_seconds": 94,
"transcript": "Agent: Hello Suresh…\nCustomer: Haan, tell me…",
"recording_url": "https://api.nacaller.com/api/v1/recordings/5d2f6a1c-…?exp=1791350143&sig=9c1e…",
"recording_url_expires_at": "2026-10-07T05:25:43.000Z",
"...": "every field from the list above"
}POST /v1/campaigns
Start a campaign
Creates a campaign from a list of contacts and starts it. Inside calling hours it starts dialling at once; outside them it waits and starts_at tells you when. Contacts who opted out are skipped and counted in skipped_opted_out.
| Field | Notes |
|---|---|
name | Required. |
agent_id | Required. |
contacts | Required. Up to 10000 per request, each with phone and optional name and variables. The same number twice is called once. |
language | Optional. Defaults to English. |
Every contact counts against the key’s daily call limit up front. If the list is larger than what is left today, nothing starts (daily_limit_reached).
curl -X POST https://api.nacaller.com/api/v1/campaigns \
-H "Authorization: Bearer $NACALLER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "October fee reminder",
"agent_id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e",
"language": "te",
"contacts": [
{ "phone": "+919876543210", "name": "Suresh", "variables": { "fee_amount": "4500" } },
{ "phone": "9123456780", "name": "Lakshmi" }
]
}'{
"id": "e4a90f1b-71d2-4a58-b0c3-6d8f2a9c5e17",
"name": "October fee reminder",
"status": "running",
"agent_id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e",
"contacts": 2,
"skipped_opted_out": 0,
"starts_at": null
}GET /v1/campaigns/{id}/results
Campaign results
One row per contact: whether they picked up, what the agent concluded, the details it captured and the variables you sent. totals covers the whole campaign, not just the page.
| status | Meaning |
|---|---|
received | Picked up. |
not_called | No attempt yet. |
not_answered | Rang, nobody picked up. |
busy / switched_off / disconnected / rejected | The carrier’s reason. |
curl "https://api.nacaller.com/api/v1/campaigns/e4a90f1b-71d2-4a58-b0c3-6d8f2a9c5e17/results?limit=50" \
-H "Authorization: Bearer $NACALLER_API_KEY"{
"campaign": { "id": "e4a90f1b-…", "name": "October fee reminder", "status": "completed",
"language": "te", "agent": "Riya", "created_at": "2026-10-07T05:10:00.000Z" },
"totals": { "contacts": 2, "called": 2, "answered": 1, "opted_out": 0 },
"data": [
{
"contact_id": "0c5b…", "name": "Suresh", "phone": "+919876543210",
"status": "received", "outcome": "interested", "opted_out": false,
"attempts": 1, "talk_seconds": 94, "last_call_at": "2026-10-07T05:14:02.000Z",
"tags": ["hot"], "summary": "Will pay by Friday.",
"captured": {}, "variables": { "fee_amount": "4500" }
}
],
"has_more": false,
"next_cursor": null
}GET /v1/agents
List agents
The agents on your account, with only what you need to pick one: id, name and language. Scripts, voices and settings are not exposed. There is no endpoint to create or edit an agent.
curl https://api.nacaller.com/api/v1/agents \
-H "Authorization: Bearer $NACALLER_API_KEY"{
"data": [
{ "id": "b7f1c2e0-4a3d-4c1e-9d55-0f1a2b3c4d5e", "name": "Riya", "language": "Telugu, English" }
],
"has_more": false,
"next_cursor": null
}Pagination
Cursors, not page numbers.
List endpoints take limit (20 by default, 100 at most) and cursor, and answer with data, has_more and next_cursor. Pass next_cursor back unchanged to get the next page. A cursor is opaque and only works for the key that received it.
# first page
curl "https://api.nacaller.com/api/v1/calls?limit=50" -H "Authorization: Bearer $NACALLER_API_KEY"
# next page: pass next_cursor back, unchanged
curl "https://api.nacaller.com/api/v1/calls?limit=50&cursor=NWQyZjZhMWMt…" -H "Authorization: Bearer $NACALLER_API_KEY"Errors
One shape, always.
Every error has the same JSON body. Branch on error.code, which is stable. The message is for people and may be reworded. Some errors carry extra fields, such as opens_at.
{
"error": {
"code": "outside_calling_hours",
"message": "Calls can only be placed between 9 am and 9 pm India time.",
"opens_at": "2026-10-08T03:30:00.000Z"
}
}| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed. The message names it. |
| 400 | invalid_json | The body is not valid JSON. |
| 400 | invalid_cursor | The cursor is not one this endpoint gave you. |
| 401 | missing_api_key | No Authorization: Bearer header. |
| 401 | invalid_api_key | The key does not exist, or it has been revoked. |
| 402 | no_minutes | No plan minutes and not enough wallet balance to start the call. |
| 403 | account_pending | The account is waiting for approval before it can use calling features. |
| 403 | account_suspended | The account has been suspended. |
| 403 | phone_unverified | Verify the account phone number in the dashboard first. |
| 403 | contact_opted_out | This number asked not to be called. It is never dialled. |
| 403 | number_blocked | This number cannot be called. |
| 403 | international_not_allowed | The account is not approved for international numbers. |
| 404 | agent_not_found | No agent with that id on your account. |
| 404 | call_not_found | No call with that id on your account. |
| 404 | campaign_not_found | No campaign with that id on your account. |
| 409 | calling_paused | Calling is paused on the account. Resume it in the dashboard. |
| 422 | outside_calling_hours | Calls go out between 9 am and 9 pm India time. The error carries opens_at. |
| 422 | agent_paused | That agent is paused. |
| 422 | agent_placeholders | The agent's script still has a [placeholder] it would read aloud. Fill it in. |
| 422 | all_contacts_opted_out | Every contact in the campaign has opted out. |
| 429 | rate_limited | More than 300 requests a minute on one key. Wait for Retry-After. |
| 429 | daily_limit_reached | The key's daily call limit is used up. It resets at midnight India time. |
| 403 | link_expired | A recording link is invalid or older than ten minutes. Fetch the call again. |
| 500 | internal_error | Our side. Safe to retry. |
| 503 | unavailable | Calling is briefly unavailable. Safe to retry. |
Limits
Rate limit, daily limit, and the rules that never bend.
- 300 requests a minute per key. Beyond that you get
429 rate_limitedand aRetry-Afterheader. Every response carriesX-RateLimit-LimitandX-RateLimit-Remaining. - A daily call limit per key, 200 by default and set when you create the key (up to 15,000). A campaign uses one call per contact. It resets at midnight India time. A call that is refused before it rings is not counted.
- Calling hours: 9 am to 9 pm India time, for single calls and campaigns alike.
- Do-not-call: a number that opted out is never dialled, whichever way it was saved.
- Your wallet: calls use your plan minutes first, then your wallet. If both are empty you get
402 no_minutes. - Calling paused in the dashboard pauses the API too (
409 calling_paused).
A 5xx or 503 may be retried. Do not blindly retry a POST /v1/calls that timed out: check GET /v1/calls first so one contact is not rung twice.
Webhooks
Every finished call, posted to you.
In Settings → Developers, add an HTTPS address and copy the signing secret. When a call ends we wait about 45 seconds, so the outcome and transcript are ready, then POST the call.completed event. This covers every call on your account, including the ones you placed with a key. You can send a sample from the same screen.
Check the signature
The X-NaCaller-Signature header is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your signing secret.
- Read the body as raw bytes, before parsing JSON.
- Compute the HMAC and compare in constant time.
- No match: reply
401and ignore the request.
Delivery
- Reply with any
2xxwithin 8 seconds. Do slow work afterwards. - Anything else, or no answer, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then given up on.
- Deliveries are queued separately, so a slow or broken receiver never affects your calls.
- A retry can arrive after the call was already handled. Use
call.idto ignore repeats.
Field-by-field notes and the Google Sheets option: Call results.
{
"event": "call.completed",
"call": {
"id": "5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30",
"direction": "outbound",
"status": "Completed",
"outcome": "interested",
"outcomeReason": "Asked for a site visit on Saturday.",
"startedAt": "2026-10-07T05:14:02.000Z",
"completedAt": "2026-10-07T05:15:43.000Z",
"durationSeconds": 94,
"to": "919876543210",
"from": "918012345678",
"recordingUrl": null,
"transcript": "Agent: Hello Suresh…",
"captured": { "budget": "50 lakh" },
"tags": ["site visit"]
},
"contact": { "id": "0c5b…", "name": "Suresh", "phone": "+919876543210" },
"campaign": { "id": "e4a90f1b-…", "name": "October fee reminder" },
"agent": { "id": "b7f1c2e0-…", "name": "Riya" }
}// Express. Sign-check the RAW body, then parse it.
import express from "express";
import crypto from "node:crypto";
const app = express();
app.post("/webhooks/nacaller", express.raw({ type: "application/json" }), (req, res) => {
const sent = String(req.get("X-NaCaller-Signature") || "");
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.NACALLER_WEBHOOK_SECRET)
.update(req.body) // a Buffer: the exact bytes we sent
.digest("hex");
const ok = sent.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(expected));
if (!ok) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
if (event.event === "call.completed") {
// event.call.id, event.call.outcome, event.call.transcript, event.call.captured …
}
res.sendStatus(204); // reply 2xx quickly; do slow work afterwards
});# Flask. Sign-check the RAW body, then parse it.
import hashlib, hmac, os
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/webhooks/nacaller")
def nacaller():
sent = request.headers.get("X-NaCaller-Signature", "")
expected = "sha256=" + hmac.new(
os.environ["NACALLER_WEBHOOK_SECRET"].encode(),
request.get_data(), # the exact bytes we sent
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(sent, expected):
abort(401)
event = request.get_json()
if event["event"] == "call.completed":
pass # event["call"]["id"], ["outcome"], ["transcript"], ["captured"] …
return "", 204API questions
What the API does, and what it will not let you do
6questions, answered without a sales call. Where an answer is “that part is on you”, we say so.