Skip to main content
POST
Record that your patient dropped off the questionnaire

Authorizations

Authorization
string
header
required

Per-client API key (M2M). Presented as Authorization: Bearer <key>.

Headers

X-Correlation-Id
string

An optional id you send to tie this request to your own logs. Send one and it is echoed back unchanged; omit it and one is assigned for you. Either way the id is returned in the X-Correlation-Id response header on every response, including errors, so you can match a response to the request that produced it.

Maximum string length: 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
X-Brand-Id
string
required

Opaque brand id (brd_...). Validated to belong to the resolved client (§2).

Pattern: ^brd_[A-Za-z0-9][A-Za-z0-9_-]*$

Body

application/json
session_id
string
required

Response

abandonment recorded

The result of a resolve, next, or abandon call — the session identity, the current question (or null when finished), the status, any flags (e.g. ship_state_mismatch), and any validation issues. On completion it may carry the entry-link hand-off.

journey_id
string
required
Pattern: ^jny_[A-Za-z0-9][A-Za-z0-9_-]*$
session_id
string
required
status
enum<string>
required

active (a node is presented), complete (server-authoritative completion), abandoned (patient drop-off), or blocked — a terminal, server-authoritative refusal to proceed (a required consent was declined or could not be affirmed). On blocked, node is null and blocked carries the honest stop-screen outcome.

Available options:
active,
complete,
abandoned,
blocked
blocked
object

The honest stop-screen outcome. Present only when status is blocked. Carries the machine-readable reason, the node at which the block occurred, the consent scopes that were not granted (codes, never patient data), and a support-routing hint. The stop-screen copy is a presentation concern (the intake kit renders it); no patient data ever rides here. No order lock ever forms without a positive affirmation where one is required.

flags
string[]
handoff
object

Post-completion hand-off carried when a session that began from an entry link completes. Present only when status is complete and the session carried a validated entry context. redirect holds a brand-allowlisted https URL; promo is an opaque pass-through token validated downstream; test is the per-client test-mode flag. Never carries patient data.

issues
object[]
node
object | null

A node as presented to the client — PRESENTATION ONLY. The client never owns the sequence, controls, or option order (those come from the compiled bundle; a brand theme cannot alter them). Brand theme/copy, when applied, ride alongside as presentation overlay.

progress
object

Server-computed progress metadata, present on every resolve/next step: computed from the live effective plan — never client-guessed. position_estimate is the honest fraction of the plan completed (0..1); display nodes participate in the fraction. Whether and how it renders (thin persistent bar, step ring, interstitial pacing, none) is brand-theme presentation.