Patients are the foundational resource in ClinikAPI. Every clinical record — encounters, observations, prescriptions, labs, and more — is linked to a patient. Under the hood, ClinikAPI maps your simplified JSON to a FHIR R4 Patient resource stored in AWS HealthLake. You interact with patients through clinik.patients.
Create a patient
Pass the patient’s demographics to clinik.patients.create. All fields except firstName and lastName are optional, but including contact info and birth date makes search much more effective.
const { data: patient } = await clinik.patients.create({
firstName: 'Jane',
lastName: 'Doe',
email: '[email protected]',
phone: '+1-555-0100',
gender: 'female',
birthDate: '1990-03-15',
address: {
line: ['123 Main St', 'Apt 4B'],
city: 'Austin',
state: 'TX',
postalCode: '78701',
country: 'US',
},
});
console.log(patient.id); // "pt_abc123"
Read a patient
Fetch a single patient by ID. Use the include option to pull related resources in one request — ClinikAPI uses FHIR _revinclude under the hood to avoid N+1 lookups.
const { data } = await clinik.patients.read(patient.id!, {
include: ['Encounter', 'Observation', 'MedicationRequest', 'Appointment'],
});
console.log(data.patient); // Patient resource
console.log(data.encounters); // Encounter[]
console.log(data.observations); // Observation[]
console.log(data.prescriptions); // MedicationRequest[]
console.log(data.appointments); // Appointment[]
PatientReadResponse includes every resource type linked to the patient:
| Field | Type | Description |
|---|
patient | Patient | The patient resource |
encounters | Encounter[] | All encounters for this patient |
observations | Observation[] | Vitals, lab values, etc. |
medications | Medication[] | Medication records |
appointments | Appointment[] | Scheduled appointments |
intakes | QuestionnaireResponse[] | Intake forms |
consents | Consent[] | Signed consents |
labs | DiagnosticReport[] | Lab reports |
prescriptions | MedicationRequest[] | Prescriptions |
notes | DocumentReference[] | Clinical notes |
assessments | ClinicalImpression[] | Clinical assessments |
documents | Composition[] | Structured documents |
Only request the include types you actually need. Fetching all resource types on every read adds latency and increases response size.
Update a patient
clinik.patients.update applies a partial update — send only the fields you want to change. ClinikAPI uses JSON Patch under the hood.
const { data: updated } = await clinik.patients.update(patient.id!, {
phone: '+1-555-0200',
address: {
line: ['456 Oak Ave'],
city: 'Dallas',
state: 'TX',
postalCode: '75201',
},
});
Delete a patient
await clinik.patients.delete(patient.id!);
Deleting a patient does not cascade to related resources. Delete dependent resources first if needed, or query with include to identify them before deletion.
Search patients
Search supports partial name matching and exact matches on contact fields. Results are paginated — use cursor to fetch the next page.
const { data: results } = await clinik.patients.search({
name: 'Doe',
gender: 'female',
count: 20,
});
for (const patient of results.data) {
console.log(patient.name?.[0]?.family); // "Doe"
}
// Fetch the next page
if (results.hasMore) {
const { data: nextPage } = await clinik.patients.search({
name: 'Doe',
cursor: results.cursor,
});
}
Search parameters
| Parameter | Type | Description |
|---|
name | string | Search by name (partial match) |
email | string | Exact email match |
phone | string | Exact phone match |
birthDate | string | Date of birth (YYYY-MM-DD) |
gender | string | male, female, other, unknown |
active | boolean | Filter by active status |
count | number | Results per page (default: 20, max: 100) |
cursor | string | Pagination cursor from previous response |