API v2

Read one task: the outreach Ringtime is running for one person in one campaign. The response carries who the task is for, its status, how far outreach got (reach), and the headline result (task_outcome). The campaign the task belongs to is embedded by default.

Use include to ask for more in the same call. include=business_outcomes adds the full result of the outreach: every booking, the screening assessment, opt-outs, and the writes we made in your systems. include=interactions adds one summary per attempt (each call or chat), and is also what fills execution. Both cost an extra lookup, so ask for them only when you need them.

A task belonging to another organization answers 404, exactly like a task id that does not exist.

Stop all outreach for one task. Use it when someone on your side has taken the person over, or the reason for the outreach is gone. Ringtime cancels the task, the call or message it had planned, any remaining retries, and a warm-up message that has not gone out yet. The person's place in the campaign reads as cancelled from the next request on.

The call is idempotent. Cancelling a task that has already finished returns 200 with the status it actually has, because the effect you asked for (no further outreach) already holds. cancelled_at is set only when this task really is cancelled; a task that concluded on its own reports its own status and a null cancelled_at.

A call already in progress is not hung up. Cancelling stops what has not started yet.

Start outreach to a contact. Ringtime enrols the contact in the campaign with this routing key and creates a task for it.

The Test button sends a real request to production. Keep test_mode: true while you try the API. The call then goes to the phone number in contact, not to a real candidate. Set it to false only for real outreach.

contact is required unless the source named in ids[] lets Ringtime read the person from that system. See Sources for the required ids and context keys. Test mode always requires contact.

409 SOURCE_RECORD_NOT_AVAILABLE + Retry-After: 60 is a retryable refusal, only possible for such a fetching source: the record was addressed correctly but the source has not made it readable yet (we read a synced copy). Re-POST the identical body after the given delay. Nothing was enrolled and — unlike every other outcome — no row appears in the trigger audit log, because the retries would flood it; the eventual accepted request is recorded normally.

409 CAMPAIGN_NOT_READY means the body passed every check on your side — schema, ids, contact, context, language — but the campaign it names is still being set up by Ringtime (no agent assigned). Nothing was enrolled. Keep the body and send it again on a later run; there is no Retry-After because the wait is on Ringtime, not on a sync. details.reason is AGENT_NOT_ASSIGNED.

422 has two body shapes. A body that does not match the schema (a phone without a country calling code, an unknown field, a bad e-mail) is refused before the handler runs with FastAPI's {"detail": [...]} list, one entry per field. A body that matches the schema but names a language the campaign does not run in is refused by the handler with the error_code envelope: LANGUAGE_NOT_SUPPORTED, where details.requested is what you sent and details.supported lists the languages on offer. CHANNEL_MISMATCH uses the same envelope when channel names a channel this routing key has no campaign on. Tell them apart by the presence of detail (a list) versus error_code.