Multi-patient submissions

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

Submit the packet

POST /task/create with your multi-patient task_type and the file(s). You get a parent Task back with status: "pending".

Synthpop splits it

The parent Task separates the patients, groups each one’s pages, and creates a child Task for each.

Read the child Tasks

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:

curl "https://app.synthpop.ai/public/v1/task/get?uuid=$PARENT_UUID" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN"

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:

{
  "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_types 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 — 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. 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.

Validate an order

Poll and interpret each child Task with the standard flow.

Listing tasks

Filter, sort, and page through Tasks to reconcile a submission.

Intake overview

How the intake capability maps to the API.

Responding to waiting tasks

Complete a child Task that pauses for more documents.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

Multi-patient submissions

How it works

Discovering the child Tasks

1. Read the parent’s child-task output

2. Correlate with your own IDs via `GET /task/list`

Notes and limits

Validate an order

Listing tasks

Intake overview

Responding to waiting tasks

​How it works

​Discovering the child Tasks

​1. Read the parent’s child-task output

​2. Correlate with your own IDs via GET /task/list

​Notes and limits

​Related

Validate an order

Listing tasks

Intake overview

Responding to waiting tasks

How it works

Discovering the child Tasks

1. Read the parent’s child-task output

2. Correlate with your own IDs via `GET /task/list`

Notes and limits

Related