OpenMRN connector intake API

Use the OpenMRN connector intake API to receive migration or sync packets from OpenMRN-compatible connectors.

Endpoint

POST /receiveOpenMrnInterop

Security model

Send x-api-key with connector ingestion scope.

Required connector metadata

• sourceSystemId
• externalPatientId
• externalDocumentId or importJobId

Recommended metadata

• sourceSystemName
• syncStatus
• reconciliationStatus
• patientReference

Request example

{
  "payload": {
    "sourceSystemId": "openemr-prod",
    "sourceSystemName": "OpenEMR East Clinic",
    "externalPatientId": "EXT-PAT-991",
    "externalDocumentId": "DOC-77",
    "importJobId": "JOB-20260307-1",
    "syncStatus": "completed",
    "reconciliationStatus": "pending"
  }
}

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 connector payload and metadata.
• Creates a Files record with sourceSystemId and import metadata.
• Preserves sync and reconciliation status for review.
• Routes directly when patientId or matching identifiers are available.

Common errors

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

For clinical file payloads, compare the FHIR intake guide.