FHIR file intake API

Use the FHIR file intake API to send FHIR resources into EMRDesk Files and interop review workflows.

Endpoint

POST /receiveFhirInterop

Security model

Send x-api-key with the required interop ingestion scope.

Include patientId when the destination patient is known. Otherwise, the packet is queued for matching.

Supported resources

• Bundle
• DocumentReference
• Binary
• DiagnosticReport
• Observation
• Condition
• AllergyIntolerance
• MedicationRequest
• Immunization

Request shape

{
  "patientId": "patient_12345",
  "fileName": "outside-lab-bundle.json",
  "payload": {
    "resourceType": "Bundle",
    "type": "document",
    "entry": [
      {
        "resource": {
          "resourceType": "DiagnosticReport",
          "id": "dr-100",
          "status": "final",
          "subject": { "reference": "Patient/patient_12345" }
        }
      }
    ]
  }
}

Response headers

• x-request-id is returned for tracing and can be supplied by the caller.
• x-ratelimit-limit shows the request limit for the current key.
• x-ratelimit-remaining shows requests left in the current window.
• x-ratelimit-reset shows when the current rate-limit window resets.

What the endpoint does

• Stores the raw payload for audit and troubleshooting.
• Creates a Files record with source metadata and requestId traceability.
• Extracts a readable summary from supported FHIR resources.
• Builds candidate clinical records when the payload contains structured data.
• Preserves source-system lineage for future reconciliation.

Routing behavior

• Known patient: include patientId to route directly to that chart.
• Unknown patient: include source identifiers so EMRDesk can queue the packet for patient matching.

Common errors

• 401: the API key is missing, revoked, or invalid.
• 403: the key does not include FHIR intake scope.
• 429: the partner key exceeded its configured rate limit.

For adjacent workflows, compare HL7 file intake, FHIR chart export, and OpenMRN connector intake.