Patients

Overview

This resource establishes demographics and identifiers for an individual visiting or receiving treatment from a healthcare organization. A patient record serves as the most common base for data being exchanged since it establishes the "who" behind the data.

You can create, retrieve, update, or search patient records through our platform API, which integrates with Epic and eCW EHR systems.

Supported Integration Methods

  • FHIR R4.

  • HL7 v2.4.

API Endpoints

1. Create Patient (Consumer)

Endpoint: POST /api/patients/

Description: Creates a new patient record for authenticated consumers.

Authentication: Required (UserAuthMiddleware)

Request Headers:

Content-Type: application/json
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>

Request Body Schema:

Response Schema:

2. Create Patient (Service Provider)

Endpoint: POST /api/service-provider-patients/

Description: Creates a new patient record for service providers.

Authentication: Required (ProviderAuthMiddleware)

Request Headers:

Request Body: Same as Consumer endpoint

Response: Same as Consumer endpoint

Read Operations

1. Get Patient by ID (Consumer)

Endpoint: GET /api/patients/:patientId

Description: Retrieves a specific patient's information by their ID.

Authentication: Required (UserAuthMiddleware)

Request Headers:

Path Parameters:

  • patientId (string, required): The unique identifier of the patient

Query Parameters:

  • cdtName (string[], optional): Array of CDT names to retrieve

  • cdtRecordSize (number, optional): Number of CDT records to retrieve

  • fetchAllCdtFields (boolean, optional): Whether to fetch all CDT fields

  • ehrProxyFields (string[], optional): Array of EHR proxy fields to retrieve

Response: Same as Patient Model schema

2. Get Patient by Query Filter (Consumer)

Endpoint: GET /api/patients/

Description: Retrieves a patient record based on query parameters.

Authentication: Required (UserAuthMiddleware)

Query Parameters:

  • email (string, optional): Patient's email address

  • phone (string, optional): Patient's phone number

  • preferredExternalSystem (string, optional): Preferred external system

  • ehrProxyFields (string[], optional): Array of EHR proxy fields to retrieve

Response: Same as Patient Model schema

3. Get Patient by Query Filter (Service Provider)

Endpoint: GET /api/service-provider-patients/

Description: Retrieves a patient record based on query parameters for service providers.

Authentication: Required (ProviderAuthMiddleware)

Query Parameters:

  • email (string, optional): Patient's email address

  • phone (string, optional): Patient's phone number

  • externalId (string, optional): External system ID

  • consumerUuid (string, optional): Consumer UUID

  • populationTags (number[], optional): Array of population tag IDs

Response: Same as Patient Model schema

4. Search Patients (Service Provider)

Endpoint: GET /api/service-provider-patients/search

Description: Searches for patients with advanced filtering and pagination.

Authentication: Required (ProviderAuthMiddleware)

Query Parameters:

  • gender (string, optional): Patient gender (MALE, FEMALE, OTHER)

  • email (string, optional): Patient's email address

  • phone (string, optional): Patient's phone number

  • mobileNumber (string, optional): Patient's mobile number

  • birthDate (string, optional): Patient's birth date

  • externalId (string, optional): External system ID

  • consumerUuid (string[], optional): Array of consumer UUIDs

  • name (string, optional): Patient's name (searches first and last name)

  • pageSize (number, optional): Number of results per page

  • pageNumber (number, optional): Page number for pagination

  • sortBy (object, optional): Sort configuration

  • orderBy (string, optional): Sort order (asc, desc)

Response:

Update Operations

1. Update Patient (Consumer)

Endpoint: PUT /api/patients/:patientId

Description: Updates an existing patient's information.

Authentication: Required (UserAuthMiddleware)

Request Headers:

Path Parameters:

  • patientId (string, required): The unique identifier of the patient

Request Body: Same as PatientInputModel schema

Response: Same as Patient Model schema

2. Update Patient (Service Provider)

Endpoint: PUT /api/service-provider-patients/:patientId

Description: Updates an existing patient record for service providers.

Authentication: Required (ProviderAuthMiddleware)

Request Headers:

Path Parameters:

  • patientId (string, required): The unique identifier of the patient

Request Body: Same as PatientInputModel schema

Response: Same as Patient Model schema

Field Mappings to EHR Systems

Epic FHIR R4 Mapping

Platform Field
Epic FHIR Field
FHIR Path
Notes

firstName

name.given

Patient.name.given

First name in official name

lastName

name.family

Patient.name.family

Last name in official name

middleName

name.given

Patient.name.given

Middle name if present

gender

gender

Patient.gender

Mapped to lowercase (male/female)

birthDate

birthDate

Patient.birthDate

ISO date format (YYYY-MM-DD)

mobileNumber

telecom.value

Patient.telecom.value

Where system="phone" and use="mobile"

email

telecom.value

Patient.telecom.value

Where system="email"

addressLine1

address.line

Patient.address.line

First address line

addressLine2

address.line

Patient.address.line

Second address line

city

address.city

Patient.address.city

City name

state

address.state

Patient.address.state

State code

zipCode

address.postalCode

Patient.address.postalCode

ZIP/postal code

country

address.country

Patient.address.country

Country code

attributes.Ssn

identifier.value

Patient.identifier.value

Where system="urn:oid:2.16.840.1.113883.4.1"

Epic FHIR Example:

eCW HL7 v2.4 Mapping

Platform Field
HL7 Segment
HL7 Field
Notes

firstName

PID

PID.5.2

Patient first name

lastName

PID

PID.5.1

Patient last name

birthDate

PID

PID.7

Patient birth date

gender

PID

PID.8

Patient gender

race

PID

PID.10

Patient race (if provided)

addressLine1

PID

PID.11.1

Patient address line 1

addressLine2

PID

PID.11.2

Patient address line 2

city

PID

PID.11.3

Patient city

state

PID

PID.11.4

Patient state

zipCode

PID

PID.11.5

Patient ZIP code

homePhoneNumber

PID

PID.13.1

Home phone number

email

PID

PID.13.2

Patient email

workPhoneNumber

PID

PID.14.1

Work phone number

mobileNumber

PID

PID.14.2

Mobile phone number

language

PID

PID.15

Patient language (if provided)

ethnicity

PID

PID.22

Patient ethnicity (if provided)

facilityName

PID

PID.23.2

Facility name

facilityId

PID

PID.23.1

Facility ID

sexualOrientation

PID

PID.40

Sexual orientation (if provided)

genderIdentity

PID

PID.41

Gender identity (if provided)

Guardian Information (NK1 Segment):

Platform Field
HL7 Segment
HL7 Field
Notes

guardian.firstName

NK1

NK1.2.2

Guardian first name

guardian.lastName

NK1

NK1.2.1

Guardian last name

guardian.relationship

NK1

NK1.3

Guardian relationship

guardian.addressLine1

NK1

NK1.4.1

Guardian address line 1

guardian.addressLine2

NK1

NK1.4.2

Guardian address line 2

guardian.city

NK1

NK1.4.3

Guardian city

guardian.state

NK1

NK1.4.4

Guardian state

guardian.zipCode

NK1

NK1.4.5

Guardian ZIP code

guardian.phoneNumber

NK1

NK1.5

Guardian phone number

Insurance Information (GT1 Segment):

Platform Field
HL7 Segment
HL7 Field
Notes

insuranceDetails.guarantorFirstName

GT1

GT1.3.2

Guarantor first name

insuranceDetails.guarantorLastName

GT1

GT1.3.1

Guarantor last name

insuranceDetails.guarantorBirthDate

GT1

GT1.8

Guarantor birth date

insuranceDetails.guarantorRelationship

GT1

GT1.11

Guarantor relationship

insuranceDetails.guarantorPhoneNumber

GT1

GT1.6

Guarantor phone number

eCW HL7 Integration Notes:

  • Uses ADT^A08 message type for patient registration

  • Phone numbers are processed to remove country codes and formatting

  • Facility mapping is handled based on organization configuration

  • Guardian information is mapped to NK1 segments

  • Insurance details are mapped to GT1 segments

  • Custom field mappings can be configured per client/EHR

Read Operations with EHR Systems

Epic FHIR Read Operations

Patient Retrieval:

  • Uses GET /Patient/{id} endpoint for individual patient retrieval

  • Supports query parameters for filtering and searching

  • Returns FHIR Patient resource with all mapped fields

  • Handles pagination for search results

Search Capabilities:

  • Search by name, birth date, gender, and other demographics

  • Filter by active status and other criteria

  • Support for complex queries with multiple parameters

eCW HL7 Read Operations

Patient Retrieval:

  • Uses internal consumer service for patient data retrieval

  • Maps consumer data back to patient model format

  • Supports filtering by external ID, consumer UUID, and other criteria

  • Handles guardian and dependant relationships

Search Capabilities:

  • Search by email, phone number, and external identifiers

  • Filter by population tags and other criteria

  • Support for pagination and sorting

Update Operations with EHR Systems

Epic FHIR Update Operations

Patient Updates:

  • Uses PUT /Patient/{id} endpoint for patient updates

  • Validates and maps updated fields to FHIR format

  • Handles partial updates and field validation

  • Maintains data consistency across systems

Update Validation:

  • Validates required fields and data formats

  • Checks for duplicate records and conflicts

  • Ensures data integrity before EHR synchronization

eCW HL7 Update Operations

Patient Updates:

  • Updates consumer records in internal database

  • Validates duplicate email and mobile number checks

  • Handles guardian assignment and relationship updates

  • Maintains primary consumer status logic

Update Validation:

  • Checks for existing consumers with same email/mobile

  • Validates guardian relationships and assignments

  • Ensures data consistency before external sync

Custom Field Mappings

The platform includes a robust integration engine that supports client/EHR-level custom field mappings. The mappings shown above for Epic FHIR and eCW HL7 are examples of standard implementations. Each client can configure custom field mappings according to their specific EHR requirements and data structures.

Integration Engine Features:

  • Throttling: Automatic request throttling based on EHR system rate limits

  • Retry Logic: Intelligent retry mechanisms with exponential backoff

  • Failure Handling: Comprehensive error handling and recovery

  • Custom Mappers: Client-specific field mapping configurations

  • Real-time Monitoring: Integration status and performance monitoring

Validation Rules

Required Fields

  • For primary patients: firstName, lastName, birthDate, gender

  • For dependants: firstName, lastName, birthDate, gender, relationshipType

Field Validation

  • firstName: 2-50 characters, cannot be "null", "", or "undefined"

  • lastName: 1-50 characters, cannot be "null", "", or "undefined"

  • email: Valid email format, cannot be "null" or "undefined"

  • mobileNumber: Valid phone number format

  • gender: Must be one of: MALE, FEMALE, OTHER

Business Rules

  1. Duplicate Prevention: Email and mobile number must be unique within the organization

  2. Dependant Creation: Dependants require a parent record to exist first

  3. Authentication: Primary patients require authentication ID

  4. Guardian Assignment: Guardians can be assigned during patient creation

  5. Population Tags: Tags can be assigned based on organization configuration

Error Handling

HTTP Status Codes

  • 200 - Success

  • 400 - Bad Request (validation errors)

  • 401 - Unauthorized

  • 403 - Forbidden

  • 409 - Conflict (duplicate records)

  • 500 - Internal Server Error

Error Response Format

Common Error Codes

  • DUPLICATE_EMAIL - Email already exists

  • DUPLICATE_MOBILE - Mobile number already exists

  • PATIENT_NOT_FOUND - Patient record not found

  • INPUT_VALIDATION_ERROR - Request validation failed

  • UNAUTHORIZED - Authentication required

  • INTEGRATION_NOT_FOUND - EHR integration not configured

  • INTEGRATION_DISABLED - EHR integration disabled

Post-Creation Operations

After successful patient creation, the following operations are automatically triggered:

  1. Email Notification: Registration confirmation email sent to patient

  2. External Event: Webhook event CONSUMER_CREATED triggered

  3. Population Tag Assignment: Based on organization configuration

  4. Guardian Assignment: If guardian information provided

  5. EHR Sync: Patient data synchronized with configured EHR system

Security Considerations

  1. Authentication: All endpoints require valid JWT tokens

  2. Authorization: Organization-level access control

  3. Data Encryption: All data transmitted over HTTPS

  4. Audit Logging: All patient creation operations are logged

  5. PII Protection: Sensitive data is encrypted at rest

Examples

Basic Patient Creation

Patient with Guardian

Service Provider Patient Creation

Read Operation Examples

Get Patient by ID

Search Patients by Email

Advanced Patient Search

Update Operation Examples

Update Patient Information

Update Patient with Guardian

Integration Testing

The platform provides comprehensive integration testing through the patient creation journey collection, which includes:

  1. Consumer Lookup: Verify patient doesn't already exist

  2. Patient Creation: Create new patient record

  3. EHR Integration: Verify data sync with EHR system

  4. Validation: Confirm all fields are properly mapped

  5. Error Handling: Test various error scenarios

Support

For technical support or questions about patient creation API: : Support Email: [email protected]

PreviousSchedulingNextCrelio Health & Hubble Integration Guide

Last updated