Campaigns API

All endpoints require Authorization: Bearer <your-api-key>. Replace {id} with the campaign ID.

Campaigns

`POST /api/campaigns` — create draft

{
  "name": "Q2 Renewals",
  "agentId": "agent_xxx",
  "phoneNumberId": "pn_xxx",
  "agentVersion": 7,                    // optional — defaults to agent.currentVersion
  "maxConcurrent": 5,                   // 1–50
  "scheduledStartAt": "2026-05-08T09:00:00+05:30",  // optional
  "schedule": {
    "timezone": "Asia/Kolkata",
    "windowStart": "09:00",
    "windowEnd": "19:00",
    "weekdays": [1,2,3,4,5]
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffMinutes": 60,
    "retryOn": ["no_answer", "busy"]
  },
  "webhookUrl": "https://your-crm/webhooks/osmtalk"
}

`GET /api/campaigns?status=running`

`GET /api/campaigns/{id}`

`PUT /api/campaigns/{id}` — same shape as create (partial allowed)

`DELETE /api/campaigns/{id}` — only when draft / completed / failed

Lifecycle transitions

Endpoint	Allowed from
`POST /api/campaigns/{id}/start`	`draft`, `scheduled`
`POST /api/campaigns/{id}/pause`	`running`
`POST /api/campaigns/{id}/resume`	`paused`
`POST /api/campaigns/{id}/stop`	`running`, `paused`, `scheduled`

Leads

`POST /api/campaigns/{id}/leads` — upload

Three accepted body formats:

CSV (Content-Type: text/csv) — preferred for spreadsheet exports

phone,first_name,company
+919876543210,Arjun,Acme
+919876543211,Meera,BlueLeaf

JSON array

{
  "leads": [
    { "phoneNumber": "+919876543210", "variables": { "first_name": "Arjun" } },
    { "phoneNumber": "+919876543211", "variables": { "first_name": "Meera" } }
  ]
}

CSV inside JSON

{ "csv": "phone,first_name\n+919876543210,Arjun" }

Response:

{ "inserted": 2, "csvErrors": [] }

`GET /api/campaigns/{id}/leads`

Query	Type	Notes
`status`	string	Filter
`limit`	int	1–1000 (default 200)
`offset`	int	Pagination

Report

`GET /api/campaigns/{id}/report`

Returns { campaign, counts: { byStatus, byDisposition } }.

DNC list

`GET /api/campaigns/dnc`

`POST /api/campaigns/dnc`

{
  "phoneNumber": "+919876543210",
  "reason": "Customer email opt-out",
  "source": "manual"
}

`POST /api/campaigns/dnc/bulk`

{
  "entries": [
    { "phoneNumber": "+919876543210", "source": "imported" },
    { "phoneNumber": "+919876543211", "source": "imported" }
  ]
}

Up to 50,000 entries. Duplicates ignored.

`DELETE /api/campaigns/dnc/{id}`

Webhook event

See Outcomes & Webhooks for the full payload + signing.

{
  "event": "campaign.lead_completed",
  "timestamp": "...",
  "campaign": { "id": "...", "name": "..." },
  "lead": { "id": "...", "phoneNumber": "...", "status": "...", "disposition": "...", "attempts": 1, "callId": "...", "outcome": { ... } }
}

Error responses

Code	Meaning
400	Validation failed; body has `error` / `details`
401	Missing or invalid API key
402	Insufficient credits
404	Campaign / agent / phone number not found
429	Concurrency limit hit (rare for campaigns since they queue)
500	Bot spawn or SIP failure

On this page