Encounters API
Use the Encounters API to create chart encounters from external scheduling, billing, or clinical systems.
Overview
Send patient, provider, and encounter fields together so EMRDesk can create a usable chart record and preserve the source context.
Available data fields
These fields can be mapped from partner payloads into the /encounters endpoint.
- Patient fields
- firstName: Patient given name.
- lastName: Patient family name.
- dob: Date of birth in ISO or clinic-supported date format.
- gender: Administrative gender value supplied by the source system.
- address1: Primary street address.
- city: City for the patient address.
- state: State or region for the patient address.
- zip: Postal code for the patient address.
- memberId: Insurance member identifier when available.
- payerName: Primary payer name when available.
- Encounter fields
- dateOfService: Date the service occurred.
- reasonForVisit: Visit reason or chief concern.
- service: Service label or appointment type.
- encounterType: Encounter type such as in-person, telehealth, or emergency.
- controlNumber: Partner control number for reconciliation.
- notes: Source note text or encounter summary.
- billingCodes: Procedure or charge lines associated with the encounter.
- name: Display name for the code line.
- code: Procedure or billing code.
- diagnosisCode: Linked diagnosis code or code list.
- billAmount: Line charge amount.
- Provider fields
- organizationName: Rendering or billing organization name.
- npi: Provider or organization NPI.
- providerFirstName: Provider given name.
- providerLastName: Provider family name.
- address1: Provider street address.
- city: Provider city.
- state: Provider state or region.
- zip: Provider postal code.
Defining custom mappings
Custom mappings let a partner payload use its own field names while EMRDesk receives consistent chart fields.
- Create a mapping profile for the partner source.
- Map each source path to the matching patient, encounter, provider, or billing field.
{
"patient": {
"firstName": "patient.firstName",
"lastName": "patient.lastName",
"dob": "patient.dob",
"gender": "patient.gender"
},
"encounter": {
"dateOfService": "encounter.dateOfService",
"reasonForVisit": "encounter.reasonForVisit",
"notes": "encounter.notes"
},
"provider": {
"organizationName": "provider.organizationName",
"npi": "provider.npi",
"providerName": "provider.providerFirstName + ' ' + provider.providerLastName"
}
}
- Send a test payload and confirm the normalized response before enabling production traffic.
Testing custom mappings
Use a non-production payload to verify that required patient, encounter, and provider fields normalize correctly.
{
"patient": {
"firstName": "John",
"lastName": "Doe",
"dob": "1980-01-01",
"gender": "M",
"address1": "123 Main St",
"city": "Seattle",
"state": "WA",
"zip": "98101"
},
"encounter": {
"dateOfService": "2025-01-10",
"reasonForVisit": "Routine checkup",
"notes": "Patient in good health."
},
"provider": {
"organizationName": "Health Clinic",
"npi": "1234567890",
"providerFirstName": "Jane",
"providerLastName": "Smith"
}
}
Expected response
The response returns normalized objects that reflect the applied mapping profile.
{
"patient": {
"firstName": "John",
"lastName": "Doe",
"dob": "1980-01-01",
"gender": "M",
"age": 45,
"address1": "123 Main St",
"city": "Seattle",
"state": "WA",
"zip": "98101",
"memberId": "1019971233",
"payerName": "Aetna"
},
"encounter": {
"dateOfService": "2025-01-10",
"reasonForVisit": "Routine checkup",
"notes": "Patient in good health."
},
"provider": {
"organizationName": "Health Clinic",
"npi": "1234567890",
"providerName": "Jane Smith"
}
}