Referral & order intake

Intake is the work of turning an incoming referral or order — often a multi-page fax, email, or scanned packet — into a decision your team can act on: are the right documents present, and do they support the requested service under the patient’s plan? Synthpop automates that end to end. You submit the documents, and Synthpop reads them, extracts structured records, checks them against clinical and payer requirements, and returns a per-code verdict plus a plain-English conclusion and a list of any issues. This capability is healthcare-generic. The same flow validates DME and HME orders, lab and imaging referrals, prescriptions, and more — the only thing that changes is the task_type your organization is provisioned with.

Example: a sleep-study (HST) referral. Throughout these guides we use one concrete example — validating a Home Sleep Test referral packet with the hst_validation_bin task type. It is only an example; the contract and the result shape are identical for any order or referral you validate.

How intake maps to the API

There are no intake-specific endpoints. Intake is the general Task flow pointed at a validation task_type:

Create a validation Task

POST /task/create with a validation task_type and the referral or order documents under uploads. It returns immediately with status: "pending" and empty verdicts — the work has only been queued.

Wait for it to finish

Poll GET /task/get, or receive an opt-in callback, until the Task reaches a terminal status. A Task that needs more documents pauses at waiting.

Read the verdict

A completed validation Task carries verdict_summaries, verdicts, and issues — the structured decision and everything Synthpop flagged.

task_type is required and provisioned for your organization during onboarding — there is no endpoint that lists available types. Ask your Synthpop contact which validation task types are enabled for you. An unknown value returns 400 "Task type 'X' not in list of tasks for your organization: [...]."

What a validation result contains

When the Task reaches completed, the decision lives in these fields of the returned TaskDetails:

Field	What it holds
`verdict_summaries`	A per-`code`, human-readable `conclusion` — the plain-English summary.
`verdicts`	The machine-readable decision per `code`: whether it was `approved`, and which `issues` (by list index) affected it.
`issues`	Everything Synthpop flagged — missing records, expired documents, inconsistent data, and so on — each with a `message` and a `key`.
`data_items`	The `inputs`-group documents you uploaded and any `outputs` Synthpop produced, plus the extracted `medical_records` found within them.

code is the unit of approval — for example an HCPCS procedure code. A single Task can carry several codes, each with its own verdict.

A verdict’s issues field is a list of integer indices into TaskDetails.issues, not the issues themselves. To find out why a code was not approved, look up each index in the top-level issues array. See Validate an order for a worked example.

When a Task pauses at `waiting`

Validation frequently reveals that a required document is missing — a signed order, a face-to-face visit note, an insurance card. Rather than failing, the Task stops at status: "waiting" and lists what it needs in issues. You add the missing files with POST /task/{uuid}/upload and the Task resumes on its own. This is the normal intake loop, not an error — see Responding to waiting tasks.

The public status is always waiting when a Task needs more input — a normal pause, not an error.

Validate an order

The full end-to-end walkthrough: create, poll, and interpret the result.

Multi-patient submissions

When one packet contains several patients, and how to find the child Tasks.

Results: verdicts & issues

The full shape of verdicts, summaries, and task issues.

Responding to waiting tasks

Upload the missing documents and resume a paused Task.

Get started

Core concepts

Working with the API