Campaign fields

Retry configuration

retry_config is normalized on save and echoed back normalized.

Field	Type	Default	Rules
`attempts`	integer	`1`	Total dial attempts per contact, 1–30. `0` reads as `1`; values above 30 are clamped to 30; negative → `422 campaign_spec_invalid`. With the default, no number is redialed.
`interval_s`	integer	`900`	Pause between attempts in seconds. Must be `> 0` when `attempts > 1`, else `422 campaign_spec_invalid`.
`retry_mode`	`"regular"` \| `"custom"`	`regular`	`custom` uses the per-retry ladder `intervals_s`.
`intervals_s`	array of integers	—	Seconds before each retry in `custom` mode (fitted to `attempts − 1`).
`rules`	array	—	`expert` only. Each rule: `{"id"?, "if", "then", "params"?}`. `if` is a `status_reason` value (Call outcomes) or `short_call` / `goal_not_achieved`; `then` is `wait_for_pass_end` or `stop_calling` (`retry_in` is accepted but not executed — warning `rule_action_unsupported`); `params`: `max_matches` (1–30, default 1) for any condition, `max_duration_s` (≥ 10, required) for `short_call`. Ids are assigned by the server (`r-xxxxxxxx`); ids you send that are not echoes of existing ones are replaced. A bare array of rules is accepted as the legacy form.

The numbers: `planned_calls`

Each object is one row of a contact list, and its keys are column names. Every column the file upload understands is understood here: market-package columns (zip, state, city), contract-group columns (contract_id, role), timezone, name, and any variable your agent’s flow reads. A nested variables object is sugar and is flattened into the same columns (a top-level key wins over the same key inside variables). Values are converted to text (booleans → true/false, objects → compact JSON), so leading zeros survive.

{
  "planned_calls": [
    {"phone": "+77001234567", "name": "Aigerim", "variables": {"debt": "15000"}},
    {"phone": "+77007654321", "name": "Daniyar", "zip": "73301"}
  ]
}

A phone column is mandatory in every row; a value with fewer than ten digits is rejected as phone_unreadable — the row is rejected, not the request. Row-level issue codes are in The upload report.

Dialing binding

You have no internal trunk or subgroup identifiers, so the platform resolves them: omit trunk_id, route_id and from_number together, and the subgroups bound to your agent are looked up across every trunk visible to your organization.

Outcome	Result
exactly one subgroup	it is used, together with the first number of its pool
none	`422 dialing_route_unresolved`
more than one	`422 dialing_route_ambiguous`, with the candidates named in the message as `trunk_id/route_id` pairs

Ambiguity is never resolved by picking the first candidate: dialing from another trunk would spend another caller ID and another quota, and you would find out from the invoice. Read the candidates with:

GET /v1/dialing-routes?agent_id=collections-agent

The response is {"dialing_routes": [{"trunk_id", "trunk_name", "route_id", "route_name", "agents", "caller_numbers"}]} — no trunk connection settings or credentials. An empty agent_id lists every route visible to your organization.

trunk_id is the anchor. Name it and the rest follows the platform’s existing rules: the subgroup is resolved from the trunk and the agent at launch, and the caller ID is chosen by the subgroup itself, following its caller-ID policy. Naming route_id or from_number without trunk_id is refused with 422 dialing_binding_incomplete: the platform will not guess which trunk you meant. A trunk named explicitly but unusable (agent not in its subgroup, empty pool) is not refused on creation — it becomes the binding_invalid blocker.

Attestation

Dialing requires a consent attestation: {"attestation": {"confirmed": true}}. The record is stored immutably against the version of the data it covers and the wording of the campaign’s consent tier, and your API key is the signer — issuing the key is the human act the signature is attributed to (the platform records who issued the key and when). A confirmation of one upload does not carry over to a new one; on POST …/launch the attestation.import_id field is therefore mandatory (→ 422 attestation_import_id_required), and an import_id that is not the campaign’s current import yields the attestation_stale blocker. Batches of added calls are signed separately.

Do-not-call matches: `dnc_screen`

dnc_screen is the authoritative result. It screens every readable source row before market rejection and deduplication, so matched_rows may be larger than suppressed_contacts.

Field	Type	Meaning
`status`	string	`clean` \| `matches` \| `screen_unavailable` (the import has no recorded source-row screening).
`checked_rows`	integer \| null	Readable rows screened.
`unscreened_rows`	integer \| null	Rows with an unreadable phone, not screened.
`matched_rows`	integer \| null	Rows whose number is on the registry (before deduplication).
`suppressed_contacts`	integer \| null	Distinct numbers matched.
`fingerprint`	string	Deterministic hash of the exact match composition; a `skip` decision is bound to it.
`items`	array	Up to 200 matches: `{"row_number", "phone", "phone_key", "contact_name", "dnc_entry_id", "source", "reason", "recorded_at"}`.
`has_more`, `hidden_rows`		Whether `items` is truncated and by how much.
`all_dialable_suppressed`	boolean	Every pending contact is matched.
`as_of_launch`	boolean	`false` — live against the registry; `true` — frozen snapshot taken at launch.
`screened_at`, `audit_id`	number \| null, integer \| null	When the frozen snapshot was taken and its audit record.
`decision`, `import_id`	string	Frozen snapshot only: `clean` \| `skip`, and the import it covers.

import.dnc_matches is a compatibility projection of items (the same objects plus a row alias of row_number); import.dnc_matched equals matched_rows (0 when the screen is unavailable). Matches block launch with dnc_matches. Sending dnc: "skip" records the same audited decision a human makes in the dashboard. It applies to this exact import_id and fingerprint: a new match or a replacement registry entry makes the decision stale, and launch-check/409 returns the refreshed screen. If every pending contact is matched, all_contacts_suppressed stays unconditional. skip with a clean screen records nothing and the launch proceeds normally. The default dnc: "block" on an explicit launch is recorded as a decision too, and a later block revokes any earlier skip. An explicit launch that omits dnc therefore never rides on a skip somebody approved in the dashboard: pass dnc: "skip" yourself when that is what the call means. A decision needs an upload to apply to: dnc on a launch of a campaign without an import → 409 dnc_decision_without_upload; on an import without a recorded projection → 409 dnc_screen_required. Before the first launch the screen and the matched-only report follow the live registry. The launch operation re-screens immediately before the transition and freezes all matched rows atomically with the import marker, attestation and campaign state. After launch, reads and reports use that snapshot (as_of_launch: true) even when the registry changes. Contacts matched mid-campaign are still suppressed at dial time; progress counts them separately.

Idempotency of campaign requests

POST /v1/campaigns and POST /v1/campaigns/{id}/calls share one protocol:

The key is reserved before the work starts, atomically. A second request with the same key while the first is still running gets 409 idempotency_key_in_flight — wait for the first answer instead of retrying again.
The body is fingerprinted alongside the key (canonical JSON, key order irrelevant). The same key with a different body is 422 idempotency_key_reuse, never a silent replay of the earlier answer.
The same key with the same body replays the stored 201 byte for byte.
Keys are scoped to your API key, the endpoint and — for calls — the campaign, and remembered for 24 hours.
On creation, a refusal before the campaign exists frees the key; a refusal after it exists keeps it. On calls, any refusal frees the key.

​Campaign fields

​Retry configuration

​The numbers: planned_calls

​Dialing binding

​Attestation

​Do-not-call matches: dnc_screen

​Idempotency of campaign requests