Schemas

APIErrorResponse

Standard error envelope for all v2 API errors.

error_code

string · required

Machine-readable UPPER_SNAKE_CASE identifier

message

string · required

Human-readable description

Additional context

Echo of X-Request-ID

AnswerAssessment

string · enum

Enum values:

positive

neutral

negative

The automated quality assessment of a single screening answer.

Booking

An appointment, visit, intake, or inspection was booked. A task can carry more than one booking: every booking made across its attempts is reported.

EntityRef · required

The booked calendar or ATS event, with a deep link when one is available. Its ref is the booking's stable identifier.

kind

BookingKind · enum · required

The type of appointment.

Enum values:

meeting

intake

visit

inspection

demo

required

Appointment start (timezone-aware).

When the booking was confirmed/persisted.

The channel the booking was confirmed on.

object

Extra booking fields specific to your setup. Free-form and not part of the API contract: the keys change without notice, so do not depend on any particular key.

How long the appointment lasts, in minutes.

Appointment end; or derive from duration_minutes.

Physical address or video/phone join target.

How the meeting happens.

BookingParticipant[]

Who attends and in what role. A booking may have several people.

EntityRef[]

Other external records this booking touches: contact / deal / order. The primary is the dedicated external_ref field.

BookingKind

string · enum

Enum values:

meeting

intake

visit

inspection

demo

The type of appointment booked.

BookingParticipant

A person attending a booking.

role

string · minLength: 1 · required

Role in the booking (e.g. rep, buyer, realtor).

Email address.

Display name.

Phone number in E.164 format: a leading + and the country calling code.

BusinessOutcomes

Everything a task achieved, gathered from all of its attempts. The complete picture: several of these can hold at once, so read the field you care about rather than one summary value. New kinds of outcome add keys over time, so ignore keys you do not recognise. An envelope with every field empty means the task has produced no outcomes yet.

Booking[]

Every booking made, across all attempts on the task.

A request to be contacted again later, if any.

The participant's decline of this campaign, if any.

A hand-off to a person, if any.

The most recent qualification, if there was one.

A failed hard requirement of the screening, if any.

The participant's opt-out from all contact, if any.

The most recent screening assessment, if there was one.

SideEffect[]

Every write Ringtime made to your systems, across all attempts.

CallbackChannel

string · enum

Enum values:

voice

sms

The channel a requested callback should happen on.

CallbackPreference

The participant asked to be contacted again later. Only the most recent request for a task is reported.

stated_preference

string · minLength: 1 · required

The participant's stated preference, verbatim natural language ('call me tomorrow afternoon').

The channel the callback should happen on — may differ from where it was asked (asked on WhatsApp to be called = voice).

Extra context.

The resolved callback slot.

CampaignEmbed

The campaign a task belongs to, as a small embedded node. Deliberately minimal: the campaign's identity and shape, not its lifecycle. The campaign's own status is left out on purpose, because it changes independently of the task and a copy here would go stale.

id

string · required

Campaign identifier

object · required

The campaign name in every language it is held in. Keys are BCP 47 language codes, values are the name in that language. Not resolved to a single language: pick the key you want.

Outreach channel for the campaign: voice | whatsapp_chat | sms.

BCP 47 language codes the campaign offers. Null = inherits the screening flow's languages.

ConfirmationChannel

string · enum

Enum values:

voice

sms

calendar_invite

The channel a booking was confirmed on.

CreateTriggerRequest

Body of ``POST /api/v2/triggers``.

campaign

string · minLength: 1 · maxLength: 255 · required

Routing key identifying the target campaign

Disambiguate when one routing key maps to campaigns on multiple channels

The person to contact. Required unless the source named in ids[] lets Ringtime read the person from that system; see Sources. Omitting it for any other source, or when ids is empty, gives a 400 VALIDATION_ERROR. If such a source sends it anyway, the record read from the source wins for every field except language, which is kept as the fallback language. Also required when test_mode is set: the test call goes to this phone number.

Key/values (scalars or nested objects) merged into the task context. See Sources for required context keys.

TriggerId[] · maxItems: 20

External ids for the contact. See Sources for each source's identity and required/optional id types. Omit ids when you have no source system; the contact is then matched on its phone number.

test_mode

boolean

Test run. Ringtime keeps the real candidate record and any updates to your system, but sends every call and message to contact.phone instead of the real person. A STOP reply during a test never opts out the real person. Requires contact.

