API Reference

High-level routes. All requests require x-api-key in the header.

Get an API key (request form)

To submit record requests via the secure request form, you need an org API key from the fulfilling hospital. Ask that hospital’s IT admin to add your organization in their portal, then share the key with you. Example: the hospital admin goes to their portal (e.g. portal.healthxfer.com/admin) → Requesting organizations → Add org → copy the API key.

POST/v1/share-record

Send a patient record to a destination organization. Think of it like “send SMS” in Twilio.

Request body

{
  "patientId": "string",       // Patient identifier (e.g. MRN)
  "destinationOrg": "string",  // Target org id
  "payload": {},               // FHIR Bundle, CCD, or PDF reference
  "consentToken": "string"     // Consent token for this share
}

Response

{
  "transaction_id": "string",
  "delivery_status": "accepted | pending | failed",
  "audit_log": "https://..."
}

GET/v1/record/:id

Retrieve a record by id (e.g. transaction or record id).

Response

{
  "id": "string",
  "resource": { ... },  // FHIR resource or document reference
  "status": "string"
}

POST/v1/consent

Create or update a consent token for sharing. Required before calling share-record.

Request body

{
  "patientId": "string",
  "scope": "string",    // e.g. "share-to-org:org_123"
  "expiresAt": "string" // ISO 8601
}

GET/v1/audit/:transactionId

Fetch the audit log for a given transaction. Use the link returned from share-record.

Response

{
  "transactionId": "string",
  "events": [ { "timestamp": "...", "action": "...", "actor": "..." } ]
}

Errors

Standard HTTP status codes. Body shape:

{ "error": "string", "code": "string" }

Rate limits and best practices will be documented as the API stabilizes.

See the demo →