API reference

Create a campaign

POST /v1/campaigns

A list of people for an outbound agent to call, at the pace and in the hours you set. It is a draft until it starts: send start: true to start dialling at once, start_at to start at a moment of your choosing, or neither and start it later. Up to 1,000 contacts in one request; add more with POST /v1/campaigns/{id}/contacts. Needs campaigns:write, a live key and an Idempotency-Key.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	Your own id for this request, up to 120 characters. Required.

Body

Sent as JSON. A field this operation does not take is refused, so a typo fails loudly.

Field	Type	Required	Description
`agent_id`	string (uuid)	Yes	The outbound agent that makes the calls.
`callbacks`	CampaignCallbacks or null	No
`calling_hours`	CampaignCallingHours or null	No	When calls may start, read in each contact's own `timezone` — or your organization's, for a contact without one.
`contacts`	array of CampaignContactCreate	No	The people to call, up to 1,000 in one request.
`name`	string	Yes	What the campaign is called in the console.
`pacing`	CampaignPacing or null	No
`phone_number_id`	string (uuid) or null	No	One of the agent's numbers to call from. The agent's own unless you say.
`start`	boolean	No	Start dialling now.
`start_at`	string (date-time) or null	No	Start dialling at this moment instead, with its offset — `2026-10-12T09:00:00+03:00`. A time without one is UTC.
`voicemail`	CampaignVoicemail or null	No

Answer

201 with Campaign.

Errors

Every error is a problem document with a stable code.

Status	When
`400`	No `Idempotency-Key`.
`401`	The key is missing, mistyped, unknown, revoked or expired.
`403`	A test key: a campaign rings real people.
`404`	This key reaches no such agent, or no such number to call from.
`409`	The agent answers calls rather than placing them, it cannot place a call yet — not published, no number to call from — or its project is frozen.
`422`	A contact does not fit — `errors` names each by its place in `contacts` — the start time has passed, or the `Idempotency-Key` was used for another request.
`429`	Too many requests for this key or its organization; see `Retry-After`.
`500`	Something went wrong on our side. Quote the `request_id` to support.
`501`	This deployment does not place phone calls.

Examples

Create a campaign

#!/bin/sh
# Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  -H "Idempotency-Key: reminders-october" \
  --json '{
  "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c",
  "name": "Visit reminders, October",
  "calling_hours": {
    "start_hour": 9,
    "end_hour": 18,
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri"
    ]
  },
  "contacts": [
    {
      "to_number": "+12025550123",
      "variables": {
        "first_name": "Sara"
      },
      "metadata": {
        "crm_lead_id": "L-20931"
      },
      "external_id": "lead-20931"
    },
    {
      "to_number": "+12025550124",
      "variables": {
        "first_name": "Omar"
      },
      "timezone": "America/Chicago",
      "external_id": "lead-20932"
    }
  ]
}'

Try it

Sends this request to the API from your browser, with a test key. Nothing it does rings a phone.