Records API

Ingest documents

Submit scanned pages for processing. The endpoint returns a job ID immediately; the actual extraction happens asynchronously.

Endpoint#

POST/v1/ingest/documents

Multipart upload, one or more files per request. The same endpoint accepts uploads from the Pierflow capture app and from your own server-to-server integration.

http

POST /v1/ingest/documents
Authorization: Bearer pf_live_sk_...
Content-Type: multipart/form-data

file[]            — one or more PDF, TIFF, JPEG, PNG, or WEBP files (≤50 MB each)
organization_id   — required. The organization the records belong to.
batch_label       — optional. Human label (e.g. "Ward A — June").
record_type_hint  — optional. AUTO (default) | OUTPATIENT_CARD | LAB_RESULT
                    | PRESCRIPTION | ANTENATAL | IMMUNISATION | DISCHARGE_SUMMARY
                    | REGISTRATION | OTHER
priority          — optional. NORMAL (default) | URGENT
operator_id       — optional. ID of the staff member submitting the batch.

Response · 202 Accepted

json

{
  "status": "accepted",
  "batch_id": "btch_9f3a1c82d4e74b2a",
  "jobs": [
    {
      "job_id": "job_a1b2c3d4e5f6",
      "filename": "ward_a_003.pdf",
      "pages": 4,
      "status": "queued"
    }
  ]
}

Document types#

Pierflow auto-classifies pages by default. Pass a record_type_hint when you already know what's in the batch — it improves accuracy and speeds up processing.

OUTPATIENT_CARD

document

General clinical visit record

REGISTRATION

document

Patient registration sheet — demographics, blood group, allergies

LAB_RESULT

document

Haematology, biochemistry, microbiology, pathology results

PRESCRIPTION

document

Drug orders, dosages, instructions

ANTENATAL

document

Maternal health visit records

IMMUNISATION

document

Vaccination history

DISCHARGE_SUMMARY

document

Inpatient discharge notes

Job lifecycle#

A job moves through a small set of states. Poll GET /v1/jobs/:id to track progress, or wait for the records to appear in the corresponding organization's patient list.

Status	Meaning
QUEUED	Accepted, waiting in the processing queue
PROCESSING	Pages are being extracted
AWAITING_REVIEW	Extraction complete, but one or more records need human review
VALIDATED	All records approved, ready to be included in the next Import Package
IMPORTED	Records have been delivered to and acknowledged by a partner
FAILED	Processing failed — see error_code for the reason

Idempotency

Always pass an Idempotency-Key header on uploads. A retry with the same key returns the original batch_id without creating duplicate jobs.