Agoralia docs
Run

Campaigns

Create a campaign, add leads, then launch through the deterministic pre-flight gate. Covers settings (country_code, purpose, recording_enabled) and the readiness check.

Campaigns

A campaign calls many contacts with one agent. The flow is create → add leads → launch, and the launch always runs through a deterministic pre-flight gate — the same gate on REST, MCP, and the dashboard. No ungated launches.

1. Create

A campaign needs only a name to start as a draft. The agent and number can come later — the pre-flight will require and guide you toward them.

REST
curl -X POST https://api.agoralia.app/api/v1/campaigns \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 quote follow-ups",
    "agent_id": "AGENT_ID",
    "settings": {
      "country_code": "IT",
      "purpose": "quote_request",
      "recording_enabled": true
    }
  }'
MCP
create_campaign(name="Q3 quote follow-ups", agent_id="AGENT_ID",
  settings={ "country_code": "IT", "purpose": "quote_request" })

Settings

settings is a free-form object; the recognised keys are:

KeyWhat it is
country_codeDestination country (2-letter). Drives compliance + recording advisory.
timezoneTimezone for scheduling/quiet hours.
concurrent_callsHow many calls to run in parallel.
purposeThe call type / legal purpose. quote_request, survey, appointment are buying-inquiry-like (lighter rules); cold_calling is telemarketing (stricter). Default quote_request.
recording_enabledPer-campaign recording toggle. false records no audio (transcript + structured data stay on); you can't force it on where a country forbids it.

When a recording preference or country is set, the create/update response includes a recording_advisory. See Compliance.

2. Add leads

Add or upsert contacts in batch (1–10,000 per request). Phone numbers must be E.164.

REST
curl -X POST https://api.agoralia.app/api/v1/campaigns/CAMPAIGN_ID/leads \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "phone_number": "+393408994869", "name": "Mario Rossi", "external_id": "crm-101" },
      { "phone_number": "+390612345678", "name": "Lucia Bianchi", "external_id": "crm-102" }
    ]
  }'
MCP
add_campaign_lead(campaign_id="CAMPAIGN_ID", phone_number="+393408994869", name="Mario Rossi")

The response reports imported, total, and per-row errors. Upserts are keyed on external_id, so re-sending the same contact updates rather than duplicates.

3. Launch (the pre-flight gate)

Starting a campaign (POST /campaigns/{id}/start, MCP launch_campaign) runs a deterministic readiness check first. It returns all missing requirements at once, each with the action to take.

What the pre-flight checks

  1. Attestation signed for the campaign.
  2. Agent assigned and has a non-empty system_prompt.
  3. At least one pending contact.
  4. Compliance OK for the destination country/countries.
  5. Phone number assigned, or auto-assignable from the pool.
  6. GDPR launch consent (when the caller is known).
  7. Budget — an empty balance (no included minutes and no credit) blocks launch; a low-but-nonzero balance is advisory.
  8. DNC + integration health — advisory, not blocking.
REST
curl -X POST https://api.agoralia.app/api/v1/campaigns/CAMPAIGN_ID/start \
  -H "X-API-Key: ag_..."

If the campaign is ready, it moves to running:

Ready
{ "status": "running", "pending_leads": 2 }

If not, you get 422 campaign_not_ready with a missing list and suggestions — so a calling agent knows exactly what to fix, then retries.

Not ready
{
  "error": "campaign_not_ready",
  "message": "Campaign is not ready to launch. Resolve the missing requirements, then retry.",
  "missing": [
    { "requirement": "contacts", "message": "No pending contacts in this campaign.",
      "action": "Import contacts (POST /campaigns/{id}/leads)." }
  ],
  "suggestions": []
}

Pool number auto-assign

Leave phone_number_id unset and a matching pool number is assigned at launch based on your lead countries. See Phone numbers.

Manage a running campaign

  • Pause: POST /campaigns/{id}/pause (MCP pause_campaign).
  • Results: GET /campaigns/{id}/results — calls with transcript, summary, analysis.

Next

Single call

Place one outbound call with POST /api/v1/calls — body fields, the recording_enabled toggle, and the recording advisory in the response.

Journeys & pipelines

Two different multi-step concepts — journeys sequence touches (call/wait/sms) per contact over time; pipelines run multiple agents on a single call.

On this page

Campaigns1. CreateSettings2. Add leads3. Launch (the pre-flight gate)Manage a running campaignNext