Patients
Patients are the core resource in ClinikAPI. Every clinical resource (encounters, observations, prescriptions, etc.) references a patient.
Create a Patient
const { data: patient } = await clinik.patients.create({
firstName: 'Jane',
lastName: 'Doe',
email: '[email protected]',
phone: '+1-555-0100',
gender: 'female',
birthDate: '1990-03-15',
maritalStatus: 'married',
address: {
line: ['123 Main St', 'Apt 4B'],
city: 'Austin',
state: 'TX',
postalCode: '78701',
country: 'US',
},
languages: [
{ language: 'en', preferred: true },
{ language: 'es' },
],
contact: [
{
relationship: 'spouse',
firstName: 'John',
lastName: 'Doe',
phone: '+1-555-0101',
email: '[email protected]',
},
],
generalPractitionerId: 'prac_abc123',
photo: {
url: 'https://cdn.example.com/patients/jane.jpg',
contentType: 'image/jpeg',
},
});
include option uses FHIR _revinclude to fetch related resources in a single call:
const { data } = await clinik.patients.read(patient.id!, {
include: ['Encounter', 'Observation', 'MedicationRequest', 'Appointment'],
});
// Destructured response
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:
| 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 |
Update a Patient
Updates use JSON Patch under the hood — only send the fields you want to change:
const { data: updated } = await clinik.patients.update(patient.id!, {
phone: '+1-555-0200',
address: {
line: ['456 Oak Ave'],
city: 'Dallas',
state: 'TX',
postalCode: '75201',
},
});
Search Patients
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"
}
// Pagination
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 |
Delete a Patient
await clinik.patients.delete(patient.id!);
Deleting a patient does not cascade to related resources. Delete dependent resources first if needed.
