Campaigns API

Lifecycle management for outbound calling campaigns

Overview

A Campaign is the top-level container that defines how calls are made: which agent speaks, which phone numbers are used, when calls are allowed, and what retry logic to apply. Every Batch belongs to exactly one campaign and inherits its settings.

Base URL: https://api.graine.ai/api/v1

Authentication: All campaign endpoints require Authorization: Bearer gat_<token>.

Campaign Object

{
  "campaign_id": "cmp_abc123",
  "name": "Q2 Insurance Renewals",
  "organization_id": "org_xyz",
  "agent_id": "agent_abc123",
  "status": "active",
  "phone_numbers": ["[phone]", "[phone]"],
  "phone_number_strategy": "round_robin",
  "working_hours_enforced": true,
  "timezone": "Asia/Kolkata",
  "working_hours": {
    "monday":    { "start": "09:00", "end": "18:00", "enabled": true },
    "tuesday":   { "start": "09:00", "end": "18:00", "enabled": true },
    "wednesday": { "start": "09:00", "end": "18:00", "enabled": true },
    "thursday":  { "start": "09:00", "end": "18:00", "enabled": true },
    "friday":    { "start": "09:00", "end": "18:00", "enabled": true },
    "saturday":  { "start": "10:00", "end": "14:00", "enabled": false },
    "sunday":    { "start": "10:00", "end": "14:00", "enabled": false }
  },
  "retry_policy": {
    "max_retries": 3,
    "strategy": "fixed",
    "cooldown_minutes": 30
  },
  "default_call_variables": {
    "language": "en",
    "product": "Health Insurance"
  },
  "metadata": {
    "concurrency_limit": 20
  }
}

Campaign Fields

Field	Type	Description
campaign_id	string	Unique identifier for the campaign
name	string	Human-readable campaign name
organization_id	string	Owning organization. Defaults to token’s org if omitted
agent_id	string	The AI agent that makes the calls
status	string	Current state: draft · active · paused · cancelled · completed
phone_numbers	string[]	Outbound caller IDs to use
phone_number_strategy	string	How to pick numbers: round_robin · random · least_loaded
working_hours_enforced	boolean	If true, calls only go out within per-day windows
timezone	string	IANA timezone for working hours (e.g. Asia/Kolkata)
working_hours	object	Per-day { start, end, enabled } schedule
retry_policy	object	max_retries, strategy (fixed/exponential), cooldown_minutes
default_call_variables	object	Variables merged into every contact’s call (contact-level values win)
metadata.concurrency_limit	integer	Max concurrent outbound calls across all batches

Campaign Status Lifecycle

Status	Description
draft	Created but no batches yet
active	Dispatching calls
paused	Temporarily stopped — resumes with /resume
cancelled	Hard-stopped. Terminal — cannot resume
completed	All batches finished naturally

Endpoints

Create Campaign

POST /campaigns/

List Campaigns

GET /campaigns/

Get Campaign

GET /campaigns/:id

Update Campaign

PATCH /campaigns/:id

Delete Campaign

DELETE /campaigns/:id

Pause / Resume / Cancel

Control campaign execution

Campaign Stats

GET /campaigns/:id/stats