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
Headers
API version for this request; defaults to the version the key is pinned to.
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
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.
Calls at the same time for this campaign, from 1 to 50 (default 1). The plan limit of concurrent calls still applies.
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.
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
Always campaign.
Id of the campaign: use it in GET /campaigns/{campaign_id} and in the other campaign operations.
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.
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.
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).
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.