API Reference

Authentication

https://{slug}.healthxfer.com

Submit a Record Request

Submit a patient record request to a facility. MRN and DOB are encrypted in the PHI vault and never stored in the database.

Headers

x-org-key: org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
x-tenant-slug: your-hospital
Content-Type: application/json

Request body

{
  "patientId":          "MRN-12345",       // required — patient MRN
  "patientDob":         "1985-03-15",      // required — YYYY-MM-DD
  "studyType":          "ct",              // required — see Study Types
  "dateRange":          "2024-01-01 to 2024-12-31", // required
  "departmentId":       "uuid",            // optional — from /api/departments
  "contactEmail":       "records@org.com", // optional — for notifications
  "deliveryPreference": "secure_portal",   // optional
  "deliveryDetails":    "portal.org.com"   // optional
}

Response 201 Created

{
  "id":      "b7fc4d3b-3519-458b-906c-8c2985ab8cad",
  "status":  "pending",
  "message": "Request received. You'll be notified when it's processed."
}

Check Request Status

Public endpoint. No auth required — just the request ID and org key.

Query params

?requestId=b7fc4d3b-3519-458b-906c-8c2985ab8cad
&orgKey=org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Response

{
  "id":          "b7fc4d3b-...",
  "status":      "pending | fulfilled | rejected | failed",
  "studyType":   "ct",
  "updatedAt":   "2026-04-16T15:42:00Z",
  "fulfilledAt": "2026-04-16T16:01:22Z"  // present when status = fulfilled
}

List Departments

Returns the departments accepting requests for a given tenant. Use this to populate the department dropdown.

Query params

?forTenantSlug=your-hospital

Response

[
  {
    "id":       "e0168662-e2c3-4d58-8fe4-db883bb33e94",
    "name":     "Radiology",
    "slug":     "radiology",
    "workflow": "automated"
  },
  {
    "id":       "a1b2c3d4-...",
    "name":     "HIM",
    "slug":     "him",
    "workflow": "manual"
  }
]

Webhooks

Configure a webhook URL in Admin → Settings. HealthXfer sends a POST to your endpoint whenever a request status changes.

Payload

{
  "requestId":    "b7fc4d3b-3519-458b-906c-8c2985ab8cad",
  "status":       "fulfilled",
  "transactionId":"tx_abc123def456",
  "fulfilledAt":  "2026-04-16T16:01:22Z",
  "failureReason": null
}

Respond with any 2xx to acknowledge. HealthXfer fires-and-forgets (no retries in v1 — coming soon).

Study Types

Use these values in the studyType field. Case-insensitive.

Errors

All errors return standard HTTP status codes with a JSON body.

{ "error": "Invalid org key" }