Skip to navigation
Overview

Overview

The Synth API generates realistic synthetic patients for testing, development and demonstrations. No real patient data is returned. Each patient comes with:

  • a coded record: demographics, conditions, procedures, medications, allergies, immunizations, encounters, vital signs and laboratory results, coded with SNOMED CT, ICD-10-CM, RxNorm, LOINC and CVX;
  • a FHIR R4 bundle of that record, ready to load into a FHIR server;
  • clinical documents written over the patient’s history, such as progress notes, consult notes, discharge summaries, operative notes and radiology reports, as text or PDF.

The documents and the record agree: a medication in a note is on the medication list, a laboratory value quoted in a discharge summary is the one that was resulted, and a hospital stay produces the admission, daily progress notes and discharge summary you would expect.

Ask for a random patient, or describe the one you need: age, sex, conditions, medications, allergies, smoking history, or a plain-language description. Generate one patient with a job, or up to 50 at once with a cohort: patients cared for in one fictional regional health system, sharing its hospitals, clinics and clinicians, with conditions given to the share of patients you choose.

How a request works

The API is asynchronous. You submit a job, wait for it to finish, then download each result once.

POST   /v1/jobs                        → 202, the job: {"id": "…", "status": "queued", …}
GET    /v1/jobs/{job_id}               → status: queued → running → succeeded | failed | canceled
GET    /v1/jobs/{job_id}/results/{name} → fhir, notes, pdf or result, once each
DELETE /v1/jobs/{job_id}               → cancel the job

Cohorts work the same way, under /v1/cohorts. A patient usually takes one to five minutes, depending on how many documents you ask for; a cohort’s patients are generated in parallel.

AuthenticationAuthorization: Bearer <key>, using an API key or an OAuth 2.0 access token with the synth:process scope
FormatJSON requests; results as JSON, FHIR R4 JSON, or zip files of text, PDF and NDJSON
RetriesSend an Idempotency-Key with each submission to make it safe to retry. See Errors
ResultsEach downloadable once, within 24 hours of the job finishing
BillingPer clinical document, for the patients delivered. See Billing

Jobs and cohorts

JobCohort
GeneratesOne patientUp to 50 patients in one health system
You describeThe patient: any facts they must haveThe population: age range, share of women, conditions and their prevalence, documents per patient, state or province
You getFHIR bundle, documents (text, PDF), the full recordA folder per patient, the whole cohort as FHIR Bulk Data, and a summary
GuideGenerating a patientGenerating a cohort

Billing

A job is billed for the documents it asked for (num_documents) once it succeeds. A cohort is billed for the documents of the patients it delivers; a patient that failed is not billed. Failed and canceled jobs and cohorts are not billed.

When you submit, credit is set aside for the most the request can produce. If your organization does not have enough, the request is refused with 402 insufficient_credit and nothing is queued. See Billing for credit and prices.

Synthetic data

Every patient, clinician, facility and document is fictional. Names, identifiers and addresses are generated, and any resemblance to real people is coincidental. Each PDF is marked as synthetic. Do not use the data as a basis for clinical decisions.

Versioning

The API is versioned in the path (/v1). Changes within v1 are additive: new optional fields, new error codes, new document types. Ignore fields you do not recognise. A breaking change will come as a new version, with advance notice.

Support

Email support@emtelligent.com, quoting the request_id from an error response or the job id.