Campaigns

Create outbound call campaigns with multiple contacts, alternate numbers per contact, and optional caller-ID rotation across dial attempts.

Create a campaign

POST /v1/campaigns

Create a campaign in DRAFT (or SCHEDULED when scheduledAt is set). Use startImmediately: true to start it in the same request.

Required scope: campaigns:write

Request body

Field	Type	Required	Description
name	string	Yes	Campaign name
agentId	string	Yes	AI agent ID
fromNumber	string	Yes	Primary caller ID (E.164, must belong to your org)
contacts	array	Yes	Contact rows (see below)
description	string	No	Optional description
fromNumberAttempts	string[]	No	Outbound numbers per dial attempt (E.164). Used when maxRetries > 0
fromNumberStrategy	string	No	rolling, clamp, or custom — how to pick fromNumberAttempts when there are fewer numbers than attempts
contactAttemptStrategy	string	No	rolling, clamp, or custom — how to pick contact_attempts when there are fewer alternates than attempts
variableMapping	object	No	Maps contact field names to agent prompt variables
maxRetries	integer	No	Failed-call retries per contact (0–5, default 0)
retryDelayMinutes	integer	No	Minutes between retries (min 5 when maxRetries > 0, default 30)
callingDays	integer[]	No	Allowed weekdays (0 = Sunday … 6 = Saturday)
callingStartTime	string	No	Calling window start (HH:MM)
callingEndTime	string	No	Calling window end (HH:MM)
timezone	string	No	IANA timezone (default Europe/Rome)
maxConcurrency	integer	No	Max simultaneous calls for this campaign
keepFreeForInbound	integer	No	Slots reserved for inbound calls (default 0)
scheduledAt	string	No	ISO 8601 — schedule for later (SCHEDULED status)
startImmediately	boolean	No	If true, starts the campaign after creation

Contact object

Each item in contacts must include phone_number (E.164). Any other fields can be mapped to prompt variables via variableMapping.

Field	Type	Description
phone_number	string	Required. Number called on attempt 1
contact_attempts	array	Optional alternate numbers/variables for retries (attempt 2+)

Each contact_attempts entry is an object with at least phone_number, plus optional fields (for example name) that override the primary contact fields for that attempt.

Total dial attempts per contact = 1 + maxRetries (attempt 1 is the initial call, then up to maxRetries retries).

Example

curl -X POST https://api.replicer.ai/v1/campaigns \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 follow-up",
    "agentId": "clx-agent-001",
    "fromNumber": "+39000000001",
    "fromNumberAttempts": ["+39000000001", "+39000000002"],
    "fromNumberStrategy": "rolling",
    "contactAttemptStrategy": "clamp",
    "maxRetries": 2,
    "retryDelayMinutes": 30,
    "contacts": [
      {
        "phone_number": "+39111111111",
        "name": "Mario Rossi",
        "company": "Acme",
        "contact_attempts": [
          { "phone_number": "+39222222222", "name": "Luigi Bianchi" }
        ]
      }
    ],
    "variableMapping": {
      "customer_name": "name",
      "company_name": "company"
    },
    "startImmediately": true
  }'

Response 201 Created

{
  "data": {
    "id": "clx-campaign-001",
    "status": "RUNNING",
    "taskId": "task-xyz-123"
  },
  "requestId": "req-abc123"
}

When startImmediately is false, status is DRAFT and taskId is omitted.

---

Start a campaign

POST /v1/campaigns/{id}/start

Start or resume a campaign (DRAFT, SCHEDULED, or PAUSED).

Required scope: campaigns:write

Response 200 OK

{
  "data": {
    "id": "clx-campaign-001",
    "status": "RUNNING",
    "taskId": "task-xyz-123"
  },
  "requestId": "req-abc123"
}

---

List campaigns

GET /v1/campaigns

Required scope: campaigns:read

Query parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)
status	string	Filter by status (DRAFT, RUNNING, COMPLETED, …)

---

Get a campaign

GET /v1/campaigns/{id}

Returns the campaign including contacts, fromNumberAttempts (as E.164), and progress counters.

Required scope: campaigns:read

Attempt strategies

Both fromNumberStrategy and contactAttemptStrategy accept:

Value	Behavior
rolling	Cycles through the configured list
clamp	Uses each entry in order, then repeats the last
custom	For caller IDs: one number per attempt slot. For contacts: uses each alternate once, then falls back to the primary number

---

Errors

Code	Cause
validation_error	Missing fields, invalid strategy, or contact without phone_number
forbidden	No active subscription or insufficient balance
not_found	Campaign or agent not found