Skip to navigation

Create campaign

Creates a campaign in draft with its own empty list of contacts and returns it. Nothing is dialed yet: add the contacts with POST /campaigns/{campaign_id}/contacts, then start it with POST /campaigns/{campaign_id}/start. You must declare in contact_origin where the right to call these people comes from; it is recorded once with the key and the time and cannot be replaced. The calling window is the intersection of calling_hours (default 09:00-18:00) and the window of the organization, in Italian time. With a test key nothing is created: the response has status: simulated and an id that does not exist. Required scope: campaigns:write. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. NOT retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the outcome is uncertain and the key becomes “unknown” (the same key gives 409 idempotency_outcome_unknown); with no response at all, the same key returns the first outcome or that same 409. After idempotency_outcome_unknown, read the state of the resource and retry with a new key only if the operation did not happen. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:
Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

This endpoint expects an object.
namestringRequired1-200 characters
The name of the campaign, from 1 to 200 characters.
agent_idstringRequiredformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"

The agent that makes the calls, as returned by GET /agents. To start the campaign it needs an Italian phone line and must not be suspended.

max_concurrencyintegerOptional1-50

Calls at the same time for this campaign, from 1 to 50 (default 1). The plan limit of concurrent calls still applies.

calling_hoursobjectOptional

The campaign window (default 09:00-18:00). The effective window is its intersection with the organization window. An end that is not after start gives 400 invalid_request.

contact_originobjectOptional

Required (without it the answer is 422 contact_origin_required): your declaration of where the right to call comes from. VoxAI records it with the key and the time, so you can show it if asked; it does not verify it and does not check the Register of Oppositions for you. basis and purpose are required inside it.

Response

Created.
object"campaign"

Always campaign.

idstringformat: "uuid"

Id of the campaign: use it in GET /campaigns/{campaign_id} and in the other campaign operations.

namestring
The name given to the campaign.
statusenum

draft: created and not started yet. running: the campaign is calling its contacts. paused: stopped, it can be started again with POST /campaigns/{campaign_id}/start. completed: finished, it cannot be started or paused again. simulated: only with a test key, nothing was changed.

Allowed values:
paused_reasonenum

Set when the platform, and not you, paused the campaign; null otherwise. feature_not_available: the platform paused the campaign because the plan no longer includes outbound campaigns. agent_suspended: the agent was suspended; resuming it restarts the campaign.

Allowed values:
agentobject
The agent that makes the calls of the campaign.
max_concurrencyinteger
Calls the campaign can make at the same time. The plan limit of concurrent calls still applies.
calling_hoursobject
The daily window of the campaign. The effective window is its intersection with the organization window.
contact_originobject or null

The declaration made when the campaign was created; null for a campaign created in the app without one (it cannot be started through the API).

statsobject
Counts of the contacts of the campaign, updated as the calls proceed.
simulatedboolean

true with a test key: the operation was only checked and nothing was changed. After POST /campaigns with a test key the id does not exist.

created_atdatetime
When the campaign was created, ISO 8601 UTC.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error