Skip to main content
POST
/
v1
/
calls
/
batch
Create batch campaign
curl --request POST \
  --url https://api.nixflex.com/v1/calls/batch

Documentation Index

Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt

Use this file to discover all available pages before exploring further.

Creates a batch campaign: queues many outbound calls under one campaign ID. Useful for appointment reminders, lead qualification, surveys.

​
Request

curl -X POST https://api.nixflex.com/v1/calls/batch \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_125207e452f8714a",
    "from_number": "+447446466847",
    "name": "Tuesday appointment reminders",
    "recipients": [
      { "phone_number": "+447111000001" },
      { "phone_number": "+447111000002", "dynamic_vars": { "patient_name": "John" } },
      { "phone_number": "+447111000003" }
    ],
    "schedule_type": "now",
    "max_concurrent": 5
  }'

​
Body parameters

FieldTypeRequiredNotes
agent_idstringYesAgent used for all calls in this batch
from_numberstringYesYour Twilio number to dial from
namestringYesDisplay name for the campaign
recipientsarrayYesUp to 10,000 recipients
schedule_typeenumYesnow (launch immediately) or schedule
scheduled_atISO dateIf scheduleWhen to launch
max_concurrentintNoCap concurrent calls (default: account limit)
metadataobjectNoEchoed in every call’s webhook

​
Recipient object

{
  "phone_number": "+447111000001",
  "dynamic_vars": { "patient_name": "Sarah" },
  "metadata": { "lead_id": "abc123" }
}
Per-recipient dynamic_vars override batch-level defaults if set.

​
Response

201 Created: 
{
  "campaign_id": "camp_a1b2c3d4",
  "agent_id": "agent_125207e452f8714a",
  "name": "Tuesday appointment reminders",
  "status": "running",
  "recipients_count": 3,
  "created_at": "2026-05-17T03:45:12Z"
}
When schedule_type is now, the campaign launches immediately and the response includes status: running. When scheduled, returns status: scheduled.

​
Behaviour

  • Calls are queued in BullMQ and processed respecting your concurrent call limit
  • Each recipient becomes one outbound call with its own call_id
  • Failed calls are logged with ended_reason: error but don’t stop the campaign
  • Voicemail detection runs per call; voicemails count as completed (just not successful)

​
Errors

CodeCause
agent_not_ownedAgent doesn’t belong to your account
from_number_not_ownedNumber not imported to your account
too_many_recipientsMore than 10,000 recipients
invalid_scheduleschedule_type: schedule without valid scheduled_at

​
Launching a scheduled campaign

If you created a campaign with schedule_type: schedule, you can launch it manually with Launch batch.