Intake API

Compliance intake is how a patient's answers become an eligibility verdict a licensed provider can act on. This page covers the authenticated intake surface (/v1/intake/*) and the public, origin-allowlisted embed submit (/v1/public/intake/*). For the model behind it, see Intake.

Questionnaires#

A questionnaire is a versioned question set — a formulary's compliance gate. These calls are authenticated with a machine key and require an intake-view scope.

List questionnaires#

curl https://api.neolife.health/v1/intake/questionnaires \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Returns your tenant's questionnaires with their active version.

Get a questionnaire#

Fetch the active version plus version history for one questionnaire, keyed by its stable key:

curl https://api.neolife.health/v1/intake/questionnaires/glp1-eligibility \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Submissions#

A submission is one completed run of a questionnaire, carrying a status, a verdict, and — when eligible and provider-reviewed — a certificate.

List submissions#

curl "https://api.neolife.health/v1/intake/submissions?status=pending" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Query param	Type	Notes
status	string	Filter by submission status (optional).
sandbox	boolean	Pass true to list synthetic sandbox submissions.

Get a submission#

curl https://api.neolife.health/v1/intake/submissions/sub_123 \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Submit in-app#

Staff can run an intake on a patient's behalf — for example, capturing answers over the phone. This is the authenticated counterpart to the public embed.

curl -X POST https://api.neolife.health/v1/intake/submissions \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questionnaireKey": "glp1-eligibility",
    "answers": { "age": 41, "pregnant": false, "bmi": 31 },
    "patient": { "name": "Jane Doe", "email": "[email protected]" }
  }'

Field	Type	Notes
questionnaireKey	string	Which questionnaire to run.
answers	object	Answer map keyed by question id.
patient	object	Optional { name, email, patientId }.

The response carries the submissionId and a verdict — eligible, disqualified, or incomplete.

Review a submission#

Reviewing a clinical intake is a licensure act. This endpoint is provider-gated: the caller needs the intake-review scope and a verified NPI. An eligible verdict is not a prescription — a licensed provider makes the call.

curl -X POST https://api.neolife.health/v1/intake/submissions/sub_123/review \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42" \
  -d '{ "decision": "approved", "note": "Reviewed history; clear to prescribe." }'

Field	Type	Notes
decision	"approved" | "rejected"	The provider's determination.
note	string	Optional clinical note.

Send an Idempotency-Key so a retried review never double-records. A caller without the review scope or without an NPI gets 403.

Public embed submit#

The embed is how a patient fills out an intake from your storefront or a hosted check-in page — no user account. Access is scoped by a per-tenant embed key (not an API key) and, outside sandbox, restricted to your allowlisted origins. It returns a patient-safe verdict and certificate only: internal rule ids and the provider packet are never exposed here.

curl -X POST https://api.neolife.health/v1/public/intake/emb_abc123/submissions \
  -H "Origin: https://shop.yourclinic.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42" \
  -d '{
    "questionnaireKey": "glp1-eligibility",
    "answers": { "age": 41, "pregnant": false, "bmi": 31 },
    "patient": { "name": "Jane Doe", "email": "[email protected]" }
  }'

The path parameter is your embed key. Origin (or Referer) must match an allowlisted origin — a mismatch is rejected. A signed follow-up token (for a refill check-in) may accompany the body; it binds the answers to the right patient and order server-side.

Field	Type	Notes
questionnaireKey	string	Which questionnaire to run.
answers	object	Answer map keyed by question id.
patient	object	Optional { name, email }.
token	string	Optional signed intake-link token for refill follow-ups.

The response is deliberately minimal:

{
  "submissionId": "sub_123",
  "verdict": "eligible",
  "missingQuestionIds": [],
  "certificate": "cert_...",
  "sandbox": false,
  "message": "Thanks — your answers are with a licensed provider for review. You'll hear back shortly."
}

Field	Meaning
submissionId	The created submission.
verdict	eligible, disqualified, or incomplete.
missingQuestionIds	Question ids still required (when incomplete).
certificate	Certificate reference for an eligible run.
message	A ready-to-render, patient-safe message.

An eligible verdict routes the submission to a provider for review — it does not itself authorize fulfillment. See Intake for the full lifecycle and the rest of the API reference.