API reference · Developer docs · Veritas MORTAL API

Endpoint

POST https://api.mortal.onyxos.io/Patient/$match

One operation, one URL. There’s no Test-vs-Production base URL split — the Subscriber ID + bearer token route your request to the matching environment automatically.

Required headers

Header	Value
`Authorization`	`Bearer <access_token>` (see Quickstart §4)
`X-MORTAL-Subscriber-Id`	Subscriber ID from your dashboard (e.g. `sub_abcdef123456`)
`Content-Type`	`application/fhir+json`
`Accept`	`application/fhir+json` (recommended)

Request body

A FHIR Parameters resource containing the candidate Patient and matching options. Conformant to the FHIR R4 Patient-$match operation profile (see the FODDER IG for MORTAL-specific constraints).

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "name": [{"family": "DOE", "given": ["JOHN"]}],
        "gender": "male",
        "birthDate": "1955-04-22",
        "identifier": [{
          "system": "http://hl7.org/fhir/sid/us-ssn",
          "value": "999-99-9999"
        }]
      }
    },
    {"name": "onlyCertainMatches", "valueBoolean": true},
    {"name": "count", "valueInteger": 1}
  ]
}

Use synthetic identifiers (999-XX-XXXX SSNs etc.) for development. The Test environment must not receive real PHI.

Response body

A FHIR Bundle of searchset type. Each entry contains a matched Patient resource and a search.score indicating match confidence (0.0–1.0).

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [{
    "search": {"mode": "match", "score": 0.97},
    "resource": {
      "resourceType": "Patient",
      "deceasedDateTime": "2024-11-03",
      ...
    }
  }]
}

An empty bundle (total: 0) means no match was found above the confidence threshold — not that the person is alive. Read the FODDER IG’s interpretation guidance before drawing conclusions.

Error codes

Status	Meaning
`401`	Bearer token missing or expired. Re-request a token from your Entra tenant.
`403`	Subscriber ID isn’t in the allowlist for this credential’s environment, or the credential has been disabled.
`422`	Request body failed FHIR validation. The response body is an `OperationOutcome` pointing at the offending element.
`429`	Rate limit exceeded. Honour the `Retry-After` header.
`500`	MORTAL internal error. Retry with exponential backoff; if it persists, contact support with the `x-request-id` response header value.

SDKs

None yet. MORTAL exposes a single HTTP endpoint — fhirclient (Python) and HAPI FHIR (Java) work directly. We’ll publish language-specific examples here as integrations mature.