Skip to main content
Everything on this site runs against the test-mode environment with test-scoped keys and synthetic data only. There is no path from these docs to production or to real patient data.

​
1. Get access

  • Docs access: this site is gated (visitor authentication is on pre-release). Access is provisioned for internal staff and design partners during onboarding.
  • API access: your onboarding contact issues a per-client test API key and your X-Brand-Id value. See Authentication.

​
2. Make your first call

Resolve the intake instrument for the product the patient chose - this mints a journey and returns the first node:
$OFFERING_REF is one of the offering references in your welcome kit. A brand with more than one treatment refuses a start without it (422). An offering for a different treatment than the one the session resolves is refused the same way. The response carries a session_id, a journey_id (prefixed jny_), and the first node to present. The examples use the names from your welcome kit. $PURPLE_API_BASE is the API origin your welcome kit states, of the form https://api.<env>.purplelabelmd.com (the test environment’s hosts are on Environments). The base is an origin only, and /v1 is written into every path, so never add /v1 to the base itself. $PURPLE_API_KEY is your test API key, and $BRAND_ID is your brand id (brd_...).

​
3. Walk the instrument

Submit the current node’s answer; the server advances exactly one step:
  • Echo the served node_id. It ties your answer to the question you showed. Without it, an answer can land on the wrong question after the server skips one.
  • Shape the answer by the node’s control. Choice controls send the selected option codes as {"codes": [...]}. Text, email, number, date and phone controls send {"value": ...}. The example above answers an email question. See how serving works.
  • A display node collects nothing. Send its node_id with no answer to move past it.
Repeat while status is active. Stop when it is complete, blocked or abandoned. blocked means the server ended the questionnaire (for example, a required consent was declined); the step then carries a blocked object with the reason. The server owns sequence, branching, and completion - a client can never skip or reorder steps.

​
4. Read the journey status

Returns the partner-visible status projection - IDs and status values only, never patient data. This read has more than one documented outcome. Besides the refusals any key-authenticated call can return, it may return 422 with the type https://purple.md/problems/journey-status-pending instead of a status value - a typed “no status yet” response, meaning your request was well-formed and the enrollment is yours but the platform has no status to report for it. Branch on the type, keep your normal authentication and error handling, and see when a status is not yet reportable.

​
5. Try it in the playground

Every endpoint page in the API reference tab has an interactive playground. Set your test key once and drive the same flow from the browser. The playground targets the test-mode environment only.