Skip to Content
CallMitraDocs

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

  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 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:

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.

Next steps

On this page