Campanii

16 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	`/campaigns`	List the organization's campaigns newest first, filterable by status or assistant_id
POST	`/campaigns`	Create a campaign in draft from its target, origination, calling-window and retry settings
GET	`/campaigns/{campaignId}`	Retrieve one campaign with its settings, calling window and progress counters
PATCH	`/campaigns/{campaignId}`	Update a campaign's settings, refusing any edit once it has reached a terminal status
DELETE	`/campaigns/{campaignId}`	Delete a campaign and return an empty body
POST	`/campaigns/{campaignId}/cancel`	Cancel a campaign, cancelling every undialled contact and queued attempt, and return it
GET	`/campaigns/{campaignId}/contacts`	List a campaign's contacts with their state, attempt count, next attempt and last outcome
POST	`/campaigns/{campaignId}/contacts`	Add up to 5000 contacts inline and return the imported, duplicate, invalid and suppressed tally
POST	`/campaigns/{campaignId}/contacts/preview`	Parse an uploaded CSV's first 10 rows and return the header, sample, suggested mapping and row errors
POST	`/campaigns/{campaignId}/contacts/upload`	Import a CSV of contacts into the campaign and return the batch tally with per-row errors
POST	`/campaigns/{campaignId}/pause`	Pause a campaign, halting new dials and returning claimed-but-undialled contacts to the queue
GET	`/campaigns/{campaignId}/progress`	Return a campaign's live progress: status, totals, attempts, percent complete and counts by contact state
GET	`/campaigns/{campaignId}/results`	Stream every contact's outcome as a CSV download so a finished 500k-contact campaign never buffers
POST	`/campaigns/{campaignId}/resume`	Resume a paused campaign, clear its stop signal and re-dispatch the dialler
POST	`/campaigns/{campaignId}/start`	Start a campaign, refusing one with no contacts, no target, or a recording policy it cannot announce
POST	`/campaigns/preview-contacts`	Intended CSV preview, but the collection route is unreachable because the handler demands a campaign id

Endpoint-uri

List the organization's campaigns newest first, filterable by status or assistant_id

GET/campaigns

Necesită campaign.read.
Page size comes from limit (default 25, max 100), not per_page as on the billing and customer endpoints

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/campaigns" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped array

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    "string"
  ],
  "meta": {
    "total": 1,
    "per_page": 25,
    "current_page": 1
  }
}

Create a campaign in draft from its target, origination, calling-window and retry settings

POST/campaigns

Necesită campaign.write.
Always created with status draft. webhook_secret is accepted and stored encrypted; it is never read back.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	da	max 255 chars
`description`	string \| null	—
`target_type`	`assistant` · `squad` · `null` \| null	—
`assistant_id`	string \| null	—	max 26 chars. min 26 chars
`squad_id`	string \| null	—	max 26 chars. min 26 chars
`origination_type`	`phone_number` · `trunk` · `null` \| null	—
`phone_number_id`	string \| null	—	max 26 chars. min 26 chars
`sip_trunk_id`	string \| null	—	max 26 chars. min 26 chars
`caller_id_number`	string \| null	—	max 32 chars
`caller_id_name`	string \| null	—	max 64 chars
`timezone`	string \| null	—
`window_start_time`	string \| null	—
`window_end_time`	string \| null	—
`calling_days`	integer[] \| null	—
`starts_at`	string \| null	—	date-time
`ends_at`	string \| null	—	date-time
`max_concurrency`	integer \| null	—	min 1. max 1000
`dispatch_batch_size`	integer \| null	—	min 1. max 500
`retry_policy`	string[] \| null	—
`voicemail_behavior`	`hangup` · `leave_message` · `retry` · `null` \| null	—
`voicemail_message`	string \| null	—
`detect_voicemail`	boolean \| null	—
`screening_mode`	`none` · `amd` · `human_only` · `null` \| null	—
`answer_timeout_seconds`	integer \| null	—	min 5. max 120
`max_call_seconds`	integer \| null	—	min 10
`compliance`	string[] \| null	—
`suppression_list_ids`	string[] \| null	—
`variables`	string[] \| null	—
`metadata`	string[] \| null	—
`webhook_url`	string \| null	—	uri. max 1024 chars
`webhook_secret`	string \| null	—	max 255 chars
`webhook_events`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "target_type": "assistant",
       "assistant_id": "01JQ0000000000000000000000",
       "squad_id": "01JQ0000000000000000000000",
       "origination_type": "phone_number",
       "phone_number_id": "01JQ0000000000000000000000",
       "sip_trunk_id": "01JQ0000000000000000000000"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "target_type": "assistant",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "phone_number",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'target_type' => 'assistant',
    'assistant_id' => '01JQ0000000000000000000000',
    'squad_id' => '01JQ0000000000000000000000',
    'origination_type' => 'phone_number',
    'phone_number_id' => '01JQ0000000000000000000000',
    'sip_trunk_id' => '01JQ0000000000000000000000',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "target_type": "assistant",
      "assistant_id": "01JQ0000000000000000000000",
      "squad_id": "01JQ0000000000000000000000",
      "origination_type": "phone_number",
      "phone_number_id": "01JQ0000000000000000000000",
      "sip_trunk_id": "01JQ0000000000000000000000"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	Refreshed so the presenter reads the columns the database defaulted (counters, window times) rather than nulls.

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`422`	Field validation failed, or the target/origination pair is incomplete

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Retrieve one campaign with its settings, calling window and progress counters

