Quickstart
Create an API key, make your first request, and start a campaign that calls your leads.
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
- Sign in to the console and open Settings → Developers.
- Choose Create key, give it a name (for example
crm-sync), and pick its access and expiry. See Authentication for what each option does. - 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:
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
List your agents. Every request sends the key in the X-API-Key header.
curl https://api.callmitra.ai/api/v1/agents/ \
-H "X-API-Key: $CALLMITRA_API_KEY"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 with a stable error.code.
Pick a caller ID
List the phone numbers connected to your workspace and note the id of the number to call from:
curl https://api.callmitra.ai/api/v1/phone-numbers/ \
-H "X-API-Key: $CALLMITRA_API_KEY"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…).
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" } }
]
}'The response contains campaignId and processedLeads. attributes are extra fields your agent can use in the conversation.
Start the campaign
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, or list results with GET /api/v1/calls/?campaignId=CAMPAIGN_ID.
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:
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 signature over the raw body:
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 for Python, PHP and Go, and Webhooks for retries, de-duplication and every event.