Default: false

Disinterest

The participant declined this campaign or job. Their choice. A soft decline at campaign level. It ends this outreach but does not stop contact from your organization in general, which is what an opt-out does. It is also a different fact from a screening disqualification, which Ringtime determined and reports separately as not eligible. Only the most recent decline for a task is reported.

Free-text detail.

Why they declined.

EntityRef

A typed pointer to a record, usually one in an external system. Most types name a record in a CRM, an ATS, a calendar or a telephony system. One type points back at Ringtime: `notification` names a message Ringtime sent. Outcomes never carry message bodies, so read a message's subject and body from the Ringtime API through this reference rather than expecting them on the event.

ref

string · minLength: 1 · required

The external id.

type

string · required

What kind of entity this points at. New values are added over time, so treat an unrecognised value as a kind you do not handle yet, never as an error.

Deep link to the entity — when the system provides one or we can compute it from the id.

EnvelopeResponse_TaskCancelResource_

TaskCancelResource · required

Response payload

ResponseMetadata · required

Response metadata

EnvelopeResponse_TaskResource_

TaskResource · required

Response payload

ResponseMetadata · required

Response metadata

EnvelopeResponse_TriggerCreatedResource_

TriggerCreatedResource · required

Response payload

ResponseMetadata · required

Response metadata

Escalation

The conversation was handed to a person. A live transfer that also files a ticket is one escalation, with the transfer as its type and the desk as its target. The ticket itself is reported separately, as a record created in your system. Only the most recent escalation for a task is reported.

reason

string · minLength: 1 · required

Why the conversation was handed to a human.

The handoff target, typed (phone_number / desk / ticket).

Whether the warm transfer actually connected.

How the escalation happened.

EscalationType

string · enum

Enum values:

warm_transfer

deferred

handoff

ticket_logged

How an escalation to a human happened.

FieldChange

One field that was set on a record in an external system. A field can carry up to three names. To show one, read `field_name` and fall back to `field`.

field

string · minLength: 1 · required

The field as the external system names it (its API name, for example postal_code__c), recorded as it was at the time of the write.

required

The new value (null = cleared).

Readable label for the field when one is known (for example "Postcode"), so you can label the change without looking the field up. Null when no label is known beyond field.

The external system's own key for this field. Stable, so you can match on it across writes.

The value before the write, when it is known. Usually null: Ringtime does not read the record back before writing it.

Readable label for previous, on the same terms as value_name. previous always keeps the raw value; null when no label is known.

Readable label for value when one is known (for example "1.0 | Pre-screening" for a pipeline stage id), so you can show the change without resolving ids yourself. value always keeps the raw value. Null when no label is known.

HTTPValidationError

ValidationError[]

InteractionSummary

One attempt on a task: a single call or chat, as a short summary. Every field comes straight off the attempt itself, so the summary reads the same wherever it is embedded. It deliberately carries no fields that would need an extra lookup per attempt.

agent_id

string · required

ID of the agent that handled this interaction

id

string · required

Unique identifier for the interaction

kind

string · enum · required

Interaction channel type

Enum values:

voice

chat

sms

slack

primary_language_code

string · required

Primary language code used in the interaction

status

string · enum · required

Interaction status

Enum values:

pending

active

completed

Display name of the agent

Direction of the interaction (voice only)

Human-readable duration (e.g., '5m 30s')

Duration of the interaction in seconds

When the interaction ended

number_of_turns

integer

Number of interaction turns

Default: 0

When the interaction happened — the media session start, falling back to when it was created for a call that never connected.

Subject of the interaction

AI-generated summary of the interaction

JsonValue

No data returned

LeadQualification

A lead was qualified. Only the most recent qualification for a task is reported.

qualified

string · required

Whether the lead met the agent's qualification gate. New values are added over time, so treat anything other than yes as not qualified.

The filled-in Q&A trail next to the fields summary.

object

The qualifying data that was captured. The keys depend on your setup and are not part of the API contract, so do not depend on any particular key.

Name of the schema that governs fields, when Ringtime has published one for your setup, for consumers that want to validate it.

The 'why' — qualified or not.

LocationType

string · enum

Enum values:

physical

video

phone

How a booked appointment happens.

MessageChannel

string · enum

Enum values:

sms

Channel an outbound message was sent on.

MessageSent

An outbound message was sent (SMS, email, or WhatsApp).

channel

MessageChannel · enum · required