GET/campaigns/{campaignId}

Necesită campaign.read.
The compliance settings are returned under the key controls, deliberately renamed

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope
`404`	No campaign with that id in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Update a campaign's settings, refusing any edit once it has reached a terminal status

PATCH/campaigns/{campaignId}

Necesită campaign.write.
No request validation at all: the whole body is passed to the service, which keeps a whitelist and silently drops every other key

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X PATCH "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.patch(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	The campaign is terminal, or the caller id is not valid E.164

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Delete a campaign and return an empty body

DELETE/campaigns/{campaignId}

Necesită campaign.write.
Acest răspuns nu este împachetat în data.
Deletes at any status, including a running campaign, with no state check

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`204`	No content

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization

Cancel a campaign, cancelling every undialled contact and queued attempt, and return it

POST/campaigns/{campaignId}/cancel

Necesită campaign.write.
Optional body: reason, farewell, and endLiveCalls — camelCase on a snake_case API — which also hangs up calls already in progress

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`reason`	string	—
`endLiveCalls`	boolean	—	default `false`

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/cancel" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "endLiveCalls": false
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/cancel`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "endLiveCalls": false
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/cancel');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'endLiveCalls' => false,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/cancel",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "endLiveCalls": False
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	The campaign cannot move from its current status to cancelled

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

List a campaign's contacts with their state, attempt count, next attempt and last outcome

GET/campaigns/{campaignId}/contacts

Necesită campaign.read.
Page size comes from limit (default 50, max 500)

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/contacts" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/contacts`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/contacts');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/contacts",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped array

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope
`404`	No campaign with that id in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "phone_number": "+40712345678",
      "name": "Support Line",
      "email": "ops@example.com",
      "external_id": "01JQ0000000000000000000000",
      "country": "string",
      "timezone": "string",
      "state": "string",
      "state_reason": "string",
      "state_detail": "string",
      "attempts": 1,
      "last_attempt_at": "2026-01-01T12:00:00+00:00",
      "next_attempt_at": "2026-01-01T12:00:00+00:00",
      "last_outcome": "string",
      "last_call_id": "01JQ0000000000000000000000",
      "variables": {}
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 25
  }
}

Add up to 5000 contacts inline and return the imported, duplicate, invalid and suppressed tally

POST/campaigns/{campaignId}/contacts

Necesită campaign.write.
Each contact's number is written as phone on the request but read back as phone_number on the response. Row errors are capped at 500 with errors_truncated set.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`contacts`	object[]	da	min 1 items. max 5000 items
`default_country`	string \| null	—	max 8 chars
`default_timezone`	string \| null	—
`skip_suppressed`	boolean \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/contacts" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "contacts": [
         {
           "phone": "+40712345678",
           "name": "Support Line",
           "email": "ops@example.com",
           "timezone": "string",
           "country": "string",
           "external_id": "01JQ0000000000000000000000",
           "variables": [],
           "consent": []
         }
       ],
       "skip_suppressed": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/contacts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contacts": [
      {
        "phone": "+40712345678",
        "name": "Support Line",
        "email": "ops@example.com",
        "timezone": "string",
        "country": "string",
        "external_id": "01JQ0000000000000000000000",
        "variables": [],
        "consent": []
      }
    ],
    "skip_suppressed": true
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/contacts');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'contacts' => [
        [
            'phone' => '+40712345678',
            'name' => 'Support Line',
            'email' => 'ops@example.com',
            'timezone' => 'string',
            'country' => 'string',
            'external_id' => '01JQ0000000000000000000000',
            'variables' => [],
            'consent' => [],
        ],
    ],
    'skip_suppressed' => true,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/contacts",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "contacts": [
        {
          "phone": "+40712345678",
          "name": "Support Line",
          "email": "ops@example.com",
          "timezone": "string",
          "country": "string",
          "external_id": "01JQ0000000000000000000000",
          "variables": [],
          "consent": []
        }
      ],
      "skip_suppressed": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	Validation failed on the contacts array or an individual contact

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "batch_id": "01JQ0000000000000000000000",
    "read": 1,
    "imported": 1,
    "duplicates": 1,
    "invalid": 1,
    "suppressed": 1,
    "errors": [
      "string"
    ],
    "errors_truncated": true
  }
}

