Campaigns API - Anyreach

The /campaign surface manages outbound calling campaigns: the campaign itself, the contacts you dial, the schedule and agent configurations that drive them, and the org-wide concurrency limit. Every route lives under the /campaign prefix on https://api.anyreach.ai. For the product walkthrough, see Campaigns. For credentials and the X-Anyreach-Org header, see Authentication.

Endpoints

Campaigns

Method	Path	Scope	Description
`POST`	`/campaign/campaigns`	`campaigns:manage`	Create a campaign. Starts `active`.
`GET`	`/campaign/campaigns`	`campaigns:read`	List campaigns. Cursor pagination.
`GET`	`/campaign/campaigns/{id}`	`campaigns:read`	Get one campaign.
`PATCH`	`/campaign/campaigns/{id}`	`campaigns:manage`	Update a campaign.
`POST`	`/campaign/campaigns/{id}/start`	`campaigns:manage`	Start or resume the campaign.
`POST`	`/campaign/campaigns/{id}/pause`	`campaigns:manage`	Pause a running campaign.
`POST`	`/campaign/campaigns/{id}/close`	`campaigns:manage`	Close the campaign permanently.

Contacts

Method	Path	Scope	Description
`POST`	`/campaign/campaigns/{id}/contacts`	`campaigns:manage`	Upsert up to 1000 contacts.
`GET`	`/campaign/campaigns/{id}/contacts`	`campaigns:read`	List contacts with their attempts. Limit/offset pagination.
`GET`	`/campaign/campaigns/{id}/contacts/{contact_id}`	`campaigns:read`	Get one contact with its attempts. Accepts an `external_id`.
`DELETE`	`/campaign/campaigns/{id}/contacts/{contact_id}`	`campaigns:manage`	Delete a contact.

Stats

Method	Path	Scope	Description
`GET`	`/campaign/campaigns/{id}/stats`	`campaigns:read`	Contact counts, attempt counts, and active-call count.

Configurations

Method	Path	Scope	Description
`POST`	`/campaign/configurations`	`campaigns:manage`	Create a configuration.
`GET`	`/campaign/configurations`	`campaigns:read`	List configurations.
`GET`	`/campaign/configurations/{config_id}`	`campaigns:read`	Get one configuration.
`PATCH`	`/campaign/configurations/{config_id}`	`campaigns:manage`	Update a configuration.
`DELETE`	`/campaign/configurations/{config_id}`	`campaigns:manage`	Delete a configuration. Fails if a campaign references it.
`GET`	`/campaign/timezones`	—	List valid IANA timezone identifiers.

Concurrency settings

Method	Path	Scope	Description
`GET`	`/campaign/concurrency-settings`	`concurrency:read`	Get the org concurrency limit and current active count.
`PUT`	`/campaign/concurrency-settings`	`concurrency:manage`	Set the org concurrency limit.

Scopes

Read endpoints accept either campaigns:read or campaigns:manage. Mutating endpoints — create, update, start, pause, close, upsert, delete — require campaigns:manage. The concurrency endpoints have their own scopes: GET /campaign/concurrency-settings accepts campaigns:read, campaigns:manage, concurrency:read, or concurrency:manage; PUT accepts campaigns:manage or concurrency:manage. A 403 means the credential is valid but lacks the required scope. See Authentication for how scopes are granted.

Conventions

Resolving by external_id

Wherever a path takes a campaign {id} or a {contact_id}, you can pass either the resource’s UUID or the external_id you assigned on create. This applies to campaign, contact, start/pause/close, and stats routes — set external_id once and address the resource by your own key thereafter.

Pass default as the campaign {id} on the contacts routes to manage ad-hoc contacts that belong to no campaign. Contacts added under default must already carry valid E.164 phone numbers, since there is no configuration to supply a default country code.

Pagination

The two list endpoints paginate differently.

Endpoint	Style	Parameters
`GET /campaign/campaigns`	Cursor	`cursor`, `limit`
`GET /campaign/campaigns/{id}/contacts`	Offset	`limit`, `offset`

GET /campaign/campaigns also accepts name (substring filter) and status (repeatable) query parameters. GET .../contacts accepts a status filter. The contacts response echoes total, limit, and offset alongside the contacts array.

Limits

Limit	Value
`limit` on either list endpoint	Max `200`, default `50`
Contacts per `POST .../contacts` request	Max `1000`
Contacts inlined on `POST` / `PATCH /campaign/campaigns`	Max `5000`
Default concurrency limit (when unset)	`10`

Stats response

GET /campaign/campaigns/{id}/stats returns contact counts by status, attempt totals, and live activity:

{
  "campaign_id": "…",
  "status": "active",
  "contacts": {
    "total": 0,
    "pending": 0,
    "in_progress": 0,
    "completed": 0,
    "exhausted": 0
  },
  "attempts": {
    "total": 0,
    "average_per_contact": 0.0
  },
  "active_calls": 0,
  "concurrency_limit": 10
}

The stats route resolves the campaign by UUID only.

Upsert response

POST /campaign/campaigns/{id}/contacts upserts: contacts are updated when their id or external_id matches an existing row, and inserted otherwise. It returns counts plus the resolved IDs:

{
  "inserted": 0,
  "updated": 0,
  "failed": [],
  "warnings": [],
  "contact_ids": []
}

Phone numbers are normalized to E.164 using the campaign configuration’s default_country_code (falling back to +1). Numbers that can’t be parsed return 422. You cannot add contacts to a campaign whose status is closed (400).

Example: bulk-add contacts

Upsert two contacts into a campaign addressed by its external_id. With an org API key (ak_) the organization is implicit; with a personal access token (pat_) add the X-Anyreach-Org header.

curl -X POST https://api.anyreach.ai/campaign/campaigns/spring-outreach/contacts \
  -H "Authorization: Bearer $ANYREACH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "external_id": "lead-1001",
        "phone_numbers": ["+14155550123"],
        "data": { "first_name": "Ada" }
      },
      {
        "external_id": "lead-1002",
        "phone_numbers": ["+14155550199"],
        "data": { "first_name": "Grace" }
      }
    ]
  }'

Campaigns

The product walkthrough for building and running outbound campaigns.

Authentication

Bearer credentials, the X-Anyreach-Org header, and scopes.

​Endpoints

​Campaigns

​Contacts

​Stats

​Configurations

​Concurrency settings

​Scopes

​Conventions

​Resolving by external_id

​Pagination

​Limits

​Stats response

​Upsert response

​Example: bulk-add contacts

​Related

Campaigns

Authentication

Endpoints

Campaigns

Contacts

Stats

Configurations

Concurrency settings

Scopes

Conventions

Resolving by external_id

Pagination

Limits

Stats response

Upsert response

Example: bulk-add contacts

Related