Custom API mappings
Custom API mappings translate partner-specific payloads into EMRDesk field names without changing the partner source format.
Why mappings matter
Mappings keep integrations stable when outside systems use different field names, nested structures, or combined values.
Available data fields
Use these destination fields when defining mappings for /receiveTestData, /encounters, and related intake endpoints.
- selectedProviders: Provider records attached to the incoming payload.
- id: Internal or partner provider identifier.
- firstName: Provider given name.
- lastName: Provider family name.
- organizationName: Provider organization name.
- npi: Provider NPI.
- phone: Provider phone number.
- address1: Provider street address.
- address2: Provider address line 2.
- city: Provider city.
- state: Provider state or region.
- zip: Provider postal code.
- billingCode: Procedure or charge lines in the payload.
- name: Display name for the billing line.
- code: Procedure or billing code.
- diagnosisCode: Diagnosis code linked to the billing line.
- billAmount: Line charge amount.
- dateOfService: Date the service occurred.
- encounterType: Visit or encounter type from the source system.
- patientData: Patient demographic and payer data.
- patient.firstName: Patient given name.
- patient.lastName: Patient family name.
- patient.dob: Patient date of birth.
- patient.phone: Patient phone number.
- patient.address1: Patient street address.
- patient.city: Patient city.
- patient.state: Patient state or region.
- patient.zip: Patient postal code.
- payers: Payer records attached to the patient.
- name: Payer display name.
- memberId: Member identifier for the payer.
Defining custom mappings
Define mappings as source-path to destination-field relationships.
- Choose the source fields that are stable in the partner payload.
- Map those fields into EMRDesk patient, provider, billing, and encounter targets.
{
"patientID": "patientData.patient.patientID",
"firstName": "patientData.patient.firstName",
"lastName": "patientData.patient.lastName",
"dateOfService": "dateOfService",
"encounterType": "encounterType",
"billingCodes": "billingCode",
"providerName": "selectedProviders.firstName + ' ' + selectedProviders.lastName",
"payerInfo": {
"name": "payers.name",
"memberId": "payers.memberId"
}
}
- Test with a representative payload and review the normalized response.
Testing custom mappings
The test payload should include provider, billing, encounter, patient, and payer data if the mapping uses those fields.
{
"selectedProviders": {
"id": "C40AwsBwyuCXymdaaPdi",
"firstName": "WINCHENZO",
"lastName": "GRUMPY",
"organizationName": "GRUMPYFACE ORG",
"npi": "1231231234",
"phone": "3109991123",
"address1": "123 GRUMPY ST",
"city": "MANHATTAN",
"state": "NY",
"zip": "100010000"
},
"billingCode": [
{
"name": "Sample Code",
"code": "E0570",
"diagnosisCode": ["E299"],
"billAmount": 150
}
],
"dateOfService": "2025-01-03",
"encounterType": "Emergency Room Visit",
"patientData": {
"patient": {
"firstName": "John",
"lastName": "Doe",
"dob": "01/01/1980",
"phone": "(312) 123-1231",
"address1": "123 Address",
"city": "City",
"state": "WA",
"zip": "98101"
},
"payers": {
"name": "AETNA",
"memberId": "1019971233"
}
}
}
Expected response
A successful mapping returns normalized data ready for downstream intake or encounter creation.
{
"status": "success",
"message": "Mapping applied successfully.",
"data": {
"patientID": "123-abc",
"firstName": "John",
"lastName": "Doe",
"dateOfService": "2025-01-03",
"encounterType": "Emergency Room Visit",
"billingCodes": [
{
"name": "Sample Code",
"code": "E0570",
"diagnosisCode": ["E299"],
"billAmount": 150
}
],
"providerName": "WINCHENZO GRUMPY",
"payerInfo": {
"name": "AETNA",
"memberId": "1019971233"
}
}
}