Skip to navigation
Synth API ReferenceCohorts

Submit a cohort

Generate many patients from one specification, cared for in one fictional health system. Returns at once with the cohort, queued; poll it with GET /v1/cohorts/{cohort_id}.

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.
sizeintegerRequired1-50
Number of patients.
ageobjectOptional
Age range, years.
female_proportiondoubleOptional0-1Defaults to 0.5
Share of female patients, e.g. 0.6.
complexityobjectOptional
1 to 10.
conditionslist of objectsOptional

Conditions given to an exact share of the patients (rounded); others still arise naturally.

documents_per_patientobjectOptional
Clinical documents per patient.
document_typeslist of enums or nullOptional

Only these document types. Chosen per patient if omitted. To get normal charts that also have certain types, use include_document_types instead.

include_document_typeslist of enums or nullOptional

Make sure every patient’s chart has at least one document of each of these types; the rest are the usual mix. At most documents_per_patient.min types.

timelineobjectOptional
When the documents happen.
countryenum or nullOptional
Country of the health system. Random if omitted.
Allowed values:
regionstring or nullOptional
State or province for the health system, e.g. 'Ohio'. Random if omitted.
outputslist of enums or "bulk"Optional

Each patient’s fhir bundle, notes, and pdfs (as for a job), and bulk: the whole cohort as FHIR Bulk Data (NDJSON).

seedinteger or nullOptional

Random seed: the same request gives the same cohort.

Response

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

idstringformat: "uuid"
statusenum
Allowed values:
created_atdatetime
sizeinteger
Patients requested.
max_documentsinteger

Most documents the cohort can produce (size x documents per patient).

progressobject
Patients by status.
started_atdatetime or nullOptional
finished_atdatetime or nullOptional
errorobject or nullOptional
Why the cohort failed, if it did.
summaryobject or nullOptional
What was delivered, 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