Records API

Import packages

An Import Package is a single ZIP containing every newly validated patient bundle for an organization since your last import. It's the recommended way to ingest at scale.

Why packages#

Polling per patient works, but it's slow and bandwidth-heavy. Pierflow assembles validated records into Import Packages — one ZIP per organization per build cycle — so your importer pulls one file and ingests everything in it.

Listing packages#

GET/v1/organizations/:id/import-packages?status=READY

200 OK

json

{
  "packages": [
    {
      "package_id": "pkg_c7d8e9f0",
      "organization_id": "org_lagos_general_clinic",
      "created_at": "2026-06-01T10:00:00Z",
      "status": "READY",
      "patient_count": 247,
      "record_count": 1834,
      "download_url": "/v1/import-packages/pkg_c7d8e9f0/download",
      "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "expires_at": "2026-06-08T10:00:00Z"
    }
  ]
}

Downloading#

GET/v1/import-packages/:package_id/download

Returns a ZIP with a manifest and one FHIR R4 Bundle per patient.

ZIP contents

text

manifest.json          — package metadata + record index
patients/
  pat_b3f9c21a.json    — FHIR R4 Bundle
  pat_c4d5e6f7.json
  ...
checksum.sha256        — SHA-256 of every file in the package

Acknowledging#

POST/v1/import-packages/:package_id/acknowledge

After your importer finishes, send an acknowledgement so Pierflow can mark the records as IMPORTED. Include the patients you couldn't import and the reasons — they'll be rebuilt into the next package.

request

json

{
  "imported_patient_count": 245,
  "failed_patient_ids": ["pat_x1y2z3", "pat_a4b5c6"],
  "failure_reasons": {
    "pat_x1y2z3": "DUPLICATE_HOSPITAL_NUMBER",
    "pat_a4b5c6": "MISSING_REQUIRED_FIELD"
  },
  "imported_at": "2026-06-01T11:23:00Z",
  "partner_import_reference": "YOUR-IMPORT-REF-00047"
}

Package retention

Packages expire 7 days after creation. Build your importer to pull and acknowledge on a daily cadence at minimum.