Skip to navigation
API referenceCampaigns

Create a campaign from CSV or XLSX

Create a campaign from CSV or XLSX.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Headers

Idempotency-KeystringRequired1-255 characters

Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.

Request

This endpoint expects a multipart form containing a file.
recipientsfileRequired
agent_idstringRequired
namestringRequired1-200 characters
from_phone_number_idstring or nullOptional
max_attempts_per_recipientintegerOptional1-10Defaults to 1
max_concurrent_callsintegerOptional1-1000Defaults to 1
ringing_timeout_secondsinteger or nullOptional5-120
retry_backoff_msintegerOptional>=0Defaults to 3600000
dialing_time_zonestringOptional<=64 charactersDefaults to UTC
window_start_atdatetime or nullOptional
window_end_atdatetime or nullOptional
daily_opens_minuteinteger or nullOptional0-1440
daily_closes_minuteinteger or nullOptional0-1440
recipient_editsstring or nullOptional<=1048576 characters

Response headers

X-Request-IdstringOptional
Safe server request correlation ID.
RateLimit-LimitintegerOptional
Requests allowed in the current window for the tightest applicable limit.
RateLimit-RemainingintegerOptional
Requests left in the current window.
RateLimit-ResetintegerOptional
Seconds until the current window resets.
ETagstringOptional

Strong campaign revision. Use it as If-Match for state-dependent commands.

Response

Create a campaign from CSV or XLSX.
idstring<=128 characters
revisionstring
agent_idstring<=128 characters
namestring<=200 characters
statestring
recipient_countinteger>=0
max_attempts_per_recipientinteger1-10
retry_backoff_msinteger>=0
max_concurrent_callsinteger1-1000
dialing_time_zonestring<=64 characters
created_atdatetime
updated_atdatetime
ringing_timeout_secondsinteger or nullOptional5-120
from_phone_number_idstring or nullOptional<=128 characters
window_start_atdatetime or nullOptional
window_end_atdatetime or nullOptional
daily_opens_minuteinteger or nullOptional0-1440
daily_closes_minuteinteger or nullOptional0-1440
quota_checked_atdatetime or nullOptional
failure_reasonstring or nullOptional
started_atdatetime or nullOptional
ended_atdatetime or nullOptional
uploaded_recipient_countinteger or nullOptional>=0
duplicates_removedinteger or nullOptional>=0
import_reportmap from strings to any or nullOptional

Errors

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