The message channel.

Enum values:

sms

EntityRef · required

Reference to the sent message, as the sending system identifies it.

External reference to the recipient, when known.

type

string · const

Identifies this kind of write.

Const value: message_sent

Default: message_sent

NotEligible

The participant did not meet a hard requirement of the screening. Willing, but cannot be placed: a fixed factual mismatch such as work authorisation, region, or hours. It ends this outreach, but the person stays contactable for future campaigns that do match. It is a different fact from a decline (their choice) and from an opt-out (no contact at all). Only the most recent one for a task is reported. It is recorded only for an objective hard requirement, never because a score was low. A low score stays advice for a person to act on, reported through the screening assessment.

Free-text detail.

The hard mismatch, summarized.

NoteAdded

A note/activity logged against an existing record.

body

string · minLength: 1 · required

The note text.

EntityRef · required

The record the note was logged against.

The note category, when the external system types its notes.

type

string · const

Identifies this kind of write.

Const value: note_added

Default: note_added

OptOut

The participant opted out of all contact from your organization. Only the most recent opt-out for a task is reported.

reason

OptOutReason · enum · required

Why the participant opted out. gdpr = legal objection/erasure request, flagging legal handling beyond the org-wide suppression.

Enum values:

not_interested

found_job

do_not_call

wrong_number

gdpr

other

Free-text detail.

OptOutReason

string · enum

Enum values:

not_interested

found_job

do_not_call

wrong_number

gdpr

other

Why a participant opted out (org-wide do-not-contact).

QualificationAnswer

One filled-in qualification question, recorded as it was asked. Deliberately without a weight or an assessment: qualification is not a scored flow. A scored flow is reported as a screening assessment instead.

answer

string · minLength: 1 · required

The participant's answer, as a free-text summary.

question

string · minLength: 1 · required

The question text as asked — snapshotted.

1-indexed order the question was asked, when known.

RecommendedNextStep

string · enum

Enum values:

proceed

manual_review

Advice on what to do next after a screening. Input to a person, never a verdict.

proceed = the person cleared the bar, so move them to your next step, whatever that is: an intake booking, a second screen, an offer. You decide which. manual_review = someone should look before moving them on.

RecordCreated

A new record was created, optionally under a parent entity.

EntityRef · required

The created record.

Optional parent entity (e.g. the vacancy an application was created under).

type

string · const

Identifies this kind of write.

Const value: record_created

Default: record_created

RecordLinked

A record that already existed in your system was linked to this person. The counterpart of a record being created. Your system already held the person and the match was confident, so nothing was written there. From that point on Ringtime files every later action against that record. It is reported as a side effect all the same, and kept separate from a created record so you can tell "we added this person to your system" apart from "we recognised them in it". The surrounding side effect still reports whether the step succeeded; there was simply no outbound write that could fail.

EntityRef · required

The existing external record the candidate now names.

type

string · const

Identifies this kind of write.

Const value: record_linked

Default: record_linked

RecordUpdated

Fields were set on a record that already existed. A pipeline-stage move or a tag change is reported this way too: it is a change on a `stage` or `tags` field, not a separate kind of write.

FieldChange[] · required

The fields that were set.

EntityRef · required

The record that was updated.

Optional note written in the same call.

type

string · const

Identifies this kind of write.

Const value: record_updated

Default: record_updated

ResponseMetadata

Metadata block for single-resource responses.

Echo of the client-provided X-Request-ID header

ScreeningAnswer

One filled-in screening question — a snapshot taken at assessment time.

answer

string · minLength: 1 · required

The candidate's response, as a free-text summary.

assessment

AnswerAssessment · enum · required

The automated quality assessment of this answer.

Enum values:

positive

neutral

negative

position

integer · required

1-indexed order the question was asked.

question

string · minLength: 1 · required

The question text as asked (resolved to the screening language). Snapshotted — the flow definition can change later.

weight

ScreeningWeight · enum · required

How heavily the question counts — drives scoring (mandatory x4 ... low x1).

Enum values:

mandatory

high

medium

low

What the question is about (topic grouping).

The offered options for choice questions.

The answer format expected.

Join key to the live question definition.

source

string · enum

Where the answer came from: heard = given in this conversation, known = carried over from an earlier one.

Enum values:

heard

known

Default: heard

value

JsonValue

Optional normalized typed answer value

ScreeningAssessment

