No setup fees. No hidden charges. Best pricing in the industry. See pricing

Sign inStart free

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.

  1. In the dashboard, open Settings, then Developers, and create a key. It is shown once.
  2. List your agents and pick the one that should call.
  3. Place the call, then read it back by its id.
Shell
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:

Header
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.
Hashed at rest

Only the SHA-256 of your key is stored.

Same gates as the dashboard

A suspended, unapproved or unverified account cannot use a key.

Per-key limits

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.

FieldNotes
agent_idRequired. An id from GET /v1/agents.
phoneRequired. A mobile number: +919876543210 or 10 digits.
nameOptional. Used the first time the contact is saved.
variablesOptional. Up to 20 text fields, such as fee_amount, that fill {{fee_amount}} in the agent’s script.
languageOptional. 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
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" }
  }'
Response
{
  "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.

QueryNotes
statusOptional. For example Completed, No Answer, Busy, Failed.
agent_idOptional. Only this agent’s calls.
campaign_idOptional. Only this campaign’s calls.
limit / cursorSee Pagination.
curl
curl "https://api.nacaller.com/api/v1/calls?limit=2&status=Completed" \
  -H "Authorization: Bearer $NACALLER_API_KEY"
Response
{
  "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
curl https://api.nacaller.com/api/v1/calls/5d2f6a1c-93b0-4f0e-8a77-2c9e4d1b6a30 \
  -H "Authorization: Bearer $NACALLER_API_KEY"
Response
{
  "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.

FieldNotes
nameRequired.
agent_idRequired.
contactsRequired. Up to 10000 per request, each with phone and optional name and variables. The same number twice is called once.
languageOptional. 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
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" }
    ]
  }'
Response
{
  "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.

statusMeaning
receivedPicked up.
not_calledNo attempt yet.
not_answeredRang, nobody picked up.
busy / switched_off / disconnected / rejectedThe carrier’s reason.
curl
curl "https://api.nacaller.com/api/v1/campaigns/e4a90f1b-71d2-4a58-b0c3-6d8f2a9c5e17/results?limit=50" \
  -H "Authorization: Bearer $NACALLER_API_KEY"
Response
{
  "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
curl https://api.nacaller.com/api/v1/agents \
  -H "Authorization: Bearer $NACALLER_API_KEY"
Response
{
  "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.

curl
# 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
{
  "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"
  }
}
HTTPcodeWhen
400invalid_requestA field is missing or malformed. The message names it.
400invalid_jsonThe body is not valid JSON.
400invalid_cursorThe cursor is not one this endpoint gave you.
401missing_api_keyNo Authorization: Bearer header.
401invalid_api_keyThe key does not exist, or it has been revoked.
402no_minutesNo plan minutes and not enough wallet balance to start the call.
403account_pendingThe account is waiting for approval before it can use calling features.
403account_suspendedThe account has been suspended.
403phone_unverifiedVerify the account phone number in the dashboard first.
403contact_opted_outThis number asked not to be called. It is never dialled.
403number_blockedThis number cannot be called.
403international_not_allowedThe account is not approved for international numbers.
404agent_not_foundNo agent with that id on your account.
404call_not_foundNo call with that id on your account.
404campaign_not_foundNo campaign with that id on your account.
409calling_pausedCalling is paused on the account. Resume it in the dashboard.
422outside_calling_hoursCalls go out between 9 am and 9 pm India time. The error carries opens_at.
422agent_pausedThat agent is paused.
422agent_placeholdersThe agent's script still has a [placeholder] it would read aloud. Fill it in.
422all_contacts_opted_outEvery contact in the campaign has opted out.
429rate_limitedMore than 300 requests a minute on one key. Wait for Retry-After.
429daily_limit_reachedThe key's daily call limit is used up. It resets at midnight India time.
403link_expiredA recording link is invalid or older than ten minutes. Fetch the call again.
500internal_errorOur side. Safe to retry.
503unavailableCalling 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_limited and a Retry-After header. Every response carries X-RateLimit-Limit and X-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).
Retrying safely

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.

  1. Read the body as raw bytes, before parsing JSON.
  2. Compute the HMAC and compare in constant time.
  3. No match: reply 401 and ignore the request.

Delivery

  • Reply with any 2xx within 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.id to ignore repeats.

Field-by-field notes and the Google Sheets option: Call results.

The event
{
  "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" }
}
Node (Express)
// 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
});
Python (Flask)
# 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 "", 204

API 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.

What can I do with the NaCaller API?
Place a call with one of your agents, start a campaign from a list of contacts, and read back every call: its outcome, summary, sentiment, lead score, transcript and a short-lived recording link. You can also have each finished call posted to your own server as a signed webhook.
Can the API create or change my agents?
No. Agents are written and tested in the dashboard, where you can hear them before they go live. The API reads your agent list (id, name, language) and uses an agent you chose; it cannot create, edit or delete one.
Do API calls follow the same rules as calls from the dashboard?
Yes, through the same code. A number that opted out is never dialled, calls only go out between 9 am and 9 pm India time, and your own plan minutes and wallet pay for them. An API key can only ever see and spend what its owner can.
How many calls can one key place?
Each key has its own daily limit, 200 calls by default and up to 15,000 when you create it. It resets at midnight India time. Separately, a key is limited to 300 requests a minute.
Is the recording link permanent?
No. The call endpoint returns a signed link that stops working after 10 minutes. Ask for the call again whenever you need a fresh one. We never hand out a permanent public address for audio.
I lost my API key. Can you show it again?
No. We only keep a one-way fingerprint of each key, so nobody at NaCaller can read it back to you either. Revoke the lost key in Settings under Developers and create a new one; the old one stops working immediately.
Call meStart free