Skip to navigation
Synth API ReferenceJobs

Submit a job

Generate one synthetic patient. Returns at once with the job, queued; poll it with GET /v1/jobs/{job_id} until it has succeeded, then download its results.

Authentication

AuthorizationBearer

An API key, or an OAuth 2.0 access token, with the synth:process scope.

Headers

Idempotency-Keystring or nullOptional

Optional, recommended: retrying with the same key and body returns the original job (200) instead of creating, and charging for, a second one. Per organization, for 24 hours. 1-128 of [A-Za-z0-9_.:-].

Request

This endpoint expects an object.
patientobject or nullOptional
Facts the patient must have.
complexityinteger or nullOptional1-10

1 = healthy, routine care only; 10 = multiple serious chronic conditions with frequent specialist and inpatient care. Random if omitted.

num_documentsintegerOptional1-50Defaults to 5

Clinical documents to generate. A visit produces one; a hospital stay can produce several (H&P, progress notes, consults, operative note, discharge summary).

document_typeslist of enums or nullOptional

Only these document types. Generator chooses if omitted. To get a normal chart that also has certain types, use include_document_types instead.

include_document_typeslist of enums or nullOptional

Make sure the chart has at least one document of each of these types; the rest are the chart’s usual mix (of document_types, if given). At most num_documents types.

timelineobjectOptional
When the documents happen.
outputslist of enumsOptional

fhir: a FHIR R4 bundle; notes: the documents as text; pdf: each document as a PDF, plus the whole chart as one. The patient’s full record (result) is always included.

Allowed values:
seedinteger or nullOptional
The same request with the same seed generates the same patient.

Response

Idempotent retry: the job already created with this Idempotency-Key

idstringformat: "uuid"
statusenum
Allowed values:
created_atdatetime
num_documentsinteger
Clinical documents requested.
attemptsinteger

Times processing started; a job interrupted on our side is retried.

started_atdatetime or nullOptional
finished_atdatetime or nullOptional
errorobject or nullOptional
Why the job failed, if it did.
summaryobject or nullOptional
The patient generated, once succeeded.
resultslist of objectsOptional
Files ready to download.
results_expire_atdatetime or nullOptional
Files not downloaded by then are deleted.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error