Campaigns
Create Campaign
Creates a campaign called from one of your live numbers by the assistant assigned to that number. By default it is created as pending and nobody is called until you start it with Start Campaign; send start: true to create and start it in one call.
Request
/v1/campaignsx-api-keyorAuthorization: BearerBody Parameters
| Name | Type | Description |
|---|---|---|
phone_numberrequired | string | One of your live numbers, with or without its country code (+15158003229, 15158003229 and 5158003229 all work). Its assigned assistant makes the calls. |
leadsrequired | object[] | The people to call. Each lead needs "mobile" with its country code. Optional "name", optional "followUpdate" (YYYY-MM-DD HH:mm, Asia/Kolkata, in the future) to hold that call until then, and any other string, number or boolean fields, which the assistant receives as call context. |
concurrent_calls | integer | SIP numbers only: how many calls run at once, capped at the SIP limit. Other providers use your purchased channels. |
start | boolean | true starts the campaign immediately: real calls begin and use your credits. If it cannot start, nothing is created and the error is returned. Defaults to false (created as pending). |
Request Body Example
{
"phone_number": "+918000012345",
"leads": [
{
"mobile": "+919876543210",
"name": "Pankaj",
"plan": "Gold"
},
{
"mobile": "+919812345678",
"name": "Asha",
"followUpdate": "2026-11-02 15:30"
}
]
}Notes
Your account can have one active campaign at a time. Creating another while one is pending, running or paused returns 409 with details.active_campaign_id.
Up to 500 leads per calling channel you have, and never more than 5,000.
Every lead is checked before anything is saved. A 400 lists the bad rows in details.rejected_rows, and nothing is created.
Fields the platform sets itself (apiKey, assistantId, assignedNumber, customerNumber, campaignLeadId, is_demo, jobId, userId) are dropped from leads and listed in ignored_columns.
Campaigns can only be created on your own live numbers through the API, not on shared demo numbers.
With start: true the request is all or nothing: on success the campaign is created and calling; if it cannot start (for example 402, not enough credits) no campaign is left behind, so you can fix the cause and send the same request again.
Response Example
{
"success": true,
"data": {
"campaign": {
"id": "6710b2c3d4e5f60718293a40",
"campaign_number": "48213907",
"status": "pending",
"is_active": true,
"started": false,
"started_at": null,
"phone_number": "+918000012345",
"assistant_id": "66aa2b3c4d5e6f7a8b9c0d11",
"uses_shared_number": false,
"channels": 2,
"leads_submitted": 2,
"leads_queued_for_calls": 1,
"leads_scheduled_for_follow_up": 1,
"progress": {
"total": 2,
"called": 1,
"failed": 0,
"scheduled": 1,
"pending": 0,
"cancelled": 0,
"percent_complete": 50,
"is_finished": false
},
"failure_reason": null,
"created_at": "2026-10-19T09:30:00.000Z",
"updated_at": "2026-10-19T09:33:00.000Z",
"completed_at": null
},
"ignored_columns": [],
"message": "Campaign #48213907 created with 2 lead(s). It will not dial until it is started."
}
}Status Codes
| HTTP | Meaning | Description |
|---|---|---|
| 201 | Created | Resource was created. |
| 400 | Bad request | Invalid leads, too many leads, or phone_number is not a live number of yours with an assistant (and, for SIP, a trunk). |
| 401 | Unauthorized | Missing, invalid, inactive, or origin-restricted API key. |
| 402 | Payment required | start: true was sent and your credits are too low to start. Nothing was created. |
| 409 | Conflict | Another campaign is still active on your account. |
| 415 | Unsupported media type | Content-Type header is missing or is not application/json. |
| 422 | Validation error | JSON body failed schema or business validation. |
| 429 | Rate limited | Per-IP or per-key request budget was exceeded. |