Tasks

A Task is the single resource you program against. Every capability — intake, coverage, engagement — is a Task differentiated by its task_type. Everything you do is: create a Task, add data to it, read it back, or list Tasks. A Task is returned as a TaskDetails object from every endpoint except the download-link one.

Creating a Task

POST /task/create is the entry point. It is a multipart/form-data request:

cURL

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

The response comes back immediately with status: "pending" and empty verdicts — Synthpop processes the work in the background.

{
  "uuid": "0685bb22-eeec-776c-8000-ad631be0e894",
  "external_id": "order-4821",
  "task_type": "task",
  "status": "pending",
  "name": "Robert: 7",
  "cleared": null,
  "created": "2026-07-15T08:24:15.571185Z",
  "latest_status_change": "2026-07-15T08:24:15.571185Z",
  "category": null,
  "data_items": [ /* ... */ ],
  "issues": [],
  "verdicts": []
}

The API is asynchronous. Results exist only after you poll GET /task/get to a terminal status, or receive a callback. See Async results.

`task_type` (required)

string

required

Determines what processing Synthpop performs. Task types are provisioned for your organization during onboarding — there is no discovery endpoint, so the values available to you come from your Synthpop contact. Passing an unprovisioned type returns 400 "Task type 'X' not in list of tasks for your organization: [...]."

Optional inputs on create

file[]

Zero or more documents (PDFs, images, text, audio). Uploads are deduplicated by content — re-submitting identical bytes is a no-op, not a duplicate. (An upload where every file is a duplicate returns 409 rather than a no-op.)

object

Task-type-specific JSON configuration. What it accepts depends on the task_type; leave it empty unless your Synthpop contact specifies fields.For validation and referral task types, request_spec accepts a patient_hcpcs field. This field gives the order’s HCPCS or CPT codes directly, instead of relying on document extraction alone.patient_hcpcs accepts two shapes:

A JSON array of code strings, for example ["E0470", "E1161"]. This is the current shape. Synthpop strips whitespace from each entry and drops empty entries.
A single string with codes separated by whitespace, for example "E0470 E1161". This is the original shape, kept for existing callers.

Synthpop does not validate array entries beyond converting each entry to a string. Send only code strings in the array.A related field, patient_icd10, accepts diagnosis codes as a whitespace-separated string only. patient_icd10 does not accept the array shape.

Synthpop checks patient_hcpcs and patient_icd10 together. A code in either field turns off document extraction for both codes and diagnoses on that Task. Send both fields together, or send neither.

string

Your own identifier for this Task, echoed back on every read. It is a correlation key, not an idempotency key — sending the same external_id twice creates two Tasks. Use it to tie Synthpop’s work back to a record in your system and to find related Tasks via GET /task/list.

string

An optional friendly label. If you omit it, Synthpop derives a name from the extracted content (e.g. "Jordan Lee (1985-04-12): Order intake").

string

A URL pattern (with {uuid} and {external_id} placeholders) that Synthpop calls when the Task finishes. Callbacks are opt-in and org-gated — they fire only for organizations that have them enabled. See Async results.

The `TaskDetails` shape

string (uuid)

required

Synthpop’s unique ID for the Task.

string | null

required

Your correlation key (see above), or null.

string

required

The type the Task was created with.

TaskStatus

required

The current state. See the status lifecycle below.

string

required

A user-friendly name, derived from extracted inputs if you did not supply one.

string | null

required

A suggested category determined from the medical records found (e.g. "outpatient-referral"). null until enough has been extracted.

string (date-time) | null

required

Marks that follow-up work external to Synthpop is done. You set cleared with a boolean via PATCH /task/{uuid}/update; it reads back as the timestamp it was set at (or null if never set).

string (date-time)

required

When the Task was created.

string (date-time)

required

When the status last changed (entered processing, waiting, completed, or failed). Equal to created while the Task is pending.

DataItem[]

required

The Task’s inputs, outputs, and extracted records. See Data Items.

TaskIssue[]

required

Issues detected with the Task or its medical records. See Results.

Verdict[]

Per-code approval decisions (validation tasks). See Results.

VerdictSummary[]

Per-code human-readable conclusions (validation tasks). See Results.

The status lifecycle

status is a TaskStatus — one of exactly these six values you can observe and no others. (The underlying TaskStatus enum also defines deferred, but the API never returns it — a deferrable Task reports as pending until it runs.)

Status	Terminal?	Meaning
`pending`	No	Created and waiting to be processed. The initial status of every Task.
`processing`	No	Actively being processed.
`waiting`	No	Paused, awaiting additional input from you (e.g. a missing document). Resume it by updating or uploading.
`completed`	Yes	Processing finished successfully; results are available.
`failed`	Yes	An error occurred during processing.
`invalid`	Yes	The uploaded data provides no information relevant to the requested task.

waiting is not an error or a stuck state. A Task in waiting needs something from you before it can continue — typically a document flagged in its issues. Supply it and the Task resumes. See Responding to waiting tasks.

Frozen tasks — a 409 condition, not a status

When a newer patient-matched Task supersedes an older one, the older Task is frozen. Frozen is not a status value — it is a condition you discover by trying to add to the Task. Uploading to a frozen Task returns 409 with a TaskFrozenError body:

string

required

Human-readable description of the error.

string (uuid)

required

The UUID of the current, non-frozen Task that your uploads should be directed to.

{
  "message": "This task has been superseded and can no longer accept uploads.",
  "current_task_uuid": "0685cd41-1a2b-7c3d-8000-9e0f1a2b3c4d"
}

Redirect your upload to current_task_uuid. This is detailed in Responding to waiting tasks.

Working with an existing Task

Endpoint	What it does
`GET /task/get`	Read a Task by `uuid` xor `external_id` (supplying neither or both is a `400`).
`PATCH /task/{uuid}/update`	Change metadata (`name`, `cleared`, `external_id`) and resume a `waiting` Task.
`POST /task/{uuid}/upload`	Add more files to a Task awaiting input.
`POST /task/{task_uuid}/log_event`	Record a client-side event against a Task (your own event logging).
`GET /task/list`	List your Tasks, filtered/sorted/paginated. See Listing tasks.

Every Task is org-scoped: it is visible only to the organization that owns it. See Authentication.

Get started

Core concepts

Working with the API

Referral & order intake

Coverage & authorization

Patient engagement

Resources

Support

Creating a Task

`task_type` (required)

Optional inputs on create

The `TaskDetails` shape

The status lifecycle

Frozen tasks — a 409 condition, not a status

Working with an existing Task

​Creating a Task

​task_type (required)

​Optional inputs on create

​The TaskDetails shape

​The status lifecycle

​Frozen tasks — a 409 condition, not a status

​Working with an existing Task

Creating a Task

`task_type` (required)

Optional inputs on create

The `TaskDetails` shape

The status lifecycle

Frozen tasks — a 409 condition, not a status

Working with an existing Task