curl --request GET \
--url https://api.dev.purplelabelmd.com/v1/instrument/resolve \
--header 'Authorization: Bearer <token>' \
--header 'X-Brand-Id: <x-brand-id>'import requests
url = "https://api.dev.purplelabelmd.com/v1/instrument/resolve"
headers = {
"X-Brand-Id": "<x-brand-id>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Brand-Id': '<x-brand-id>', Authorization: 'Bearer <token>'}
};
fetch('https://api.dev.purplelabelmd.com/v1/instrument/resolve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.dev.purplelabelmd.com/v1/instrument/resolve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Brand-Id: <x-brand-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.dev.purplelabelmd.com/v1/instrument/resolve"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Brand-Id", "<x-brand-id>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.dev.purplelabelmd.com/v1/instrument/resolve")
.header("X-Brand-Id", "<x-brand-id>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.dev.purplelabelmd.com/v1/instrument/resolve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Brand-Id"] = '<x-brand-id>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"journey_id": "<string>",
"session_id": "<string>",
"status": "active",
"blocked": {
"code": "<string>",
"node_id": "<string>",
"support_route": "<string>",
"ungranted_scopes": [
"<string>"
]
},
"flags": [
"<string>"
],
"handoff": {
"promo": "<string>",
"redirect": "<string>",
"test": true
},
"issues": [
{
"code": "<string>",
"message": "<string>",
"conflicting_codes": [
"<string>"
],
"exclusive_codes": [
"<string>"
]
}
],
"node": {
"kind": "question",
"node_id": "<string>",
"section_id": "<string>",
"computed_stub": true,
"consent_version": "<string>",
"content": {},
"control": "<string>",
"copy": "<string>",
"display": "static",
"fact": "<string>",
"grants": [
"<string>"
],
"interstitial": true,
"may_auto_advance": true,
"media": {
"kind": "image",
"accept": [
"<string>"
],
"capture_mode": "upload",
"consent_copy": "<string>",
"consent_fact": "<string>",
"consent_version": "<string>",
"facing": "user",
"max_bytes": 123,
"max_duration_s": 123,
"min_duration_s": 123,
"require_consent": true,
"resumable": true
},
"offering_refs": [
"<string>"
],
"option_codes": [
"<string>"
],
"options": [
{
"code": "<string>",
"classification_code": "<string>",
"exclusive": true,
"label": "<string>"
}
],
"prefill": "collect",
"prefilled_value": "<unknown>",
"reassurance": "<string>",
"required": true,
"theme": {},
"values": {},
"zone": {
"scale_max": 123,
"scale_min": 123,
"zone_label": "<string>",
"zone_max": 123,
"zone_min": 123
}
},
"progress": {
"position_estimate": 0.5,
"scope": "<string>",
"section_label": "<string>"
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}Start an intake session and get the first question
Begins an intake questionnaire for your patient and returns the first question to present. On the first call the server mints an enrollment id (returned as journey_id) that identifies the session on every later call; send it back in the X-Journey-Id request header on a return visit to resume. The server owns the question sequence, branching, and completion — a client cannot skip, hide, or reorder questions, and any value pre-filled from an entry link is always shown for explicit confirmation, never accepted on the patient’s behalf. WHICH questionnaire is served follows your brand’s configured therapies: a brand with exactly one enabled therapy always serves that therapy’s questionnaire; a brand with more than one must name an offering on the entry link so the therapy is unambiguous. If that therapy’s questionnaire is briefly still loading, the session opens on the platform’s shared questionnaire rather than failing. If your brand’s therapy has no questionnaire at all — none is published for it, or the brand is configured for a therapy this platform does not serve — the call is REFUSED (422) rather than answered with a different therapy’s questions, which would be neither safe nor useful; and an error is likewise answered when no questionnaire is available at all. PROOF-OF-IDENTITY CAPTURE IS NEVER PART OF THIS QUESTIONNAIRE. Questions that collect a government ID are withheld from this surface and are not counted toward its completion, so the patient finishes the intake here and verifies identity in the member portal’s own identity step. Clinical photo capture and the consent video are unaffected and continue to be served exactly as before.
curl --request GET \
--url https://api.dev.purplelabelmd.com/v1/instrument/resolve \
--header 'Authorization: Bearer <token>' \
--header 'X-Brand-Id: <x-brand-id>'import requests
url = "https://api.dev.purplelabelmd.com/v1/instrument/resolve"
headers = {
"X-Brand-Id": "<x-brand-id>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Brand-Id': '<x-brand-id>', Authorization: 'Bearer <token>'}
};
fetch('https://api.dev.purplelabelmd.com/v1/instrument/resolve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.dev.purplelabelmd.com/v1/instrument/resolve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Brand-Id: <x-brand-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.dev.purplelabelmd.com/v1/instrument/resolve"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Brand-Id", "<x-brand-id>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.dev.purplelabelmd.com/v1/instrument/resolve")
.header("X-Brand-Id", "<x-brand-id>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.dev.purplelabelmd.com/v1/instrument/resolve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Brand-Id"] = '<x-brand-id>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"journey_id": "<string>",
"session_id": "<string>",
"status": "active",
"blocked": {
"code": "<string>",
"node_id": "<string>",
"support_route": "<string>",
"ungranted_scopes": [
"<string>"
]
},
"flags": [
"<string>"
],
"handoff": {
"promo": "<string>",
"redirect": "<string>",
"test": true
},
"issues": [
{
"code": "<string>",
"message": "<string>",
"conflicting_codes": [
"<string>"
],
"exclusive_codes": [
"<string>"
]
}
],
"node": {
"kind": "question",
"node_id": "<string>",
"section_id": "<string>",
"computed_stub": true,
"consent_version": "<string>",
"content": {},
"control": "<string>",
"copy": "<string>",
"display": "static",
"fact": "<string>",
"grants": [
"<string>"
],
"interstitial": true,
"may_auto_advance": true,
"media": {
"kind": "image",
"accept": [
"<string>"
],
"capture_mode": "upload",
"consent_copy": "<string>",
"consent_fact": "<string>",
"consent_version": "<string>",
"facing": "user",
"max_bytes": 123,
"max_duration_s": 123,
"min_duration_s": 123,
"require_consent": true,
"resumable": true
},
"offering_refs": [
"<string>"
],
"option_codes": [
"<string>"
],
"options": [
{
"code": "<string>",
"classification_code": "<string>",
"exclusive": true,
"label": "<string>"
}
],
"prefill": "collect",
"prefilled_value": "<unknown>",
"reassurance": "<string>",
"required": true,
"theme": {},
"values": {},
"zone": {
"scale_max": 123,
"scale_min": 123,
"zone_label": "<string>",
"zone_max": 123,
"zone_min": 123
}
},
"progress": {
"position_estimate": 0.5,
"scope": "<string>",
"section_label": "<string>"
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}Authorizations
Per-client API key (M2M). Presented as Authorization: Bearer <key>.
Headers
The patient's enrollment id (jny_...) — the resume channel. Send it on a return visit and the questionnaire resumes that patient's session with everything already answered applied; omit it and a new enrollment id is minted. A malformed value is ignored and treated as absent, never trusted.
^jny_[A-Za-z0-9][A-Za-z0-9_-]*$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.
128^[A-Za-z0-9][A-Za-z0-9._:-]*$Opaque brand id (brd_...). Validated to belong to the resolved client (§2).
^brd_[A-Za-z0-9][A-Za-z0-9_-]*$Query Parameters
an existing enrollment id (returning patient) as a query parameter — a compatibility channel. On the hosted platform this query parameter is not read: the enrollment id rides the X-Journey-Id request header, and that header is the resume mechanism. Absent both, a new enrollment id is minted.
^jny_[A-Za-z0-9][A-Za-z0-9_-]*$serve ONE tier of the instrument as an independent phase. qualification plays the pre-pay funnel-top tier and completes at the qualification terminal (the journey then hands to checkout); clinical plays the post-pay tier (re-resolved by the same enrollment id after checkout) and completes at the usual intake terminal. OMITTED ⇒ the continuous single-pass flow (unchanged): the whole instrument, one terminal. Requires a tier-aware bundle; an unknown value is rejected 400.
qualification, clinical preselect a catalog offering by STABLE ref (never a free-text product name). Resolvable only against the compiled bundle's declared offering refs; an unresolvable ref FAILS CLOSED to the generic flow. Effect is presentation-only narrowing of display-node offering_refs — EXCEPT for a brand configured with MORE THAN ONE enabled therapy, where this parameter is additionally REQUIRED and is a DECLARED RESOLUTION INPUT: it selects which of that brand's enabled therapies the session's questionnaire comes from. Omitting it, naming a ref that belongs to none of the brand's enabled therapies, or naming one that belongs to more than one, is REFUSED (422) — never guessed. For a brand with a single enabled therapy (and for a brand with none) the parameter does not change which SHARED questionnaire is served. SECOND DECLARED EFFECT — YOUR OWN QUALIFICATION QUESTIONS. On an entry that carries no journey (the direct-buy intake the site kit uses, where this endpoint is the op that mints the journey), this parameter ALSO selects WHICH of your brand's own qualification questions are composed onto the served plan, funnel-top: the ones you attached to the offering you name here. This applies only when your brand has declared its enabled therapies and the session resolved one of them; a brand that has declared none is served exactly as before. When the session's journey already recorded an offering, THAT offering wins and this parameter is not consulted for question selection. Naming an offering the platform's committed catalog does not bind, naming one you attached no questions to, or naming a malformed ref all FAIL CLOSED to the shared questionnaire with no error — the parameter can never conjure questions you did not author, and can never reach another brand's questions. THE TREATMENT-AGREEMENT RULE, and the one case that is REFUSED rather than ignored: the offering you name must belong to the SAME treatment the session resolved. Naming a real offering of a DIFFERENT treatment — even one your own brand sells — is refused with the 422 config-gap, not served: a patient must never be asked one treatment's questions while buying another, and answering them silently would be worse than refusing. The refusal is oracle-free: it is the same single answer every structural cause gives, and it names no offering, treatment or brand. An offering the platform cannot bind at all is NOT this case — it simply selects nothing and the shared questionnaire serves as before, so a stale or mistyped link degrades gently while a genuinely wrong-treatment link is caught.
128^[A-Za-z0-9][A-Za-z0-9_.:-]*$stage a contact-email prefill. Lands unverified: nothing is written until the patient acts at the confirm step (which ALWAYS renders — prefill is never silent acceptance); a confirm-as-is records method=patient_reported, never validated/patient_confirmed.
254same contract as prefill_email, for the contact phone.
32an opaque promo token, passed through unchanged to the completion hand-off. It is not interpreted here; validation, eligibility, and stacking are applied downstream.
256post-completion return URL. Honored ONLY if it matches the brand config's redirect_allowlist (absolute https, exact origin + path-segment prefix); anything else is refused — open redirect barred, fail closed. Surfaces on the completion handoff.
2048per-client test-mode flag; passed through unchanged.
true, false, 1, 0 Response
the minted/loaded session + the first node (or complete)
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.
^jny_[A-Za-z0-9][A-Za-z0-9_-]*$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.
active, complete, abandoned, blocked 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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes