Skip to main content

Connect Your EMR

This page walks through linking an external EMR or EHR to Elix, for a facility that keeps its record system and uses Elix for one or more services. The example throughout is a hospital that keeps its EMR and sends lab work to the Elix lab module, but the steps are the same for pharmacy, billing or maternal care.

1. Agree the scope​

Before any code, write down:

  • Which Elix modules the facility will use, and which stay in the EMR.
  • Which system owns each record. Usually the EMR owns the patient's demographics and Elix owns the results it produces. Each record should have one owner; the other system keeps a copy.
  • Which direction each flow runs: patients from the EMR to Elix, results from Elix to the EMR, or both.
  • How fresh each copy must be: seconds, minutes, or once a day.

Send this to sales@elix.ng. We confirm the modules are enabled for the facility and set up what the integration needs.

2. Get credentials​

The facility's administrator creates an integration account with a role that holds only the permissions your flows need. For the lab example:

FlowPermissions
Find patients and read the registerpatients.patients.list, patients.patients.get
Read lab results and their FHIR bundlesinvestigations.lab.list
Read encounters over FHIRencounters.fhir.encounter.read, encounters.fhir.encounter.search

Sign-in, token refresh and the facility headers are covered in Authentication.

3. Match patients​

Both systems need to agree which patient is which. Pick one identifier and use it everywhere:

  • the Elix patient id, a UUID that never changes, stored in your EMR against your own patient number; or
  • the Elix care number, which your registration staff can see on screen and on printed labels.

Store the Elix patient id once you have it. Names and dates of birth are not identifiers: two patients can share them, and they get corrected.

To find a patient by name or number:

curl 'https://api.app.elix.ng/api/v1/patients/base?search=adeyemi&purposeOfUse=TREATMENT' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-org-id: <organisation id>' -H 'x-facility-id: <facility id>'

4. Keep a copy of the register, if you need one​

If your EMR keeps its own copy of patients registered in Elix, read the patient change feed instead of polling the whole list:

curl 'https://api.app.elix.ng/api/v1/patients/base/changes?limit=500' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-org-id: <organisation id>' -H 'x-facility-id: <facility id>'
{
  "data": [ { "id": "1f0b6df2-...", "careNumber": "P-000184", "firstName": "...", "updatedAt": "2026-10-18T14:02:11.000Z" } ],
  "cursor": "eyJ0Ijoi...",
  "horizon": "2026-10-19T08:00:00.000Z",
  "hasMore": true
}
  • The first call, with no since, reads from the beginning. Each later call sends the last answer's cursor as since.
  • While hasMore is true, call again straight away. When it is false, you are up to date as of horizon; wait before the next call.
  • Changes are returned oldest first, and inactive patients are included so you can deactivate your copy too.
  • Changes from the last 30 seconds are held back until a later call, so a record still being written is never half read.
  • limit is up to 1,000, default 500.

Store the cursor after you have saved each page, not before. If your process stops part way, it resumes from the last page it saved and may see a few records twice, which is harmless if you update by id.

5. Exchange clinical data​

Choose by direction:

  • Elix to your EMR, on demand. Your EMR fetches what it needs when it needs it: the lab order as FHIR (GET .../lab/orders/<id>/clinical/fhir), or a patient's encounters (GET .../encounters/fhir/Encounter?patient=...).
  • Elix to your FHIR server, pushed. If your EMR has a FHIR server, Elix can publish an order's results to it once they are released, using the publish endpoint for that order. Give us its base address and its authentication: a bearer token, basic auth, or an API key in a header. See Publishing to a FHIR server.
  • Your system to Elix, callbacks. Where your system confirms or updates something Elix sent, it calls an Elix callback address signed with a shared secret. See Signed callbacks.

6. Map your codes​

If your EMR uses local codes for tests, units or encounter types, map them to standard codes before go-live. The facility's administrator records the mappings in Elix's terminology maps, so results leave Elix with LOINC codes and your EMR can match them to its own catalogue.

7. Test, then go live​

  1. Run the integration against a test facility that holds no real patients.
  2. Check each flow end to end: a patient registered in one system is found in the other, a released result appears where it should, a correction updates rather than duplicates.
  3. Check the failure paths: an expired token is refreshed, a 403 is logged and not retried in a loop, a network error is retried with a pause.
  4. Switch to the live facility and watch the first day's traffic.

Checklist​

  • Scope and record ownership agreed with the facility
  • Integration account created with only the permissions needed
  • Patient identifier chosen and stored on both sides
  • Change feed cursor stored after each saved page
  • Every patient read sends the right purposeOfUse
  • FHIR server address and authentication sent to Elix, if Elix pushes to you
  • Callback secret stored securely, and callbacks signed over the exact bytes sent
  • Local codes mapped
  • Tested on a test facility, including failures