> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synthpop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referral & order intake

> Automate intake: submit the documents you already receive and get back a structured, per-code validation result.

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.

<Note>
  **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.
</Note>

## How intake maps to the API

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Read the verdict">
    A completed validation Task carries `verdict_summaries`, `verdicts`, and
    `issues` — the structured decision and everything Synthpop flagged.
  </Step>
</Steps>

<Note>
  `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: [...]."`
</Note>

## 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.

<Warning>
  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](/guides/intake/validate-an-order) for a worked example.
</Warning>

## 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](/guides/responding-to-waiting-tasks).

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

## Next

<CardGroup cols={2}>
  <Card title="Validate an order" icon="file-import" href="/guides/intake/validate-an-order">
    The full end-to-end walkthrough: create, poll, and interpret the result.
  </Card>

  <Card title="Multi-patient submissions" icon="users" href="/guides/intake/multi-patient">
    When one packet contains several patients, and how to find the child Tasks.
  </Card>

  <Card title="Results: verdicts & issues" icon="clipboard-check" href="/concepts/results">
    The full shape of verdicts, summaries, and task issues.
  </Card>

  <Card title="Responding to waiting tasks" icon="reply" href="/guides/responding-to-waiting-tasks">
    Upload the missing documents and resume a paused Task.
  </Card>
</CardGroup>