Campaigns Reference

Endpoints for creating, launching, and monitoring broadcast campaigns across groups, contacts, and direct CRM recipients.

POST

/api/v1/campaigns

Creates a new broadcast campaign draft associated with an approved template.

Headers

Header	Required	Description
Authorization	Yes	Bearer ps_secret_live_YOUR_API_KEY
Content-Type	Yes	application/json

Request Body Parameters

Field	Type	Required	Description
name	string	Yes	Human-readable campaign name
template_id	string	No	Template UUID in PingStack
template_name	string	No	Approved Meta template name (e.g. fee_reminder)
scheduled_at	string	No	ISO-8601 future timestamp for scheduled dispatch (Growth/Pro plan)

Code Example (5 Languages)

curl -X POST "https://app.pingstack.in/api/v1/campaigns" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "September Fee Reminders", "template_name": "fee_reminder"}'

Response Example

JSON

{
  "success": true,
  "data": {
    "id": "c8a1b2c3-1d2e-4f5a-b6c7-8d9e0f1a2b3c",
    "name": "September Fee Reminders",
    "template_id": "tpl_fee_01",
    "status": "draft",
    "created_at": "2026-09-10T08:00:00.000Z"
  },
  "request_id": "req_1a2b3c4d"
}

POST

/api/v1/campaigns/{id}/launch

Triggers broadcast delivery across audience groups, contact lists, or direct CRM recipient arrays with template variables.

Headers

Header	Required	Description
Authorization	Yes	Bearer ps_secret_live_YOUR_API_KEY
Idempotency-Key	No	Unique request key for safe network retries

Request Body Parameters

Field	Type	Required	Description
recipients	array	No	Direct CRM recipient objects: [{ phone, variables: {"1": "Val"}, name }]
group_ids	array	No	Array of audience group IDs in PingStack
contact_ids	array	No	Array of contact IDs in PingStack
template_variables	object	No	Shared template variables applied to all group/contact recipients (supports {{name}} and {{phone}} macros)

Code Example (5 Languages)

curl -X POST "https://app.pingstack.in/api/v1/campaigns/CAMPAIGN_ID/launch" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fee-batch-sep-01" \
  -d '{
    "recipients": [
      { "phone": "919876543210", "variables": { "1": "Rahul", "2": "₹2,500" } },
      { "phone": "919876543211", "variables": { "1": "Amit", "2": "₹1,800" } }
    ]
  }'

Response Example

JSON

{
  "success": true,
  "data": {
    "campaign_id": "c8a1b2c3-1d2e-4f5a-b6c7-8d9e0f1a2b3c",
    "name": "September Fee Reminders",
    "status": "running",
    "queued_at": "2026-09-10T08:00:00.000Z"
  },
  "request_id": "req_5a6b7c8d"
}

GET

/api/v1/campaigns/{id}/results

Returns real-time delivery metrics, sent counts, read rates, and failure tallies for a campaign.

Code Example (5 Languages)

curl "https://app.pingstack.in/api/v1/campaigns/CAMPAIGN_ID/results" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY"

Response Example

JSON

{
  "success": true,
  "data": {
    "campaign_id": "c8a1b2c3-1d2e-4f5a-b6c7-8d9e0f1a2b3c",
    "name": "September Fee Reminders",
    "status": "completed",
    "metrics": {
      "total_messages": 250,
      "pending": 0,
      "sent": 248,
      "delivered": 245,
      "read": 192,
      "failed": 2,
      "delivered_rate_pct": 98,
      "read_rate_pct": 77
    }
  },
  "request_id": "req_6b7c8d9e"
}

All Reference Endpoints