Parse an uploaded CSV's first 10 rows and return the header, sample, suggested mapping and row errors

POST/campaigns/{campaignId}/contacts/preview

Necesită campaign.read.
column_map and default_country shape the returned errors but are not validated. An empty file returns empty header/rows rather than an error.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`file`	string	da	Maximum file size: 204800 kilobytes.. binary

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/contacts/preview" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "file": "string"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/contacts/preview`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "file": "string"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/contacts/preview');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'file' => 'string',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/contacts/preview",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "file": "string"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope
`404`	No campaign with that id in this organization
`422`	No file was uploaded or it exceeds 200 MB

Exemplu de răspuns, generat din schemă:

json

{
  "data": "string"
}

Import a CSV of contacts into the campaign and return the batch tally with per-row errors

POST/campaigns/{campaignId}/contacts/upload

Necesită campaign.write.
Multipart upload, max 200 MB. skip_suppressed defaults to true here even though it is optional; row errors are capped at 500.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`file`	string	da	Maximum file size: 204800 kilobytes.. binary
`column_map`	string[] \| null	—
`default_country`	string \| null	—	max 8 chars
`default_timezone`	string \| null	—
`skip_suppressed`	boolean \| null	—
`delimiter`	string \| null	—	max 1 chars. min 1 chars

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/contacts/upload" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "file": "string",
       "skip_suppressed": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/contacts/upload`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "file": "string",
    "skip_suppressed": true
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/contacts/upload');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'file' => 'string',
    'skip_suppressed' => true,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/contacts/upload",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "file": "string",
      "skip_suppressed": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	Bad upload, an empty CSV, or no column mappable to a phone number

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "batch_id": "01JQ0000000000000000000000",
    "read": 1,
    "imported": 1,
    "duplicates": 1,
    "invalid": 1,
    "suppressed": 1,
    "errors": [
      "string"
    ],
    "errors_truncated": true
  }
}

Pause a campaign, halting new dials and returning claimed-but-undialled contacts to the queue

POST/campaigns/{campaignId}/pause

Necesită campaign.write.
Calls already connected are left alone unless the body sets endLiveCalls — camelCase on a snake_case API — optionally with a farewell line

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`reason`	string	—
`endLiveCalls`	boolean	—	default `false`

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/pause" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "endLiveCalls": false
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/pause`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "endLiveCalls": false
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/pause');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'endLiveCalls' => false,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/pause",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "endLiveCalls": False
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	The campaign cannot move from its current status to paused

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Return a campaign's live progress: status, totals, attempts, percent complete and counts by contact state

GET/campaigns/{campaignId}/progress

Necesită campaign.read.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/progress" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/progress`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/progress');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/progress",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope
`404`	No campaign with that id in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "status": "string",
    "total": 1,
    "attempts": 1,
    "percent": 1,
    "states": {},
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00"
  }
}

Stream every contact's outcome as a CSV download so a finished 500k-contact campaign never buffers

GET/campaigns/{campaignId}/results

Necesită campaign.read.
Acest răspuns nu este împachetat în data.
Responds with text/csv as a file attachment, not JSON. Columns are fixed and include last_ended_reason, which the contacts list endpoint does not return.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/results" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/results`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/results');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/results",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Not JSON — `text/csv`

Erori

Status	Când apare
`403`	The API key does not carry the campaign.read scope
`404`	No campaign with that id in this organization

Resume a paused campaign, clear its stop signal and re-dispatch the dialler

POST/campaigns/{campaignId}/resume

Necesită campaign.write.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/resume" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/resume`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/resume');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/resume",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	The campaign cannot move from its current status to running

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Start a campaign, refusing one with no contacts, no target, or a recording policy it cannot announce

POST/campaigns/{campaignId}/start

Necesită campaign.write.
Returns status scheduled rather than running when starts_at is in the future; the scheduler picks it up later

Parametri de cale

