> ## 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.
# Multi-patient submissions
> When one submission contains several patients, Synthpop can split it into child Tasks — one per patient — and route each to the right validation workflow.
Intake queues receive packets that bundle **more than one patient** into a single
file — a fax with several orders stapled together, or a roster listing many
patients at once. Rather than forcing your team to sort pages by hand, Synthpop
can detect the multiple patients, group each one's documents, and create a
**child Task per patient**, each validated independently.
Multi-patient handling is enabled per organization and per `task_type`. Ask
your Synthpop contact whether it is provisioned for you and which task type to
use. Where it is not enabled, a submission that contains more than one patient
may instead pause at `waiting` for you to separate the documents yourself.
## How it works
You create one Task for the whole submission, exactly as in
[Validate an order](/guides/intake/validate-an-order). If Synthpop finds multiple
patients, that Task acts as a **parent**: it fans out into one child Task per
patient, and each child runs its own validation workflow, routed automatically
from that patient's documents.
`POST /task/create` with your multi-patient `task_type` and the file(s). You
get a parent Task back with `status: "pending"`.
The parent Task separates the patients, groups each one's pages, and creates a
child Task for each.
Discover the child Task IDs (below), then poll and interpret each child the
same way you would any validation Task.
**Example: a mixed sleep packet.** A single fax contains a Home Sleep Test
referral for one patient and intake forms for another. Synthpop creates two
child Tasks: the first is routed to HST validation, the second to a patient
record workflow. The example is illustrative — the same split works for any mix
of orders and referrals.
## Discovering the child Tasks
`TaskDetails` has **no** `parent_task_id` or `children` field. There is no
schema field that links a child back to its parent, or a parent to a fixed list
of children. Use one of the discovery paths below instead.
There are two reliable ways to find the children.
### 1. Read the parent's child-task output
When the parent Task finishes splitting, it emits an **`outputs`-group data item** whose
`tag` is `child-tasks`. Its JSON `data` carries the child Task UUIDs:
```bash cURL theme={null}
curl "https://app.synthpop.ai/public/v1/task/get?uuid=$PARENT_UUID" \
-H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN"
```
```python Python theme={null}
def get_child_task_ids(parent: dict) -> list[str]:
for item in parent["data_items"]:
if item.get("tag") == "child-tasks" and item.get("data_type") == "json":
return item["data"].get("child_tasks", [])
return []
parent = poll_task(jwt_token, parent_uuid) # from the validate-an-order guide
child_ids = get_child_task_ids(parent)
for child_id in child_ids:
child = poll_task(jwt_token, child_id)
print(child["uuid"], child["task_type"], child["status"])
```
The relevant part of the parent's response looks like this:
```json theme={null}
{
"uuid": "06892416-b68f-715e-8000-eae6dc59120a",
"task_type": "task_multi_patient",
"status": "completed",
"data_items": [
{
"uuid": "0689241f-33ed-7339-8000-ce712bd44305",
"group": "outputs",
"tag": "child-tasks",
"name": "Child Tasks",
"data_type": "json",
"data": {
"child_tasks": [
"0689241f-2235-7caf-8000-63d6f8507911",
"0689241f-294b-757c-8000-ead09d80d908"
]
}
}
],
"issues": [],
"verdicts": []
}
```
`task_multi_patient` is an **illustrative** placeholder, not a real value.
Multi-patient `task_type`s are provisioned per organization during onboarding;
your Synthpop contact tells you the concrete value to use.
Each child is an ordinary Task. Poll and interpret it exactly as in
[Validate an order](/guides/intake/validate-an-order) — including handling any
child that stops at `waiting` because it needs more documents.
### 2. Correlate with your own IDs via `GET /task/list`
If you want to track children in your own system, or reconcile them after the
fact, use [`GET /task/list`](/guides/listing-tasks). Filter by `task_type` and a
`date_from`/`date_to` window around when you submitted the parent, then match the
returned Tasks against what you expect. Each child carries its own `uuid` and, if
your workflow set one, its own `external_id`.
Set a distinctive `external_id` on the parent (e.g. `batch-2026-07-15-A`) so you
can find the whole submission again with `GET /task/get?external_id=...`, then
pull the child IDs from its `child-tasks` output. `external_id` is a correlation
key, so children created for that submission are what you reconcile against your
own records.
## Notes and limits
* **Children may pause at `waiting`.** Splitting a patient out does not guarantee
their documents are complete. A child validation Task can stop at `waiting`
asking for a missing record, just like any other — resolve it the same way.
* **Routing is automatic.** Each child's downstream validation workflow is chosen
from that patient's documents; you don't select it.
* **Availability varies.** Both splitting and the behaviour for an unenabled
organization depend on your provisioning — confirm with your Synthpop contact.
## Related
Poll and interpret each child Task with the standard flow.
Filter, sort, and page through Tasks to reconcile a submission.
How the intake capability maps to the API.
Complete a child Task that pauses for more documents.