A screening flow was filled in and scored. An assessment, not a decision. There is deliberately no verdict field: the only decision-like value is the numeric score, which is a measurement, and `recommended_next_step` is advice for a person to act on, never a verdict. Only the most recent assessment for a task is reported.

ScreeningAnswer[] · required

The filled-in flow, ordered by position.

score

integer · min: 0 · max: 100 · required

The overall assessment score, weighted across answers.

Flow display name, resolved to the screening language.

has_mandatory_fail

boolean

A mandatory question scored <= neutral — a knockout (e.g. 'no' on a mandatory driver's-licence question); routes to manual_review.

Default: false

has_soft_negative

boolean

A non-mandatory question scored negative — worth a recruiter's look, not a knockout.

Default: false

The language the screening was conducted in (BCP-47).

Deterministic human-readable summary of the assessment.

Advisory routing hint — input to a human, never a verdict.

score_scale

string · enum

The scale the score is expressed on. binary_interest = synthesized from interest signals (100 = interested, 0 = not interested).

Enum values:

0_100

binary_interest

Default: 0_100

Join key to the live screening-flow definition.

The minimum score this submission was judged against. Null = no threshold was recorded for it; 0 = knockout questions only, with no numeric bar.

ScreeningUnansweredQuestion[]

Flow questions that got no answer, ordered by position.

ScreeningCategory

string · enum

Enum values:

identification

availability

qualification

experience

preference

What a screening question is about (topic grouping).

ScreeningQuestionType

string · enum

Enum values:

yes_no

single_choice

multiple_choice

numeric

free_text

date

The answer format a screening question expects.

ScreeningUnansweredQuestion

A question in the flow that never got an answer. Reported next to the answered questions, because a must-have nobody got to is a reason in its own right: without it a report can say the score is low but never name the missing question. It carries no answer and no assessment, because there is none.

position

integer · required

1-indexed order the question sits at in the flow.

question

string · minLength: 1 · required

The question text (resolved to the screening language). Snapshotted.

weight

ScreeningWeight · enum · required

How heavily the question counts — mandatory means it was a must-have.

Enum values:

mandatory

high

medium

low

Join key to the live question definition.

ScreeningWeight

string · enum

Enum values:

mandatory

high

medium

low

How heavily a screening question counts toward the score.

SideEffect

Ringtime wrote something to a system outside itself. Recorded per attempt, so a task can carry several. `effect` holds the typed write and its `type` says which kind it is. New kinds are added over time: show an unrecognised one from the common fields around it rather than dropping the record.

required

The write itself. type says which kind it is.

integration

string · required

The system that was written to. Free-form: the set of systems Ringtime writes to grows over time, so do not match on a fixed list of values.

required

When the write happened.

succeeded

boolean · required

Whether the external write succeeded.

Short verb for the write, for display and auditing (for example move_stage). It restates what effect already says.

Extra detail about the write, for auditing. Free-form and not part of the API contract; it never contains credentials.

SideEffectNote

A note written alongside a record update, or on its own.

body

string · minLength: 1 · required

The note text.

The note category, when the external system types its notes.

TaskCancelRequest

Cancel-task request payload.

Optional free-form short code for why the task is being cancelled (e.g. 'recruiter_took_over', 'candidate_moved', 'vacancy_closed'). Recorded for analytics and surfaced back to your team.

TaskCancelResource

Result of a task cancellation.

id

string · required

Task identifier

status

string · enum · required

The task's current status. 'cancelled' after a successful stop; an already-terminal task returns its existing status unchanged (the outreach was already over).

Enum values:

created

active

paused

completed

failed

cancelled

When the task was cancelled (its last-updated time). Null when the task is in a non-cancelled terminal state — it concluded on its own.

Echo of the cancellation reason supplied in the request (null if none was given)

TaskExecutionObservation

What Ringtime plans next for a task, or how it ended. Read-only. A planned time is the current plan, not a promise about when the attempt starts.

status

string · enum · required

Where the task stands: its final state, or its current plan.

Enum values:

pending

planned

queued

executing

paused

completed

failed

cancelled

The channel the attempt uses. Null when not yet known.

Why the task ended without a completed attempt, when that is what happened.

When the next attempt is planned, in UTC. It may already be in the past. Null when there is no plan to report.

TaskResource

One task: the outreach Ringtime is running for one person in one campaign.

agent_id

string · required

Agent identifier

business_goal

string · required

Business goal tracked by this task

created_at

string · date-time · required

When the task was created

id

string · required

Task identifier

organization_id

string · required

Organization owning the task

participant_identifier

string · required

Participant phone/email identifier

status

string · enum · required

Task status

Enum values:

created

active

paused

completed

failed

cancelled

updated_at

string · date-time · required

When the task last changed

Everything the task achieved, gathered across its attempts. Returned only when the request asks for include=business_outcomes; null otherwise. An envelope with every field empty means there are no outcomes yet.

The campaign this task belongs to, with its id on the node. Embedded by default when you read a single task. Null when the task has no campaign.

object

Values the agent gathered while running this task. Free-form and not part of the API contract: the keys and their meaning differ per agent and change without notice, so do not depend on any particular key. For results you can rely on, read business_outcomes.

What Ringtime currently plans or has concluded for this task. Returned only when the request asks for include=interactions; null when there is nothing to report. scheduled_at is the current plan for the next attempt, not a promise about when it starts.

The task's attempts, each as a short summary, oldest first. Returned only when the request asks for include=interactions; null otherwise. An empty list means there have been no attempts yet.

Preferred language code

object

Extra data attached to the task. Free-form and not part of the API contract: the keys and their meaning change without notice, so do not depend on any particular key.

participant_first_name

string

Participant first name

Default:

participant_last_name

string

Participant last name

Default:

object

Working context the agent carries between attempts on this task. Free-form and not part of the API contract: the keys and their meaning differ per agent and change without notice, so do not depend on any particular key.

How far the outreach got, counting the best attempt on the task. Voicemail counts as unreached. An attempt that reached the person and ended conclusively counts as resolved. New values are added over time, so tolerate one you do not recognise.

Identifier of the outreach request this task was created from.

The single headline result of the task, for when you do not want to read business_outcomes in full. It is a summary, so use business_outcomes for reporting, billing, or anything you must be able to defend. Null = no attempt has happened yet. none = the person was reached but nothing came of it. New values are added over time, so tolerate one you do not recognise.

TriggerAddress

A contact's address as separate fields. Every field is optional. Send what your system holds. A single-line address goes in ``formatted``; separate components go in their own fields. The agent reads whichever fields are present. None is required.

Belgium-specific apartment / box number

City / municipality

ISO 3166-1 alpha-2 code (e.g. 'BE', 'NL')

Single-line fallback address when the decomposed fields are unavailable

House / building number

Postal / ZIP code

Province / state

Street name

TriggerContact

The person to contact. For most sources this block is the record Ringtime uses. A source that lets Ringtime read the person from that system may omit it outside test mode; see [Sources](https://docs.ringtime.ai/sources). If such a source sends it anyway, the record read from the source wins for name, email, phone and address. Only ``language`` is kept, as the fallback language.

first_name

string · minLength: 1 · maxLength: 255 · required

Contact's first name

language

string · pattern: ^[a-z]{2}(-[A-Z]{2})… · required

BCP 47 language code for the conversation (e.g. 'nl', 'fr-BE')

phone

string · required

Contact's phone number, including the country calling code. Separators and a national trunk prefix are normalized away (e.g. +15555550100)

Contact's address as a structured object

Contact's email address

Contact's last name

When YOUR record for this contact was last changed, with a UTC offset (e.g. '2026-03-03T14:22:00+01:00'). It dates every field in this block, including the address, which is why it sits on the contact and not on the address. Send it when you are enrolling a profile that was edited a while ago, so a later correction from the person is not outranked by today's batch. Omit it and we read the address as of this request. A naive timestamp or one in the future is rejected.

TriggerCreatedResource

The resource returned on a successful trigger (201).

created_at

string · date-time · required

When the trigger was recorded

id

string · required

The trigger's id (trg_ prefixed)

status

string · const · required

Always 'accepted' for a created trigger

Const value: accepted

task_id

string · required

The created task's id (task_ prefixed)

TriggerId

One external identifier from your source system. The identity id type and the allowed and required types depend on the source. See [Sources](https://docs.ringtime.ai/sources) for its contract.

source

string · minLength: 1 · maxLength: 64 · required

Source system the id belongs to, e.g. 'carerix'

type

string · minLength: 1 · maxLength: 64 · required

What the id refers to, e.g. 'candidate', 'application', 'job'

value

string · minLength: 1 · maxLength: 255 · required

The id value in the source system

ValidationError

array · required

msg

string · required

type

string · required

ctx

object

input