Skip to main content
The clinik.patients namespace provides methods to manage FHIR Patient resources. Patients are the central resource in ClinikAPI — most other resources such as encounters, observations, and prescriptions reference a patient by ID. The read method supports an include option that lets you fetch related resources in a single round-trip.

​
create

Create a new Patient resource. Only firstName and lastName are required; all other fields are optional. 
const { data, meta } = await clinik.patients.create(request: PatientCreateRequest): Promise<ApiResponse<Patient>>
​
firstName
string
required
Patient’s first (given) name.
​
lastName
string
required
Patient’s family name.
​
email
string
Email address.
​
phone
string
Phone number.
​
gender
'male' | 'female' | 'other' | 'unknown'
Administrative gender.
​
birthDate
string
Date of birth in YYYY-MM-DD format.
​
address
object
Address object with line, city, state, postalCode, and country fields.

​
Example

const { data: patient, meta } = await clinik.patients.create({
  firstName: 'Jane',
  lastName: 'Doe',
  email: '[email protected]',
  gender: 'female',
  birthDate: '1990-03-15',
  address: {
    line: ['123 Main St'],
    city: 'Austin',
    state: 'TX',
    postalCode: '78701',
    country: 'US',
  },
});

console.log('Patient ID:', patient.id);
console.log('Request ID:', meta.requestId);

​
read

Fetch a single Patient by ID. Use the include option to retrieve related FHIR resources in the same call. 
const { data, meta } = await clinik.patients.read(id: string, options?: ReadOptions): Promise<ApiResponse<PatientReadResponse>>
​
id
string
required
The patient ID (e.g. pt_abc123).
​
include
string[]
An array of related resource types to include in the response. Supported values: Encounter, Observation, MedicationRequest, and other FHIR resource types linked to the patient.
When you pass include, the response’s data object contains the patient alongside arrays of the requested related resources. 
const { data } = await clinik.patients.read('pt_abc123', {
  include: ['Encounter', 'Observation', 'MedicationRequest'],
});

data.patient;       // Patient
data.encounters;    // Encounter[]
data.observations;  // Observation[]
data.prescriptions; // MedicationRequest[]
Using include avoids multiple sequential requests. Prefer it when you need to display a full patient summary on page load.

​
update

Partially update an existing patient. Send only the fields you want to change — the SDK applies a JSON Patch internally, so unspecified fields remain unchanged. 
const { data, meta } = await clinik.patients.update(id: string, request: PatientUpdateRequest): Promise<ApiResponse<Patient>>
​
id
string
required
The patient ID to update.

​
Example

const { data: updated } = await clinik.patients.update('pt_abc123', {
  phone: '+15125550100',
  address: {
    line: ['456 Oak Ave'],
    city: 'Austin',
    state: 'TX',
    postalCode: '78702',
    country: 'US',
  },
});

​
delete

Permanently delete a patient record. 
const { data, meta } = await clinik.patients.delete(id: string): Promise<ApiResponse<void>>
Deleting a patient does not automatically delete linked resources such as encounters or observations. Remove dependent records first if your compliance requirements demand full erasure.
Search for patients with optional filters and cursor-based pagination. Omit params entirely to return the first page of all patients. 
const { data, meta } = await clinik.patients.search(params?: PatientSearchParams): Promise<ApiResponse<PaginatedResponse<Patient>>>
​
name
string
Partial name match across first and last name.
​
email
string
Exact email address match.
​
phone
string
Exact phone number match.
​
birthDate
string
Filter by date of birth (YYYY-MM-DD).
​
gender
string
Filter by administrative gender.
​
active
boolean
Filter by active status.
​
count
number
Number of results per page. Maximum is 100.
​
cursor
string
Opaque pagination cursor from the previous response. Pass data.nextCursor to fetch the next page.

​
Example

const { data: results } = await clinik.patients.search({
  name: 'Doe',
  active: true,
  count: 20,
});

console.log('Found:', results.data.length, 'patients');
console.log('Next cursor:', results.nextCursor);

// Fetch next page
if (results.nextCursor) {
  const { data: page2 } = await clinik.patients.search({
    name: 'Doe',
    active: true,
    count: 20,
    cursor: results.nextCursor,
  });
}