> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# 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.

|                    |                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authentication** | `Authorization: Bearer <key>`, using an [API key](/platform/api-keys) or an [OAuth 2.0 access token](/platform/oauth-clients) with the `synth:process` scope |
| **Format**         | JSON requests; results as JSON, FHIR R4 JSON, or zip files of text, PDF and NDJSON                                                                           |
| **Retries**        | Send an `Idempotency-Key` with each submission to make it safe to retry. See [Errors](/synth/reference/errors#retrying-safely)                               |
| **Results**        | Each downloadable once, within 24 hours of the job finishing                                                                                                 |
| **Billing**        | Per clinical document, for the patients delivered. See [Billing](#billing)                                                                                   |

## Jobs and cohorts

|                  | Job                                                 | Cohort                                                                                                               |
| ---------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Generates**    | One patient                                         | Up to 50 patients in one health system                                                                               |
| **You describe** | The patient: any facts they must have               | The population: age range, share of women, conditions and their prevalence, documents per patient, state or province |
| **You get**      | FHIR bundle, documents (text, PDF), the full record | A folder per patient, the whole cohort as FHIR Bulk Data, and a summary                                              |
| **Guide**        | [Generating a patient](/synth/guides/patients)      | [Generating a cohort](/synth/guides/cohorts)                                                                         |

## 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](/platform/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](mailto:support@emtelligent.com), quoting the `request_id`
from an error response or the job `id`.