DIBBs Record Linkage Service (1.2.11)

Download OpenAPI specification:Download

CDC Public Health Data Infrastructure: dmibuildingblocks@cdc.gov URL: https://cdcgov.github.io/phdi-site/ License: Creative Commons Zero v1.0 Universal

Getting Started with the DIBBs Record Linkage Service

Introduction

The DIBBs record linkage service offers a REST API for linking new health care messages to existing records if a connection exists.

Running the Record Linkage Service

The record linkage service can be run using Docker (or any other OCI container runtime e.g., Podman), or directly from the Python source code.

Running with Docker Compose (Recommended)

To run the record linkage service with Docker Compose follow these steps.

Confirm that you have Docker installed by running docker -v. If you do not see a response similar what is shown below, follow these instructions to install Docker.
```
❯ docker -v
Docker version 20.10.21, build baeda1f
```
Navigate to the containers/record-linkage folder and start the service by running docker compose up --build

Congratulations the record-linkage should now be running on localhost:8080!

Running with Docker

To run the record linkage service with Docker follow these steps.

Confirm that you have Docker installed by running docker -v. If you do not see a response similar to what is shown below, follow these instructions to install Docker.
```
❯ docker -v
Docker version 20.10.21, build baeda1f
```
Download a copy of the Docker image from the DIBBs repository by running docker pull ghcr.io/cdcgov/phdi/record-linkage:latest.
Run the service with docker run -p 8080:8080 record-linkage:latest.

Congratulations, the record linkage service should now be running on localhost:8080!

Running from Python Source Code

We recommend running the record linkage service from a container, but if that is not feasible for a given use case, it may also be run directly from Python using the steps below.

Ensure that both Git and Python 3.10 or higher are installed.
Clone the DIBBs repository with git clone https://github.com/CDCgov/phdi.
Navigate to /phdi/containers/record-linkage/.
Make a fresh virtual environment with python -m venv .venv.
Activate the virtual environment with source .venv/bin/activate (MacOS and Linux), venv\Scripts\activate (Windows Command Prompt), or .venv\Scripts\Activate.ps1 (Windows PowerShell).
Install all Python dependencies for the record linkage service with pip install -r requirements.txt into your virtual environment.
Run the record linkage service on localhost:8080 with python -m uvicorn app.main:app --host 0.0.0.0 --port 8080 --log-config app/log_config.yml.

Building the Docker Image

To build the Docker image for the record linkage service from source code instead of downloading it from the DIBBs repository follow these steps.

Ensure that both Git and Docker are installed.
Clone the DIBBs repository with git clone https://github.com/CDCgov/phdi.
Navigate to /phdi/containers/record-linkage/.
Run docker build -t record-linkage ..

The API

When viewing these docs from the /redoc endpoint on a running instance of the record linkage service or the DIBBs website, detailed documentation on the API will be available below.

Health Check

Check the status of this service and its connection to Master Patient Index(MPI). If an HTTP 200 status code is returned along with '{"status": "OK"}' then the record linkage service is available and running properly. The mpi_connection_status field contains a description of the connection health to the MPI database.

Responses

Response samples

Content type

application/json

{"status": "string",
"mpi_connection_status": "string"
}

Link Record

Compare a FHIR bundle with records in the Master Patient Index (MPI) to check for matches with existing patient records If matches are found, returns the bundle with updated references to existing patients.

Request Body schema: application/json

bundle required	object (Bundle) A FHIR bundle containing a patient resource to be checked for links to existing patient records
use_enhanced	boolean (Use Enhanced) Default: false Optionally, a boolean flag indicating whether to use the DIBBs enhanced algorithm (with statistical correction) for record linkage. If `False` and no optional `algo_config` is provided, the service will use the DIBBs basic algorithm. If this parameter is set to `True`, the enhanced algorithm will be used in place of any configuration supplied in `algo_config`.
algo_config	object (Algo Config) Default: {} A JSON dictionary containing the specification for a linkage algorithm, as defined in the SDK functions `read_algo_config` and `write_algo_config`. Default value uses the DIBBS in-house basic algorithm.
external_person_id	string (External Person Id) The External Identifier, provided by the client, for a unique patient/person that is linked to patient(s)

Responses

Request samples

Payload

Content type

application/json

{"bundle": { },
"use_enhanced": false,
"algo_config": { },
"external_person_id": "string"
}

Response samples

Content type

application/json

Example

Matches an existing Patient

{"found_match": true,
"updated_bundle": {"resourceType": "Bundle",
"entry": [{"resource": {"resourceType": "Patient",
"name": [{"family": "DOE",
"given": ["JANE"
]
}
],
"address": [{"line": ["1600 Pennsylvania Av NW"
],
"city": "Washington",
"state": "DC",
"postalCode": "",
"country": "USA"
}
]
}
},
{"fullUrl": "urn:uuid:{person_id}",
"resource": {"resourceType": "Person",
"id": "{person_id}",
"link": [{"target": {"reference": "Patient/{patient_id}"
}
}
]
},
"request": {"method": "PUT",
"url": "Person/{person_id}"
}
}
]
}
}