API Reference
Broadcasts

Append contacts (batch, row-level results)

POST
/v1/broadcasts/{id}/contacts

Batch append with per-row results — one bad row never fails the batch. Phones must be strict E.164 (leading '+', no spaces); rows missing the template's required_variables are rejected with missing_variables + the missing names. Supports Idempotency-Key: replaying the same key + body returns the original result without re-inserting; same key + different body is 409.

Authorization

bearerAuth
AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Path Parameters

id*string
Formatuuid

Header Parameters

Idempotency-Key?string

Client-supplied idempotency key for safe batch retries.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/broadcasts/497f6eca-6276-4993-bfeb-53cbbbba6f08/contacts" \  -H "Content-Type: application/json" \  -d '{    "contacts": [      {        "phone": "+254712345678",        "variables": {          "name": "Alice",          "date": "Tuesday 10am"        }      },      {        "phone": "+254700000001",        "variables": {          "name": "Ben",          "date": "Wednesday 2pm"        }      }    ]  }'
{  "accepted": [    "0eaa4f9a-b3ff-4843-a0ba-e12d4647d9f2"  ],  "rejected": [    {      "index": 0,      "phone": "string",      "code": "invalid_phone",      "missing": [        "string"      ]    }  ]}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string"  }}

List a broadcast's contacts GET

Cursor-paginated with filters. `status` accepts roster vocabulary (scheduled | active | completed | missed | discarded) or a raw contact status; `q` is a phone substring; `from`/`to` are inclusive `created_at` bounds (RFC3339 or YYYY-MM-DD).

Bulk contact action (cancel | reschedule | dial_now) POST

Applies one action to a set of contact ids. `next_attempt_at` (RFC3339) is honoured only by `reschedule`. `dial_now` is seat-gated: ids that could not be queued for lack of a free seat come back in `no_seat`.