> 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. # Generating a patient A job generates one patient. Send `POST /v1/jobs` with a request; every field is optional, so `{}` generates a random patient, of any age, with five documents. ```json { "patient": { "age": 72, "sex": "male", "country": "US", "conditions": [ {"name": "heart failure with reduced ejection fraction", "onset_years_ago": 4}, {"name": "atrial fibrillation"}, {"name": "appendicitis", "resolved": true, "onset_years_ago": 30} ], "procedures": [{"name": "appendectomy", "years_ago": 30}], "medications": [{"name": "apixaban 5 mg", "frequency": "twice daily"}], "allergies": [{"substance": "penicillin", "reaction": "hives"}], "smoking": {"status": "former", "start_age": 20, "quit_age": 55, "packs_per_day": 1}, "narrative": "Retired electrician, lives with his wife, struggles with fluid restriction." }, "complexity": 7, "num_documents": 8, "document_types": ["progress_note", "history_and_physical", "discharge_summary"], "timeline": {"end_date": "2026-06-30"}, "outputs": ["fhir", "notes", "pdf"], "seed": 20260630 } ``` ## The patient Everything in `patient` is a fact the generated patient will have. Whatever you leave out is filled in to fit: a 72-year-old with heart failure gets a plausible medication list, history and care, even if you only name the condition. | Field | | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `age`, `birth_date` | Age when the timeline starts, or the date of birth. Give either or both. Omit them and the age fits the conditions you asked for — an adult for rheumatoid arthritis. A cohort sets its own patients' ages, so this applies to a single patient | | `sex` | `female`, `male`, `other` or `unknown` | | `race`, `ethnicity`, `marital_status`, `occupation` | Free text | | `country` | `US` or `CA`: where the patient lives and is cared for. Addresses, clinicians and coding follow the country | | `conditions` | Conditions the patient has or had, in plain language, with `onset_years_ago` — years before the timeline **starts** — `primary` (see below) and `resolved` if you need them. Others may be added to fit | | `procedures` | Procedures, with `years_ago` — years before the timeline starts. `"years_ago": 0` puts the procedure *during* the timeline, with the documents it produces: a procedure note, and a pathology report for a biopsy | | `medications` | What the patient takes when the timeline starts, by drug name and optionally strength, with `frequency` | | `allergies`, `no_known_allergies` | Allergies, with `reaction`; or `true` for none. Medications the patient is allergic to are never prescribed | | `smoking` | `status` (`never`, `former`, `current_every_day`, `current_some_day`), `start_age`, `quit_age`, `packs_per_day` | | `immunizations_up_to_date` | Whether routine immunizations are current | | `narrative` | Anything else, in plain language, up to 4,000 characters. A state, province or well-known city named here sets where the patient lives, unless `country` or the cohort says otherwise. The structured fields take precedence | > **Tip** > > The patient's history is as it stands when the documents **begin**, so > `onset_years_ago` and `years_ago` count back from there. `"onset_years_ago": 0` > puts a new diagnosis at the start of the documents, which is how you get a > condition's whole workup and treatment to fall within them. Names you give are coded in the record (conditions with SNOMED CT and ICD-10-CM, medications with RxNorm), and keep your wording as their text. ### Primary conditions A primary condition is what the chart is mainly about. Most of the patient's visits, specialists, studies and hospital stays follow from the primary conditions, their complications and their treatment — alongside the routine care and occasional unrelated problems any real chart has. ```json "conditions": [ {"name": "heart failure with reduced ejection fraction", "primary": true}, {"name": "chronic kidney disease stage 3b", "primary": true}, {"name": "hyperlipidemia"} ] ``` Mark as many as apply; complex patients often have several. If you mark none, the conditions you asked for that are not `resolved` are the primary ones, and if you ask for no conditions at all, primary conditions are chosen to fit the patient — none for a healthy one. On a cohort, `primary` applies to the patients given that condition. If none of a patient's conditions is marked there, all of them are primary. ## Complexity `complexity` sets how sick the patient is and how much care they get, from 1 to 10. It is chosen at random if omitted, and reported in the job's `summary`. | | | | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Healthy: no chronic conditions or regular medications; preventive care and minor illnesses | | 2 | One minor ongoing issue, such as seasonal allergic rhinitis; at most one regular medication | | 3 | One well-controlled chronic condition, such as mild hypertension; one or two medications | | 4 | Two well-controlled chronic conditions; two to four medications; an occasional specialist visit | | 5 | Three or four chronic conditions, some with early complications; regular specialist follow-up | | 6 | Four to six conditions, at least one significant (CKD stage 3, heart failure, COPD); occasional emergency visits | | 7 | Five to eight conditions including a serious diagnosis; emergency visits and occasional hospital stays | | 8 | Seven to ten interacting conditions, several specialists, at least one hospital stay a year | | 9 | Severe complex disease, such as end-stage organ disease, metastatic cancer or an organ transplant; frequent hospital stays | | 10 | Very complex congenital or multisystem disease with its complications, such as spina bifida or cystic fibrosis; frequent hospital stays and procedures | ## Documents `num_documents` is how many clinical documents to write, from 1 to 50. An office, emergency, virtual or home visit produces one document. A **hospital stay** produces several: usually an admission history and physical, progress notes on the following days, consult notes when specialists are involved, an operative or procedure note on the day of a procedure, and a discharge summary on the last day. Each counts toward `num_documents`. Restrict the documents to the types you need with `document_types`. Encounters are planned so each type is written where it belongs: **Clinical notes** | `document_types` value | Written for | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `progress_note` | Office, virtual and home visits, and each day of a hospital stay | | `history_and_physical` | Hospital admissions, and pre-operative visits | | `consult_note` | Specialist consultations, in clinic, in hospital or in the emergency department | | `discharge_summary` | The end of a hospital stay: the reason for admission and a single principal diagnosis — headed "Most responsible diagnosis" for Canadian patients, as Canadian hospitals write it — then the secondary diagnoses, hospital course, procedures, discharge medications and follow-up. Asking for discharge summaries gets you hospital stays | | `emergency_department_note` | Emergency visits | | `operative_note` | Surgery, as an inpatient or day case, at the length of a real operative report: pre- and postoperative diagnoses, indications and consent, findings, the procedure step by step (positioning, preparation, each step, closure, counts), blood loss, specimens, drains and disposition | | `procedure_note` | Procedures such as endoscopy, joint injection or cardiac catheterization | | `pathology_report` | Specimens: biopsies and surgical specimens | | `radiology_report` | CT, MRI, ultrasound, X-ray and mammography | | `nursing_note` | Hospital stays and home visits | | `telephone_encounter` | Telephone and virtual contacts | | `preoperative_assessment` | Anesthesia evaluation before a planned operation, in a pre-anesthesia clinic or in hospital before surgery | | `palliative_care_note` | Palliative care consultations and follow-up for serious illness: symptoms, goals of care, advance care planning | | `radiation_oncology_consult` | A radiation oncologist's consultation before a course of radiation therapy | | `radiation_treatment_summary` | A radiation oncologist's summary at the end of a radiation course | **Allied health** | `document_types` value | Written for | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `social_work_note` | Social work assessments and follow-up: coping, supports, finances, housing, discharge and advance care planning | | `occupational_therapy_note` | Occupational therapy: daily activities, upper-limb function, adaptive equipment, home safety | | `physical_therapy_note` | Physical therapy: mobility, gait, strength, balance, assistive devices | | `dietitian_note` | A dietitian's nutrition assessment or follow-up, in ADIME format: intake, weight history, estimated needs, a nutrition diagnosis, the diet or feeding plan, and monitoring | | `speech_language_pathology_note` | Swallowing and communication evaluation and therapy: bedside or instrumental swallow studies, recommended diet and liquid consistencies (IDDSI levels), strategies and goals | | `respiratory_therapy_note` | In hospital or the emergency department: breath sounds, oxygen, treatments given and the response, and ventilator settings where used | | `cardiac_rehabilitation_note` | Outpatient cardiac rehabilitation after a heart attack, stent, bypass or valve surgery, or for heart failure: risk stratification, exercise prescription, session vitals and progress | | `pulmonary_rehabilitation_note` | Outpatient pulmonary rehabilitation for COPD and other chronic lung disease: dyspnea scores, six-minute walk, oxygen use, exercise and education | **Diagnostic reports** | `document_types` value | Written for | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `laboratory_report` | One draw: panels and tests with values, units, flags and reference ranges; collection, receipt and report times; the specimen; any critical result called to the care team | | `microbiology_report` | A culture — urine, blood, sputum, wound — with its Gram stain where done, the result, each organism with its count, and its antibiotic susceptibilities (MIC and S/I/R). Dated when the result is final, which is days after collection. Where an organism resists an antibiotic the patient is taking, the course is stopped that day for one it is susceptible to, and the next document records the change | | `ecg_report` | A resting 12-lead ECG read by a cardiologist: rate, rhythm, PR, QRS, QT/QTc, axis and the interpretation | | `echocardiogram_report` | An echocardiogram read by a cardiologist: chambers, ejection fraction, wall motion, valves and estimated pulmonary pressure | | `cardiac_study_report` | A stress test, Holter or event monitor, or cardiac catheterization, read by a cardiologist | | `pulmonary_function_report` | Pulmonary function tests read by a pulmonologist: spirometry with percent predicted, bronchodilator response, lung volumes and diffusing capacity | **Insurance** | `document_types` value | Written for | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insurance_coverage_summary` | The eligibility and benefits check printed at registration: each active plan with its member ID, group, subscriber, effective date and benefits — copays, deductible, prior authorization requirements | | `prior_authorization_request` | A request from the ordering clinician's office asking the insurer to approve a service before it is done — advanced imaging, a specialty drug, elective surgery, equipment — with the service, diagnoses in ICD-10-CM, and the clinical justification | | `letter_of_medical_necessity` | A letter from the treating clinician explaining why a service or drug is medically necessary for this patient: history, alternatives tried, and the expected benefit | Charts include the allied health, diagnostic and insurance documents where the patient's care calls for them — speech-language pathology after a stroke, cardiac rehabilitation after a heart attack, a prior authorization before advanced imaging. Each report type stays a minority of the chart, at most a tenth of it, so name one in `include_document_types` to be sure of at least one. ### Insurance documents Three things worth knowing before you use them: * **Every detail is fictional.** Insurers have generic names such as "Regional Health Plan". Member IDs and clinician NPIs are invented — and the NPIs are built to **fail** the NPI check digit, so none can ever match a real clinician's. * **No CPT or HCPCS codes.** Services are described in words. Diagnoses carry ICD-10-CM codes. * **The coverage fits the patient.** In the US, Medicare or Medicare Advantage from 65, commercial or Medicaid otherwise, and a parent's plan for a child. In Canada, the provincial plan, often with extended health benefits. A document type that records a procedure (operative, procedure, radiology and pathology reports) comes with that procedure in the record. Oncology and hematology notes open with the patient's oncologic history in a sentence or two — stage, biomarkers, and each treatment with its cycles, dose, fractions and dates — and their assessment and plan covers the treatment, the response and side effects, the next steps with dates, and what was agreed with the patient. When you don't restrict `document_types`, a patient's documents fit their problems. A patient with cancer has oncology notes, imaging and pathology reports, and radiation oncology notes when radiation is part of treatment. A patient with advanced cancer has palliative care and social work notes, and an operation comes with its preoperative assessment, operative report and pathology report. Left to itself a chart follows a realistic mix — mostly visits and consultations, with fewer reports. ### Only these types, or include these types `document_types` **restricts** the chart to the types you list. To get a normal chart that is sure to contain certain documents, list those in `include_document_types` instead: the chart then has at least one of each, and the rest of its documents fit the patient's care. ```json {"num_documents": 10, "include_document_types": ["radiology_report", "pathology_report"]} ``` The two work together — every type you include must also be in `document_types`, where you give both. A request cannot include more types than it has documents, which for a cohort means no more than `documents_per_patient.min`. > **Note** > > Radiation oncology documents are written while the patient is treated. To get them, describe > a cancer diagnosed near the start of the timeline (for example `"onset_years_ago": 0`), so > its treatment falls within the documents' dates. ## Timeline By default the documents end today and start far enough back to fit them, given the patient's complexity. Set `timeline.end_date`, `timeline.start_date`, or both, to place them. If you give the patient both `age` and `birth_date`, the timeline starts when the patient is that age. Before the timeline, the record holds the patient's history: past conditions, procedures, immunizations and the medications they take when it starts. ## Outputs | `outputs` value | You get | | --------------- | ------------------------------------------------------------------------ | | `fhir` | `fhir_bundle.json`, a FHIR R4 transaction bundle of the whole record | | `notes` | `notes.zip`, each document as text | | `pdf` | `notes_pdf.zip`, each document as a PDF, plus the whole chart as one PDF | `result.json`, the patient's full record, is always included. The default is `["fhir", "notes"]`. See [Results](/synth/guides/results). ## Reproducing a patient The job's `summary.seed` identifies the patient. Send it as `seed` with the same request, and the new patient has the same dates, age, sex, state or province, and complexity. The rest of the record and the documents are generated again, so they are similar but not identical. ## Cancelling `DELETE /v1/jobs/{job_id}` cancels a queued job, or a running one (its results are discarded). Canceled jobs are not billed. ## When a job fails A job that could not be completed has status `failed` and an `error` with a code: ```json { "id": "…", "status": "failed", "error": { "code": "invalid_request", "message": "patient.birth_date is after the timeline start" } } ``` See [Errors](/synth/reference/errors) for the codes.