Campaigns - Synthesys Docs

A campaign has one agent call a list of contacts from one phone number. The API is read-only for campaigns, so you create and launch them in the dashboard. Use these endpoints to report on status and call counts.

Endpoint	Request
List campaigns	GET`/v1/campaigns`
Get a campaign	GET`/v1/campaigns/{id}`

The campaign object

Most campaign fields use snake_case. phoneNumber and assistantName are in camelCase.

Attributes

idstringrequired

The campaign's UUID.

namestringrequired

The campaign's name.

statusstringrequired

Scheduled, Live, Completed, Cancelled, Failed or Archived. Values are capitalized.

assistant_idstringrequired

The UUID of the agent that makes the calls.

assistantNamestring

That agent's display name. Left out if it can't be found.

phone_number_idstringrequired

The UUID of the phone number the calls come from.

phoneNumberstring

That phone number's value. Left out if the number can't be found.

audience_idstring | null

The UUID of the audience being called, if the campaign uses one.

contact_countintegerrequired

Number of contacts in the campaign.

total_callsintegerrequired

Total calls in the campaign.

ended_callsintegerrequired

Calls that have ended.

picked_up_callsintegerrequired

Calls that were answered.

voicemail_callsintegerrequired

Calls that reached voicemail.

failed_initiationsinteger

Calls that couldn't be started.

pickup_ratenumberrequired

Stored pickup rate as a decimal, so 0.67 means 67%. It is 0 when no value is stored.

click_ratenumberrequired

Stored click rate as a decimal. It is 0 when no value is stored.

order_ratenumberrequired

Stored order rate as a decimal. It is 0 when no value is stored.

schedule_typestringrequired

now or later.

scheduled_atstring | null

The scheduled start time, for a later campaign.

timezonestring | null

The timezone for the schedule.

launched_atstring | null

When the campaign started.

completed_atstring | null

When the campaign finished.

created_atstringrequired

When the campaign was created.

updated_atstringrequired

When the campaign last changed.

List campaigns

GET/v1/campaignsread key

Returns your campaigns, newest first. Archived campaigns are only included when you filter for them.

Query parameters

limitintegerdefault 50

Maximum results, from 1 to 100.

offsetintegerdefault 0

Number of results to skip, up to 1,000,000.

statusstring

Only return campaigns with this status, in any letter case. See the values below. Any other value returns 400.

Filter value	Matches campaigns with `status`
`scheduled`	`Scheduled`
`live` or `running`	`Live`
`completed`	`Completed`
`cancelled` or `canceled`	`Cancelled`
`failed`	`Failed`
`archived`	`Archived`
`draft` or `paused`	None. These are accepted, but campaigns are never in these states, so the list is empty.

Request

curl "https://backend.synthesys.app/api/v1/campaigns?limit=10" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "c7e2a9d4-1f3b-4a6c-9e80-2b3c4d5e6f70",
      "name": "October renewals",
      "status": "Live",
      "assistant_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "phone_number_id": "d4c3b2a1-6f5e-4b7a-9d8c-5c4b3a2f1e0d",
      "phoneNumber": "+12025550123",
      "audience_id": "8a1d4f2c-3b6e-4c7a-8d90-1e2f3a4b5c6d",
      "contact_count": 200,
      "total_calls": 200,
      "ended_calls": 80,
      "picked_up_calls": 52,
      "voicemail_calls": 18,
      "pickup_rate": 0,
      "click_rate": 0,
      "order_rate": 0,
      "schedule_type": "now",
      "scheduled_at": null,
      "timezone": null,
      "launched_at": "2026-10-01T09:30:00",
      "completed_at": null,
      "created_at": "2026-10-01T09:25:00",
      "updated_at": "2026-10-01T11:00:00"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0 }
}

Get a campaign

GET/v1/campaigns/{id}read key

Returns one campaign. This route can also return an archived campaign, which the list leaves out.

Path parameters

idstringrequired

The campaign's UUID.

Returns 404 if the campaign doesn't exist or belongs to another account. An id that isn't a valid UUID returns 400.

Request

curl https://backend.synthesys.app/api/v1/campaigns/c7e2a9d4-1f3b-4a6c-9e80-2b3c4d5e6f70 \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "c7e2a9d4-1f3b-4a6c-9e80-2b3c4d5e6f70",
    "name": "October renewals",
    "status": "Completed",
    "assistant_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "phone_number_id": "d4c3b2a1-6f5e-4b7a-9d8c-5c4b3a2f1e0d",
    "phoneNumber": "+12025550123",
    "audience_id": "8a1d4f2c-3b6e-4c7a-8d90-1e2f3a4b5c6d",
    "contact_count": 200,
    "total_calls": 200,
    "ended_calls": 200,
    "picked_up_calls": 130,
    "voicemail_calls": 44,
    "pickup_rate": 0,
    "click_rate": 0,
    "order_rate": 0,
    "schedule_type": "now",
    "scheduled_at": null,
    "timezone": null,
    "launched_at": "2026-10-01T09:30:00",
    "completed_at": "2026-10-01T15:10:00",
    "created_at": "2026-10-01T09:25:00",
    "updated_at": "2026-10-01T15:10:00"
  }
}

Not found (404)

{
  "success": false,
  "error": "Campaign not found",
  "code": "NOT_FOUND",
  "requestId": "e3a1c5d7-2b4f-4a6c-9d8e-1f2a3b4c5d6e",
  "timestamp": "2026-10-31T14:02:11.482Z"
}