Fact Of Death Direct Enquiry Response Implementation Guide
0.1.0 - ci-build
Fact Of Death Direct Enquiry Response Implementation Guide
0.1.0 - ci-build
Fact Of Death Direct Enquiry Response Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
This page provides practical examples demonstrating how to use FODDER for querying deceased patient records from the Veritas Data Research Fact of Death API. All examples use the standard FHIR match-grade extension on the Bundle entry's search element and optionally include a DocumentReference containing a death record PDF.
A healthcare organization wants to verify that a patient record they have on file is actually deceased. They have the patient's Social Security Number, name, and date of birth.
Using the Patient/$match operation with basic identifiers:
POST /Patient/$match HTTP/1.1
Host: api.example.org/fhir
Content-Type: application/fhir+json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "123-45-6789"
}
],
"name": [
{
"family": "Doe",
"given": ["John"]
}
],
"birthDate": "1950-03-15",
"gender": "male"
}
}
]
}
The Veritas API confirms a certain match and includes a death record document:
{
"resourceType": "Bundle",
"id": "match-response-bundle-1",
"type": "searchset",
"timestamp": "2024-01-10T14:35:00Z",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://api.example.org/fhir/Patient/$match"
}
],
"entry": [
{
"fullUrl": "http://api.example.org/fhir/Patient/deceased-patient-001",
"resource": {
"resourceType": "Patient",
"id": "deceased-patient-001",
"meta": {
"profile": [
"https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-deceased-patient"
]
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "123-45-6789"
}
],
"name": [
{
"use": "official",
"family": "Doe",
"given": ["John"]
}
],
"birthDate": "1950-03-15",
"gender": "male",
"deceasedDateTime": "2024-01-10T14:30:00Z",
"address": [
{
"use": "home",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
]
},
"search": {
"mode": "match",
"score": 1.0,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "certain"
}
]
}
},
{
"fullUrl": "http://api.example.org/fhir/DocumentReference/death-record-001",
"resource": {
"resourceType": "DocumentReference",
"id": "death-record-001",
"meta": {
"profile": [
"https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-death-record-document-reference"
]
},
"status": "current",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "64297-5",
"display": "Death certificate"
}
]
},
"subject": {
"reference": "Patient/deceased-patient-001"
},
"date": "2024-01-10T14:35:00Z",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "http://api.example.org/fhir/Binary/death-record-001",
"title": "Fact of Death Record - John Doe",
"creation": "2024-01-10"
}
}
]
},
"search": {
"mode": "include"
}
}
]
}
certain - The record is known to be a matchA healthcare system queries for a deceased patient but receives multiple potential matches due to common names. Each result includes the standard match-grade extension.
The API returns multiple potential matches ordered by confidence score:
{
"resourceType": "Bundle",
"type": "searchset",
"timestamp": "2024-01-10T15:00:00Z",
"total": 3,
"entry": [
{
"fullUrl": "http://api.example.org/fhir/Patient/deceased-patient-002",
"resource": {
"resourceType": "Patient",
"id": "deceased-patient-002",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "987-65-4321"
}
],
"name": [
{
"family": "Smith",
"given": ["John", "Michael"]
}
],
"birthDate": "1960-01-01",
"gender": "male",
"deceasedDateTime": "2023-06-15T09:45:00Z"
},
"search": {
"mode": "match",
"score": 0.85,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "probable"
}
]
}
},
{
"fullUrl": "http://api.example.org/fhir/Patient/deceased-patient-003",
"resource": {
"resourceType": "Patient",
"id": "deceased-patient-003",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "555-55-5555"
}
],
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"birthDate": "1960-02-14",
"gender": "male",
"deceasedDateTime": "2022-12-31T23:59:00Z"
},
"search": {
"mode": "match",
"score": 0.65,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "possible"
}
]
}
},
{
"fullUrl": "http://api.example.org/fhir/Patient/deceased-patient-004",
"resource": {
"resourceType": "Patient",
"id": "deceased-patient-004",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-ssn",
"value": "111-11-1111"
}
],
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"birthDate": "1959-12-25",
"gender": "male",
"deceasedDateTime": "2021-03-20T10:15:00Z"
},
"search": {
"mode": "match",
"score": 0.45,
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/match-grade",
"valueCode": "possible"
}
]
}
}
]
}
probable): Michael John Smith born 1960-01-01 - Most likely candidatepossible): John Smith born 1960-02-14 - Close match on name and yearpossible): John Smith born 1959-12-25 - Low confidence, different birth yearA healthcare system queries for a patient who is not in the Veritas death records database.
{
"resourceType": "Bundle",
"type": "searchset",
"timestamp": "2024-01-10T15:15:00Z",
"total": 0,
"entry": []
}
A client attempts to query FODDER without a valid access token.
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "security",
"diagnostics": "Missing or invalid authentication credentials"
}
]
}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="FODDER API", error="invalid_token"
Authorization: Bearer <token>total field and iterate through all entriesmatch-grade extension value (certain, probable, possible) to assess result qualitysearch.mode = "include" for optional death record PDFsFor transient errors (429, 503):