Campaigns & bulk calling
Create a campaign with its leads, control dialing, and follow results.
A campaign pairs an agent with a list of leads, a caller ID and a calling schedule. Once started, CallMitra dials each lead inside the schedule, retries unanswered calls, and reports every result to your webhook.
1. Create the campaign
POST /api/v1/campaigns/create-with-leads creates the campaign and attaches its leads in one request. Choose the lead source with leadSourceType:
leadSourceType | Send | Use when |
|---|---|---|
bulk_upload | uploadedLeads: an array of leads (name, phone in E.164, optional email, company, title, notes, externalId, attributes) | The leads come from your system. |
existing_leads | selectedLeadIds and/or selectedLeadSourceIds | The leads already exist in CallMitra (created with POST /api/v1/leads/ or a lead intake webhook). |
{
"campaignData": {
"name": "November renewals",
"agentId": "AGENT_ID",
"phoneNumberId": "PHONE_NUMBER_ID",
"crmWebhookUrl": "https://example.com/webhooks/callmitra",
"crmWebhookSecret": "a-long-random-secret",
"settings": {
"dialWindowStart": "10:00",
"dialWindowEnd": "18:00",
"dialTimezone": "Asia/Kolkata",
"dialDaysOfWeek": [0, 1, 2, 3, 4, 5],
"maxCallsPerDay": 200,
"retryAttempts": 3
}
},
"leadSourceType": "bulk_upload",
"uploadedLeads": [
{ "name": "Asha Rao", "phone": "+919876543210", "externalId": "crm-1042", "attributes": { "plan": "Gold" } }
]
}The response returns campaignId and processedLeads. attributes and externalId stay on the lead, so your agent can use them in the conversation and you can match results back to your records. Use copySettingsFromCampaignId to reuse the schedule of an earlier campaign.
crmWebhookUrl and crmWebhookSecret set an optional campaign webhook for this campaign's calls. For new integrations, register a webhook endpoint once instead: it receives events from every campaign.
For inbound campaigns, a phone number can have only one default inbound campaign (isDefaultInbound: true), which answers callers that no other campaign claims. Asking for a second one on the same number returns 409 campaign_default_inbound_exists.
To create an empty campaign and add leads later, use POST /api/v1/campaigns/ and then PUT /api/v1/campaigns/{campaign_id}/leads with added and removed lists of lead IDs. A removed lead keeps its call history, and adding it again revives it rather than duplicating it. Removing a lead that was already called returns 409 campaign_leads_need_confirmation with those IDs in detail.leadIds; resend with confirmRemovedContacted: true to remove them anyway.
See Leads and callbacks for lead fields, attributes and phone number rules.
2. Calling schedule
All schedule fields live in campaignData.settings and have defaults:
| Field | Default | Meaning |
|---|---|---|
dialWindowStart / dialWindowEnd | 10:00 / 17:00 | Local HH:MM window. Calls are placed only inside it. |
dialTimezone | Asia/Kolkata | Time zone of the window. |
dialDaysOfWeek | every day | 0 = Monday … 6 = Sunday. |
maxCallsPerDay | 50 | Calls placed per day. |
retryAttempts | 3 | Attempts per lead. |
retryIntervalBusyMs | 1800000 (30 min) | Wait before retrying a busy line. |
retryIntervalNoAnswerMs | — | Wait before retrying an unanswered call. |
callInterval | 7200000 (2 h) | Minimum gap between attempts to the same lead. |
autoDialEnabled | true | Dial automatically while the campaign is running. |
Numbers on your do-not-call list are never dialed.
3. Start, pause, resume, stop
| Action | Endpoint | Effect |
|---|---|---|
| Start | POST …/{campaign_id}/start | Begins dialing inside the window, up to the daily limit. |
| Pause | POST …/{campaign_id}/pause-dialing | No new calls. The campaign stays active. |
| Resume | POST …/{campaign_id}/resume-dialing | Continues where it left off. |
| Stop | POST …/{campaign_id}/stop | Cancels calls waiting to be placed. A call in progress finishes. |
Stop is safe to repeat. Start and resume can be refused:
| Status | Code | When |
|---|---|---|
422 | campaign_not_ready | Start: the campaign cannot dial yet. The message lists what to fix: no agent, placeholders in the prompt that no lead can fill, missing IVR clips, or an inbound campaign with no callers. Also returned by create-with-leads and campaign update. |
402 | payment_required | Start: the workspace has no balance or plan. |
400 | bad_request | Start: the campaign's phone number cannot place calls (param: "phoneNumberId"). |
409 | campaign_not_running | Resume: the campaign is stopped. Start it first. |
404 | campaign_not_found | The campaign does not exist in your workspace. |
4. Check progress
GET /api/v1/campaigns/{campaign_id}/dial-status explains whether the campaign is placing calls right now and, if not, why:
dialingAllowed,inDialWindow,skipReason— whether calls go out now, and the reason when they do not.callsToday/maxCallsPerDay,pendingJobCount— today's volume and the queue.nextWindowOpenAt,nextEligibleDialAt— when dialing resumes.lastErrorCode,lastErrorMessage,lastErrorAt— the most recent dialing error.
List the calls themselves with GET /api/v1/calls/?campaignId=…, and the campaign's leads with GET /api/v1/campaigns/{campaign_id}/leads.
5. Get results
Each finished call sends a call.completed event to the campaign's crmWebhookUrl and to every webhook endpoint subscribed to it. It contains the status, duration, transcript, summary, outcome and the fields your agent extracted. You can also fetch any call with GET /api/v1/calls/{call_id}.
Call one lead now
To call a lead immediately, outside the schedule, use POST /api/v1/instant/call-now with leadId and a running campaignId, or POST /api/v1/leads/{lead_id}/call-now to use the first running outbound campaign the lead belongs to. The response wraps the call in call: read call.id and call.status (usually initiated or queued).
{
"success": true,
"call": {
"id": "7c0e5a2b-1d3f-4e6a-9b8c-2f1e0d9c8b7a",
"leadId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
"campaignId": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d",
"status": "initiated"
}
}Common refusals:
409campaign_not_running: the campaign is not running. ForcallLeadNow, the lead is on campaigns but none is running.422lead_has_no_campaign:callLeadNowonly; the lead is on no outbound campaign with an agent.409number_on_dnc,409lead_call_in_progress,402payment_required.409campaign_call_limit_reached,campaign_dial_busyorcarrier_capacity_reached, and429concurrent_call_limit_reached: a capacity limit. Retry after a short wait.
The full list is under Calling refusals.
Callbacks
When a caller asks to be called later, an agent with the schedule-callback tool books a callback, and CallMitra dials it inside the campaign's calling window. Each campaign limits callback attempts (2 by default). List booked callbacks with GET /api/v1/callbacks?campaignId=… and see Leads and callbacks for how they work.