Records API

Patients

Patients are the entities the Records API ultimately produces. Each has demographic data, one or more identifiers, and a FHIR R4 bundle holding their clinical history.

List patients for an organization#

GET/v1/organizations/:id/patients

Query parameter	Description
status	VALIDATED \| IMPORTED \| ALL (default VALIDATED)
updated_since	ISO-8601 timestamp — incremental sync cursor
search	Fuzzy match on name or MRN
page / per_page	Pagination (default 1 / 100)

200 OK

json

{
  "patients": [
    {
      "patient_id": "pat_b3f9c21a",
      "mrn": "LGC-00438",
      "full_name": "Adaeze Nwosu",
      "date_of_birth": "1985-03-14",
      "sex": "F",
      "record_count": 7,
      "visit_count": 12,
      "earliest_visit": "2019-01-10",
      "latest_visit": "2025-11-03",
      "validation_status": "VALIDATED",
      "fhir_url": "/v1/organizations/org_lagos_general_clinic/patients/pat_b3f9c21a/fhir"
    }
  ],
  "pagination": { "total": 11203, "page": 1, "per_page": 100 }
}

Patient FHIR bundle#

GET/v1/organizations/:id/patients/:patient_id/fhir

Returns a FHIR R4 Bundle with every resource we've extracted for that patient. You can import this directly into any FHIR-aware system.

Query parameter	Description
include	Comma-separated resource types to include (default: all)
date_from / date_to	Filter visits by date range

200 OK (abbreviated)

json

{
  "resourceType": "Bundle",
  "type": "collection",
  "total": 34,
  "entry": [
    {
      "fullUrl": "Patient/pat_b3f9c21a",
      "resource": {
        "resourceType": "Patient",
        "id": "pat_b3f9c21a",
        "identifier": [
          { "system": "https://pierflow.com/mrn", "value": "LGC-00438" }
        ],
        "name": [{ "use": "official", "text": "Adaeze Nwosu" }],
        "gender": "female",
        "birthDate": "1985-03-14"
      }
    },
    { "fullUrl": "Encounter/enc_001", "resource": { "resourceType": "Encounter", "...": "..." } },
    { "fullUrl": "Observation/obs_bp_001", "resource": { "resourceType": "Observation", "...": "..." } },
    { "fullUrl": "Condition/cond_001", "resource": { "resourceType": "Condition", "...": "..." } },
    { "fullUrl": "MedicationRequest/med_001", "resource": { "resourceType": "MedicationRequest", "...": "..." } }
  ]
}

Identifiers#

Pierflow stores identifiers as a list of typed values so you're not stuck with a single field. Each entry has a stable system URI and a value.

System	Description
https://pierflow.com/mrn	Medical Record Number assigned by the organization
https://pierflow.com/bvn	Bank Verification Number (Nigeria)
https://pierflow.com/nin	National Identification Number (Nigeria)
https://pierflow.com/nhis	NHIS / scheme enrolment number
https://pierflow.com/hmo-card	HMO / insurer card number

Why this matters

A patient may appear in multiple systems under different IDs. By keeping identifiers as typed values, you can match a Pierflow patient to your own internal record without renegotiating a primary key.

Possible duplicates

When Pierflow suspects two patients are the same person but confidence is below the auto-merge threshold, you'll see a possible_duplicate_of field on the patient. Resolution happens in the Pierflow review portal.