API Reference
Dialer

List a campaign's contacts

GET
/v1/dialer/campaigns/{id}/contacts

Newest first, cursor-paginated.

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

Query Parameters

cursor?string

Opaque next_cursor from the previous page.

limit?integer
Range1 <= value <= 200
Default50
status?string

Value in

  • "queued"
  • "calling"
  • "connected"
  • "waiting_retry"
  • "completed"
  • "exhausted"
  • "suppressed"
  • "canceled"
  • "callback"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/dialer/campaigns/497f6eca-6276-4993-bfeb-53cbbbba6f08/contacts"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "phone": "string",      "external_ref": "string",      "fields": {},      "callback_url": "string",      "timezone": "string",      "status": "queued",      "attempts": 0,      "next_attempt_at": "2019-08-24T14:15:22Z",      "callback_at": "2019-08-24T14:15:22Z",      "priority": 0,      "last_result": "string",      "created_at": "2019-08-24T14:15:22Z",      "best_hour": 0    }  ],  "next_cursor": "string"}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

Pre-flight cost estimate GET

Worst-case spend: dialable contacts x `retry.max_attempts` x average call cost, plus an AMD analysis per attempt when AMD is on, against the budget. `priced` is false when no rates were available; the amounts are then 0.

Add contacts (JSON or CSV) POST

Send `application/json` (`{"contacts": [...]}`) or `text/csv`. A CSV needs a header row with a phone column (`phone`, `phone_number`, `msisdn` or `number`); `external_ref`, `callback_url`, `timezone` and `priority` are recognised and every other column becomes a custom field passed to your callback. At most 10,000 rows and 16 MB per request. Every row ends up accepted, suppressed (stored, never dialed) or rejected with a reason; one bad row never fails the request. `rejected[].index` is the 0-based row number in your upload (CSV: data rows, header excluded). Numbers are normalised to E.164; duplicates inside the request or already in the campaign are rejected as `duplicate`. Supports `Idempotency-Key`: the same key and body replays the original result without inserting again (`X-Idempotency-Replayed: true`); the same key with a different body is 409.