Responding to waiting Tasks

The waiting/resume loop

A Task does not always run straight to a terminal status. When Synthpop determines it needs more from you — a missing document, an additional field — the Task pauses at status: "waiting". This is a normal, expected state, not a failure. Your integration’s job is to supply what’s missing and let the Task continue:

Detect waiting

While polling GET /task/get (or on a callback), you see status: "waiting". Inspect the Task’s issues to understand what is needed — for example a task.medical_record.missing or task.data.missing entry.

Supply the missing input

Add files with POST /task/{uuid}/upload, or add structured JSON with PATCH /task/{uuid}/update. Both are covered below.

Resume and keep polling

Uploading resumes the Task automatically. Updating resumes it only when you pass ?should_resume=true. The Task moves back to processing and continues toward a terminal status (or pauses at waiting again if more is still needed).

A Task only accepts additional input while it is waiting. Sending files or a resume to a Task in any other status is rejected with 409 — see Frozen and non-waiting Tasks.

Add files: `POST /task/{uuid}/upload`

Use this when the missing input is one or more documents. It is a multipart/form-data request with one or more uploads parts — the same shape as the files you passed to POST /task/create. The Task must be in waiting. The response is an UploadDataResponse:

Field	Type	Description
`new_data_items`	array of UUIDs	IDs of the newly created data items, in the same order as the files in your request.
`task`	`TaskDetails`	The Task’s new state after the uploads were applied.

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

import requests

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

with open("progress-note.pdf", "rb") as f1, open("insurance-card.jpg", "rb") as f2:
    resp = requests.post(
        f"{BASE_URL}/task/{task_uuid}/upload",
        headers={"Authorization": f"Bearer {jwt_token}"},
        files=[
            ("uploads", ("progress-note.pdf", f1, "application/pdf")),
            ("uploads", ("insurance-card.jpg", f2, "image/jpeg")),
        ],
    )

resp.raise_for_status()
body = resp.json()
new_ids = body["new_data_items"]      # -> ["<uuid>", "<uuid>"]
task = body["task"]                    # -> TaskDetails, now back in "processing"

Uploads are deduplicated by content: re-sending the identical bytes is a no-op rather than a duplicate data item. external_id is a correlation key, not an idempotency key — it does not affect dedup. If all files in an upload are duplicates, the upload returns 409 instead.

Add structured data: `PATCH /task/{uuid}/update`

Use this when the missing input is structured data rather than a file, or when you want to change Task metadata. The request body is a TaskUpdateRequest; set only the fields you want to change and omit the rest.

Field	Type	Description
`name`	string	Set the Task’s user-friendly name.
`cleared`	boolean	Mark that your org’s follow-up work for this Task is (in)complete. You set `cleared` with a boolean via update; it reads back as the timestamp it was set at (or `null`).
`external_id`	string	Set or change your correlation ID for the Task.
`new_data_item`	JSON object	Add a new JSON data item to the Task — this is how you supply structured input to a `waiting` Task.

To actually resume a waiting Task after adding data, pass the query parameter ?should_resume=true. It defaults to false, so an update alone changes metadata without restarting processing.

curl -X PATCH "https://app.synthpop.ai/public/v1/task/$TASK_UUID/update?should_resume=true" \
  -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "new_data_item": {
          "date_of_service": "2026-07-01",
          "referring_provider_npi": "1234567890"
        }
      }'

import requests

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

resp = requests.patch(
    f"{BASE_URL}/task/{task_uuid}/update",
    headers={"Authorization": f"Bearer {jwt_token}"},
    params={"should_resume": "true"},
    json={
        "new_data_item": {
            "date_of_service": "2026-07-01",
            "referring_provider_npi": "1234567890",
        }
    },
)

resp.raise_for_status()
task = resp.json()  # -> TaskDetails

Metadata-only changes (renaming, setting cleared, changing external_id) are valid on a Task in any status and do not require should_resume. Use should_resume=true only when you have added the input the Task was waiting for.

Frozen and non-waiting Tasks

Two situations return 409 Conflict from POST /task/{uuid}/upload:

The Task is not waiting. It is not accepting additional input.
The Task is frozen. A newer, patient-matched Task has superseded this one. The 409 body is a TaskFrozenError, which names the Task you should be working with instead:

409 TaskFrozenError response body

{
  "message": "This task has been superseded and is frozen; upload to the current task instead.",
  "current_task_uuid": "3f6b2c1a-9d4e-4b7a-8c21-0a1b2c3d4e5f"
}

When you receive a TaskFrozenError, redirect your upload to current_task_uuid — do not retry against the frozen Task. Fetch that Task with GET /task/get?uuid=<current_task_uuid>, confirm it is waiting, and add your input there. Retrying the frozen UUID will only return 409 again.

Working with async results

How to detect the waiting status while polling or via callback.

Errors

Every status code the API returns, with real error bodies.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

Responding to waiting Tasks

The waiting/resume loop

Add files: `POST /task/{uuid}/upload`

Add structured data: `PATCH /task/{uuid}/update`

Frozen and non-waiting Tasks

Working with async results

Errors

​The waiting/resume loop

​Add files: POST /task/{uuid}/upload

​Add structured data: PATCH /task/{uuid}/update

​Frozen and non-waiting Tasks

​Related

Working with async results

Errors

The waiting/resume loop

Add files: `POST /task/{uuid}/upload`

Add structured data: `PATCH /task/{uuid}/update`

Frozen and non-waiting Tasks

Related