Nume	Tip	Obligatoriu	Note
`campaignId`	string	da

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/01JQ0000000000000000000000/start" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/01JQ0000000000000000000000/start`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/01JQ0000000000000000000000/start');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/01JQ0000000000000000000000/start",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The API key does not carry the campaign.write scope
`404`	No campaign with that id in this organization
`422`	No contacts, no assistant or squad, unannounceable consent, or illegal transition

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "target_type": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "squad_id": "01JQ0000000000000000000000",
    "origination_type": "string",
    "phone_number_id": "01JQ0000000000000000000000",
    "sip_trunk_id": "01JQ0000000000000000000000",
    "caller_id_number": "+40712345678",
    "timezone": "string",
    "window": {
      "start": "string",
      "end": "string",
      "days": {}
    },
    "starts_at": "2026-01-01T12:00:00+00:00",
    "ends_at": "2026-01-01T12:00:00+00:00",
    "max_concurrency": 1,
    "retry_policy": {},
    "voicemail_behavior": "ops@example.com",
    "detect_voicemail": true,
    "screening_mode": "string",
    "controls": {},
    "suppression_list_ids": {},
    "variables": {},
    "progress": {
      "total": 1,
      "pending": 1,
      "completed": 1,
      "failed": 1,
      "skipped": 1,
      "attempts": 1,
      "percent": 1
    },
    "started_at": "2026-01-01T12:00:00+00:00",
    "completed_at": "2026-01-01T12:00:00+00:00",
    "created_at": "2026-01-01T12:00:00+00:00"
  }
}

Intended CSV preview, but the collection route is unreachable because the handler demands a campaign id

POST/campaigns/preview-contacts

Necesită campaign.read.
Broken route: CampaignController::previewContacts requires a $campaignId, and this path supplies none, so every call raises ArgumentCountError (500). Use /campaigns/{campaignId}/contacts/preview.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`file`	string	da	Maximum file size: 204800 kilobytes.. binary
`default_country`	string	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/campaigns/preview-contacts" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "file": "string"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/campaigns/preview-contacts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "file": "string"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/campaigns/preview-contacts');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'file' => 'string',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/campaigns/preview-contacts",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "file": "string"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`422`	Validation error

Exemplu de răspuns, generat din schemă:

json

{
  "data": "string"
}

Campanii ​

Endpoint-uri ​

List the organization's campaigns newest first, filterable by status or assistant_id ​

Create a campaign in draft from its target, origination, calling-window and retry settings ​

Retrieve one campaign with its settings, calling window and progress counters ​

Update a campaign's settings, refusing any edit once it has reached a terminal status ​

Delete a campaign and return an empty body ​

Cancel a campaign, cancelling every undialled contact and queued attempt, and return it ​

List a campaign's contacts with their state, attempt count, next attempt and last outcome ​

Add up to 5000 contacts inline and return the imported, duplicate, invalid and suppressed tally ​

Parse an uploaded CSV's first 10 rows and return the header, sample, suggested mapping and row errors ​

Import a CSV of contacts into the campaign and return the batch tally with per-row errors ​

Pause a campaign, halting new dials and returning claimed-but-undialled contacts to the queue ​

Return a campaign's live progress: status, totals, attempts, percent complete and counts by contact state ​

Stream every contact's outcome as a CSV download so a finished 500k-contact campaign never buffers ​

Resume a paused campaign, clear its stop signal and re-dispatch the dialler ​

Start a campaign, refusing one with no contacts, no target, or a recording policy it cannot announce ​

Intended CSV preview, but the collection route is unreachable because the handler demands a campaign id ​

Campanii

Endpoint-uri

List the organization's campaigns newest first, filterable by status or assistant_id

Create a campaign in draft from its target, origination, calling-window and retry settings

Retrieve one campaign with its settings, calling window and progress counters

Update a campaign's settings, refusing any edit once it has reached a terminal status

Delete a campaign and return an empty body

Cancel a campaign, cancelling every undialled contact and queued attempt, and return it

List a campaign's contacts with their state, attempt count, next attempt and last outcome

Add up to 5000 contacts inline and return the imported, duplicate, invalid and suppressed tally

Parse an uploaded CSV's first 10 rows and return the header, sample, suggested mapping and row errors

Import a CSV of contacts into the campaign and return the batch tally with per-row errors

Pause a campaign, halting new dials and returning claimed-but-undialled contacts to the queue

Return a campaign's live progress: status, totals, attempts, percent complete and counts by contact state

Stream every contact's outcome as a CSV download so a finished 500k-contact campaign never buffers

Resume a paused campaign, clear its stop signal and re-dispatch the dialler

Start a campaign, refusing one with no contacts, no target, or a recording policy it cannot announce

Intended CSV preview, but the collection route is unreachable because the handler demands a campaign id