# Campaigns & bulk calling (/guides/campaigns)

A **campaign** pairs an [agent](/api-reference/agents/listAgents) 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 [#1-create-the-campaign]

[`POST /api/v1/campaigns/create-with-leads`](/api-reference/campaigns/createCampaignWithLeads) 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/`](/api-reference/leads/createLead) or a lead intake webhook). |

```json
{
  "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](/webhooks/campaign-agent-webhooks) for this campaign's calls. For new integrations, register a [webhook endpoint](/webhooks/endpoints) 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`](/errors/campaign_default_inbound_exists).

To create an empty campaign and add leads later, use [`POST /api/v1/campaigns/`](/api-reference/campaigns/createCampaign) and then [`PUT /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/updateCampaignLeads) 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`](/errors/campaign_leads_need_confirmation) with those IDs in `detail.leadIds`; resend with `confirmRemovedContacted: true` to remove them anyway.

See [Leads and callbacks](/guides/leads) for lead fields, attributes and phone number rules.

## 2. Calling schedule [#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](/api-reference/do-not-call/listDoNotCall) are never dialed.

## 3. Start, pause, resume, stop [#3-start-pause-resume-stop]

| Action | Endpoint | Effect |
| --- | --- | --- |
| Start | [`POST …/{campaign_id}/start`](/api-reference/campaigns/startCampaign) | Begins dialing inside the window, up to the daily limit. |
| Pause | [`POST …/{campaign_id}/pause-dialing`](/api-reference/campaigns/pauseCampaignDialing) | No new calls. The campaign stays active. |
| Resume | [`POST …/{campaign_id}/resume-dialing`](/api-reference/campaigns/resumeCampaignDialing) | Continues where it left off. |
| Stop | [`POST …/{campaign_id}/stop`](/api-reference/campaigns/stopCampaign) | 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`](/errors/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`](/errors/payment_required) | Start: the workspace has no balance or plan. |
| `400` | [`bad_request`](/errors/bad_request) | Start: the campaign's phone number cannot place calls (`param: "phoneNumberId"`). |
| `409` | [`campaign_not_running`](/errors/campaign_not_running) | Resume: the campaign is stopped. Start it first. |
| `404` | [`campaign_not_found`](/errors/campaign_not_found) | The campaign does not exist in your workspace. |

## 4. Check progress [#4-check-progress]

[`GET /api/v1/campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus) 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=…`](/api-reference/calls/listCalls), and the campaign's leads with [`GET /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/listCampaignLeads).

## 5. Get results [#5-get-results]

Each finished call sends a [`call.completed`](/webhooks/events) event to the campaign's `crmWebhookUrl` and to every [webhook endpoint](/webhooks/endpoints) 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}`](/api-reference/calls/getCall).

## Call one lead now [#call-one-lead-now]

To call a lead immediately, outside the schedule, use [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow) with `leadId` and a running `campaignId`, or [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) 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`).

```json
{
  "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:

- `409` [`campaign_not_running`](/errors/campaign_not_running): the campaign is not running. For `callLeadNow`, the lead is on campaigns but none is running.
- `422` [`lead_has_no_campaign`](/errors/lead_has_no_campaign): `callLeadNow` only; the lead is on no outbound campaign with an agent.
- `409` [`number_on_dnc`](/errors/number_on_dnc), `409` [`lead_call_in_progress`](/errors/lead_call_in_progress), `402` [`payment_required`](/errors/payment_required).
- `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached), [`campaign_dial_busy`](/errors/campaign_dial_busy) or [`carrier_capacity_reached`](/errors/carrier_capacity_reached), and `429` [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached): a capacity limit. Retry after a short wait.

The full list is under [Calling refusals](/errors#calling-refusals).

## Callbacks [#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=…`](/api-reference/campaigns/listCallbacks) and see [Leads and callbacks](/guides/leads#callbacks) for how they work.