Manage campaigns via API (create, list, detail, cancel)

Automate your broadcasts with the Omnifox REST API: create, list, fetch detail with stats and cancel campaigns straight from your own systems.

Jun 26, 2026

What it's for

The Omnifox REST API lets you drive Broadcasts from your CRM, ERP or any custom integration without opening the panel. Every resource lives under /api/v1/ and is authenticated with a Bearer token pinned to a single workspace.

Requirements

  • A workspace API token (generate it under Settings → API Keys).
  • A plan with REST API access (from Crece). Broadcasts themselves are on all plans, with monthly caps.
  • Creating and cancelling campaigns requires the admin or owner role; an agent can only list and view.

Always send the Authorization: Bearer YOUR_TOKEN and Accept: application/json headers. Responses use the envelope { "success", "data", "message" }.

1. Create a campaign

POST /api/v1/broadcasts
{
  "channel_id": 12,
  "name": "June promo",
  "type": "whatsapp_template",
  "whatsapp_template_id": 84,
  "segment_filters": { "group_ids": [3, 7] },
  "scheduled_at": "2026-06-30T15:00:00Z"
}
  • type accepts whatsapp_template, sms or email.
  • For whatsapp_template the whatsapp_template_id field is required; for sms/email send message_content.
  • Omit scheduled_at and pass "send_now": true to send immediately.
  • Returns 201 with the created campaign.

2. List campaigns

GET /api/v1/broadcasts?status=sending&channel_id=12&sort=created_at

Available filters: status, channel_id, type. Sort by created_at or scheduled_at.

3. Fetch detail with stats

GET /api/v1/broadcasts/{id}

Returns the campaign with its channel and template, plus a stats object holding the sent, delivered, read, replied, failed, pending counters.

4. Cancel a campaign

POST /api/v1/broadcasts/{id}/cancel

Only a campaign in draft, scheduled or sending status can be cancelled. Pending recipients move to failed with the reason "Broadcast cancelled". If the campaign already finished, it returns 422.

Verify

After creating, call the detail endpoint and confirm the status moves from scheduled/sending to sent. A 402 means you hit one of your plan's broadcast caps (for example, the monthly recipient cap).

Tips

  • The token is bound to one workspace: you don't need to (and can't) operate on a different workspace_id.
  • Reuse your groups and tags in segment_filters so you don't recompute audiences.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp