Developers

External IDs and matching records

Match records by ID, never by name. Every object carries the IDs other systems know it by.

The external_ids field#

Clinics, practitioners, patients and appointments all carry it:

"external_ids": [
  { "source": "cliniko", "id": "100234" },
  { "source": "halaxy", "id": "PT-88412" }
]
  • Each entry is another system's ID for this record, exactly as that system gave it.
  • One record can carry several, from several systems. An empty list means none are linked.
  • Links belong to one clinic. The same patient at another clinic is another record, with its own links.
  • Treat an unknown source as just another system. New sources appear without notice.

Today the links come from the integrations a clinic connects in Claro. Writing your own, and updating or creating a record by its external ID, is coming.

Store both IDs#

Keep Claro's ID (pat_…, appt_…) on your record, beside your own. Then every later sync is an exact lookup, not a search.

Names are not identifiers. People share them, change them and spell them differently. Match in this order and stop at the first rule that applies:

Patients#

  1. An ID. Your ID in external_ids, or a pat_ ID you stored. A match.
  2. A strong pair. date_of_birth with email, or date_of_birth with mobile. A match.
  3. Name and date of birth. Suggest it to a person. Never link automatically.
  4. Nothing. Treat the patient as new.

Compare emails case-insensitively, and mobiles in one normalized format.

Practitioners#

Match on email together with a registration from registrations: an AHPRA number in Australia, an NPI in the US. Never on name alone.

Keep it reversible#

Record why you linked two records, and let a person undo it. A wrong link puts one patient's details on another's file.