Skip to Content
CallMitraDocs

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:

leadSourceTypeSendUse when
bulk_uploaduploadedLeads: an array of leads (name, phone in E.164, optional email, company, title, notes, externalId, attributes)The leads come from your system.
existing_leadsselectedLeadIds and/or selectedLeadSourceIdsThe 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:

FieldDefaultMeaning
dialWindowStart / dialWindowEnd10:00 / 17:00Local HH:MM window. Calls are placed only inside it.
dialTimezoneAsia/KolkataTime zone of the window.
dialDaysOfWeekevery day0 = Monday … 6 = Sunday.
maxCallsPerDay50Calls placed per day.
retryAttempts3Attempts per lead.
retryIntervalBusyMs1800000 (30 min)Wait before retrying a busy line.
retryIntervalNoAnswerMs—Wait before retrying an unanswered call.
callInterval7200000 (2 h)Minimum gap between attempts to the same lead.
autoDialEnabledtrueDial automatically while the campaign is running.

Numbers on your do-not-call list are never dialed.

3. Start, pause, resume, stop

ActionEndpointEffect
StartPOST …/{campaign_id}/startBegins dialing inside the window, up to the daily limit.
PausePOST …/{campaign_id}/pause-dialingNo new calls. The campaign stays active.
ResumePOST …/{campaign_id}/resume-dialingContinues where it left off.
StopPOST …/{campaign_id}/stopCancels calls waiting to be placed. A call in progress finishes.

Stop is safe to repeat. Start and resume can be refused:

StatusCodeWhen
422campaign_not_readyStart: 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.
402payment_requiredStart: the workspace has no balance or plan.
400bad_requestStart: the campaign's phone number cannot place calls (param: "phoneNumberId").
409campaign_not_runningResume: the campaign is stopped. Start it first.
404campaign_not_foundThe 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:

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.

On this page