Entity API
Read entity data through typed API methods
The Entity API provides typed methods for reading entity data via sdk.ehr.api. Each entity type has its own namespace with methods generated from the API catalog.
The API is by default scoped to the entity the provider currently has open — the patient (or encounter, referral, or order) in context. Call a method with no id and it reads the entity in context. Use these methods to pull the fuller record: data that is not on the EHR screen, because the page shows only what the EHR loaded into the current view. To read one you hold an id for instead, pass it — provider.getById({ providerId: order.orderingProviderId }). This form is interim; reading related entities directly from the entity you hold is planned to replace it.
Reading Entity Data
Patient
// Get full patient data
const result = await sdk.ehr.api.patient.getPatient();
if (result.success) {
const patient = result.data;
console.log('Name:', patient.demographics?.firstName, patient.demographics?.lastName);
}
// Get specific data
const problems = await sdk.ehr.api.patient.getProblems();
const insurance = await sdk.ehr.api.patient.getInsurances();Encounter
const result = await sdk.ehr.api.encounter.getEncounter();
if (result.success) {
console.log('CC:', result.data.cc);
console.log('Diagnoses:', result.data.diagnoses);
}Referral
const result = await sdk.ehr.api.referral.getReferral();Order
const result = await sdk.ehr.api.order.getOrder();Response Shape
All API methods return the same structure:
interface EntityAPIResponse<T> {
success: boolean;
data?: T;
error?: string;
}Always check result.success before accessing result.data.
Paginated Methods
Some methods (for example getAllergies) return results one page at a time behind an opaque forward cursor. They take an optional typed input and return a PaginatedResponse. The Entity API reference marks which methods are paginated.
// Request — every field optional
input?: {
cursor?: string; // forward cursor from the previous page
query?: string; // free-text search (only when the op supports it)
filters?: { /* field?: value */ }; // entity-specific filterable fields
};
// Response
interface PaginatedResponse<T> {
success: boolean;
data: T[];
pagination:
| { hasMore: true; nextCursor: string; limit: number }
| { hasMore: false; limit: number };
}Which filters keys an op accepts, and whether it supports query, are entity- and op-specific. Check the generated @vimconnect/app-sdk types for the op, or read sdk.ehr.getManifest(), to see what a given getter supports.
To page through results, pass the previous response's pagination.nextCursor back as input.cursor, and stop once pagination.hasMore is false:
let result = await sdk.ehr.api.patient.getAllergies();
const allergies = [...result.data];
while (result.pagination.hasMore) {
result = await sdk.ehr.api.patient.getAllergies({
cursor: result.pagination.nextCursor,
});
allergies.push(...result.data);
}Checking API Availability
Not all API methods are available on every EHR. Use the manifest to check:
const manifest = sdk.ehr.getManifest();
// Check if getPatient is available
const patientOps = manifest.operations?.filter(
op => op.sdkNamespace === 'patient' && op.available
);
console.log('Available patient operations:', patientOps?.map(op => op.sdkMethod));Entity Types
Every entity's full field list is auto-generated from the Default Collection — see Entity Types Reference.
Shared Types
Reusable structures (Demographics, Address, Provider, Diagnosis, …) are auto-generated too — see Shared Types Reference.
Importing Types
All entity and shared types are exported from @vimconnect/app-sdk, both as TypeScript types and matching Zod schemas (PatientSchema, DiagnosisSchema, …):
import type { Patient, Diagnosis } from '@vimconnect/app-sdk';
import { PatientSchema, DiagnosisSchema } from '@vimconnect/app-sdk';Runtime Validation with Zod
import type { Patient } from '@vimconnect/app-sdk';
import { PatientSchema } from '@vimconnect/app-sdk';
const result = await sdk.ehr.api.patient.getPatient();
// Safe parse (returns success/error)
const parsed = PatientSchema.safeParse(result.data);
if (parsed.success) {
const patient: Patient = parsed.data;
} else {
console.error('Validation failed:', parsed.error);
}
// Or throw on invalid data
const patient = PatientSchema.parse(result.data);