Validate an order

This is the complete intake flow. You’ll create a validation Task with a document, poll it until it finishes, handle the case where it needs more input, and read the structured decision back out. Every request is grounded in the public API — there are no intake-specific endpoints.

Base URLs

Production: https://app.synthpop.ai/public/v1
Staging: https://stage.synthpop.ai/public/v1

The examples use production and assume $SYNTHPOP_JWT_TOKEN holds a valid bearer token. If you don’t have one yet, see the Quickstart and Authentication.

Example task type. These examples use hst_validation_bin — validating a sleep-study (HST) referral packet — as a concrete, real value. Your organization’s validation task types are provisioned during onboarding; swap in the one you were given. There is no endpoint that lists them.

Create the validation Task

POST /task/create is a multipart/form-data request. Set task_type to your provisioned validation type and attach the referral or order document(s) under uploads. You can attach several files in one request — a whole packet at once.

curl -X POST "https://app.synthpop.ai/public/v1/task/create" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
  -F "task_type=hst_validation_bin" \
  -F "uploads=@referral-packet.pdf;type=application/pdf" \
  -F "external_id=order-4821"

from pathlib import Path
import requests

BASE_URL = "https://app.synthpop.ai/public/v1"

def create_validation_task(
    jwt_token: str, file_path: Path, task_type: str, external_id: str | None = None
) -> dict:
    data = {"task_type": task_type}
    if external_id is not None:
        data["external_id"] = external_id
    with file_path.open("rb") as f:
        response = requests.post(
            f"{BASE_URL}/task/create",
            headers={"Authorization": f"Bearer {jwt_token}"},
            data=data,
            files={"uploads": (file_path.name, f, "application/pdf")},
        )
    response.raise_for_status()
    return response.json()

task = create_validation_task(
    jwt_token,
    Path("referral-packet.pdf"),
    task_type="hst_validation_bin",
    external_id="order-4821",
)
print(task["uuid"], task["status"])  # -> "<uuid>" "pending"

The response is a TaskDetails object. It comes back right away with status: "pending" and empty verdicts — nothing has been evaluated yet:

{
  "uuid": "06862491-0dc0-77b7-8000-0539870235af",
  "external_id": "order-4821",
  "task_type": "hst_validation_bin",
  "status": "pending",
  "name": "Order 4821",
  "cleared": null,
  "created": "2026-07-15T08:21:37.396333Z",
  "latest_status_change": "2026-07-15T08:21:37.396333Z",
  "category": null,
  "data_items": [
    {
      "uuid": "06862491-168e-7d50-8000-539ce3c38468",
      "group": "inputs",
      "tag": "upload",
      "name": "referral-packet.pdf",
      "created": "2026-07-15T08:21:37.396333Z",
      "data_type": "file"
    }
  ],
  "issues": [],
  "verdicts": [],
  "verdict_summaries": []
}

Hold onto uuid. If you passed an external_id, you can also read the Task by that instead.

external_id is a correlation key — a handle from your own system you can later read the Task by. It does not make creates idempotent. Deduplication is content-based: uploading identical bytes again is a no-op.

Poll until the Task reaches a terminal status

GET /task/get returns the current TaskDetails. Supply exactly one of uuid or external_id (neither or both returns 400). Poll until the Task settles.The terminal statuses are completed, failed, and invalid. A Task can also stop at waiting, which means it needs more input from you (next step); pending and processing both mean “keep polling.”

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

# Or read it back by your own correlation id:
curl "https://app.synthpop.ai/public/v1/task/get?external_id=order-4821" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN"

import time

TERMINAL = {"completed", "failed", "invalid"}

def poll_task(jwt_token: str, uuid: str) -> dict:
    headers = {"Authorization": f"Bearer {jwt_token}"}
    while True:
        response = requests.get(
            f"{BASE_URL}/task/get",
            headers=headers,
            params={"uuid": uuid},
        )
        response.raise_for_status()
        task = response.json()
        status = task["status"]
        print(f"status: {status}")

        if status in TERMINAL or status == "waiting":
            return task
        time.sleep(5)

task = poll_task(jwt_token, task["uuid"])

Prefer not to poll? If your organization has callbacks enabled, pass a callback_template URL on create and Synthpop issues a GET to it when the Task finishes. Callbacks are opt-in and gated per organization — see Working with async results.

Handle a Task that stops at `waiting`

Validation often finds a required document missing. Instead of failing, the Task stops at status: "waiting" and lists what it needs in issues — here, a missing face-to-face visit note and insurance carrier:

{
  "uuid": "06862491-0dc0-77b7-8000-0539870235af",
  "external_id": "order-4821",
  "task_type": "hst_validation_bin",
  "status": "waiting",
  "name": "Order 4821",
  "category": "HST",
  "issues": [
    {
      "key": "task.medical_record.missing",
      "medical_record_type": "face to face visit note",
      "message": "Upload a face-to-face visit note."
    },
    {
      "key": "task.data.missing",
      "property": "insurance_carrier",
      "message": "Missing insurance carrier."
    }
  ],
  "verdicts": [
    { "code": "hst", "approved": false, "issues": [0, 1] }
  ],
  "verdict_summaries": []
}

Add the missing files with POST /task/{uuid}/upload (the Task must be in waiting to accept them), then go back to polling. The Task resumes on its own.

curl -X POST "https://app.synthpop.ai/public/v1/task/$TASK_UUID/upload" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
  -F "uploads=@visit-note.pdf;type=application/pdf"

def upload_more(jwt_token: str, uuid: str, file_path: Path) -> dict:
    with file_path.open("rb") as f:
        response = requests.post(
            f"{BASE_URL}/task/{uuid}/upload",
            headers={"Authorization": f"Bearer {jwt_token}"},
            files={"uploads": (file_path.name, f, "application/pdf")},
        )
    response.raise_for_status()
    return response.json()

upload_more(jwt_token, task["uuid"], Path("visit-note.pdf"))
task = poll_task(jwt_token, task["uuid"])  # resume polling

For the full resume loop — including what to do when the Task keeps asking for more — see Responding to waiting tasks.

Interpret the completed result

Once the Task is completed, read the decision from three fields. Here is a completed validation result for our example packet:

{
  "uuid": "06862491-0dc0-77b7-8000-0539870235af",
  "external_id": "order-4821",
  "task_type": "hst_validation_bin",
  "status": "completed",
  "name": "Order 4821 (12/31/1999): HST",
  "cleared": null,
  "created": "2026-07-15T08:21:37.396333Z",
  "latest_status_change": "2026-07-15T08:24:29.954317Z",
  "category": "HST",
  "data_items": [
    {
      "uuid": "0686249b-de84-7ae9-8000-9d974cde3912",
      "group": "outputs",
      "tag": "referral-text",
      "name": "Home Sleep Test Analysis",
      "created": "2026-07-15T08:24:29.954317Z",
      "data_type": "text",
      "data": "Issues: No issues found — service supported. Conclusion: The packet supports the requested home sleep test. Documented daytime sleepiness, fatigue, habitual loud snoring, and an Epworth Sleepiness Scale score of 11 support medical necessity."
    }
  ],
  "issues": [],
  "verdicts": [
    { "code": "hst", "approved": true, "issues": [] }
  ],
  "verdict_summaries": [
    {
      "code": "hst",
      "conclusion": "Documentation supports the requested service. Required clinical evidence and a signed order are present."
    }
  ]
}

Read the three fields together:

verdict_summaries — the plain-English conclusion per code. Show this to a human reviewer.
verdicts — the machine-readable decision per code: approved true or false, and an issues list.
issues — the flat list of everything flagged. Each entry has a key (its type) and a human-readable message.

A verdict’s issues are indices into the top-level issues array, not the issues themselves. When a code is not approved, resolve each index to explain why:

def explain_verdicts(task: dict) -> None:
    issues = task["issues"]
    for verdict in task["verdicts"]:
        status = "APPROVED" if verdict["approved"] else "NOT APPROVED"
        print(f"{verdict['code']}: {status}")
        for i in verdict["issues"]:
            print(f"  - {issues[i]['message']} ({issues[i]['key']})")

explain_verdicts(task)

For a not-approved code, this prints the exact blocking reasons — for example:

hst: NOT APPROVED
  - Upload a face-to-face visit note. (task.medical_record.missing)
  - Missing insurance carrier. (task.data.missing)

A completed Task is not necessarily an approved one. Always check each verdict.approved — a Task can reach completed with unmet criteria and a false verdict. completed means “Synthpop finished evaluating,” not “the order is supported.”

That’s the full intake loop: create, poll, resolve waiting, and interpret the verdict. Wire the same pattern behind your own intake queue.

Intake overview

How the capability maps to the API and what a result contains.

Multi-patient submissions

When one packet holds several patients and splits into child Tasks.

Results: verdicts & issues

Every issue key and the full verdict shape.

Working with async results

Polling versus callbacks, and load backpressure.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

Validate an order

Intake overview

Multi-patient submissions

Results: verdicts & issues

Working with async results

​Related

Intake overview

Multi-patient submissions

Results: verdicts & issues

Working with async results

Related