API docs by Redocly

Record Linker (24.2.1)

Download OpenAPI specification:Download

URL: https://github.com/CDCgov/RecordLinker License: Apache 2.0

Health Check

Check the status of this service and its connection to the database.

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

algorithm

List Algorithms

List all algorithms from the MPI database.

:returns: list of all algorithms

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Algorithm

Create a new algorithm in the MPI database.

:param data: The algorithm data :returns: The created algorithm

Request Body schema: application/json
required
label
required
string (Label) ^[a-z0-9]+(?:-[a-z0-9]+)*$
Description (string) or Description (null) (Description)
is_default
boolean (Is Default)
Default: false
include_multiple_matches
boolean (Include Multiple Matches)
Default: true
required
Array of items (Belongingness Ratio) = 2 items
required
Array of objects (Passes)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "is_default": false,
  • "include_multiple_matches": true,
  • "belongingness_ratio": [
    ],
  • "passes": [
    ]
}

Response samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "is_default": false,
  • "include_multiple_matches": true,
  • "belongingness_ratio": [
    ],
  • "passes": [
    ]
}

Get Algorithm

Get an algorithm by its label from the MPI database.

:param label: The algorithm label :returns: algorithm

path Parameters
label
required
string (Label)

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "is_default": false,
  • "include_multiple_matches": true,
  • "belongingness_ratio": [
    ],
  • "passes": [
    ]
}

Update Algorithm

Update an existing algorithm in the MPI database.

:param label: The algorithm label :param data: The algorithm data :returns: The updated algorithm

path Parameters
label
required
string (Label)
Request Body schema: application/json
required
label
required
string (Label) ^[a-z0-9]+(?:-[a-z0-9]+)*$
Description (string) or Description (null) (Description)
is_default
boolean (Is Default)
Default: false
include_multiple_matches
boolean (Include Multiple Matches)
Default: true
required
Array of items (Belongingness Ratio) = 2 items
required
Array of objects (Passes)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "is_default": false,
  • "include_multiple_matches": true,
  • "belongingness_ratio": [
    ],
  • "passes": [
    ]
}

Response samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "is_default": false,
  • "include_multiple_matches": true,
  • "belongingness_ratio": [
    ],
  • "passes": [
    ]
}

Delete Algorithm

Delete an algorithm from the MPI database.

:param label: The algorithm label

path Parameters
label
required
string (Label)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Link Record

Compare a PII Record with records in the Master Patient Index (MPI) to check for matches with existing patient records If matches are found, returns the patient and person reference id's

Request Body schema: application/json
required
required
object (PIIRecord)

A PIIRecord to be checked

Algorithm (string) or Algorithm (null) (Algorithm)

Optionally, a string that maps to an algorithm label stored in algorithm table

External Person Id (string) or External Person Id (null) (External Person Id)

The External Identifier, provided by the client, for a unique patient/person that is linked to patient(s)

Responses

Request samples

Content type
application/json
{
  • "record": {
    },
  • "algorithm": "string",
  • "external_person_id": "string"
}

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "prediction": "match"
}

Link FHIR for DIBBs

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 FHIR bundle with updated references to existing patients. This is a special endpoint that allows integration into a DIBBs pipeline, as it accepts and returns FHIR bundles.

Request Body schema: application/json
required
bundle
required
object (Bundle)

A FHIR bundle containing a patient resource to be checked for links to existing patient records

Algorithm (string) or Algorithm (null) (Algorithm)

Optionally, a string that maps to an algorithm label stored in algorithm table

External Person Id (string) or External Person Id (null) (External Person Id)

The External Identifier, provided by the client, for a unique patient/person that is linked to patient(s)

Responses

Request samples

Content type
application/json
{
  • "bundle": { },
  • "algorithm": "string",
  • "external_person_id": "string"
}

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "updated_bundle": { },
  • "prediction": "match"
}

Link FHIR

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 patient and person reference id's

Request Body schema: application/json
required
bundle
required
object (Bundle)

A FHIR bundle containing a patient resource to be checked for links to existing patient records

Algorithm (string) or Algorithm (null) (Algorithm)

Optionally, a string that maps to an algorithm label stored in algorithm table

External Person Id (string) or External Person Id (null) (External Person Id)

The External Identifier, provided by the client, for a unique patient/person that is linked to patient(s)

Responses

Request samples

Content type
application/json
{
  • "bundle": { },
  • "algorithm": "string",
  • "external_person_id": "string"
}

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "prediction": "match"
}

patient

Assign Patient to new Person

Create a new Person in the MPI database and link the Patient to them.

path Parameters
patient_reference_id
required
string <uuid> (Patient Reference Id)

Responses

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92"
}

Assign Patient to existing Person

Update the Person linked on the Patient.

path Parameters
patient_reference_id
required
string <uuid> (Patient Reference Id)
Request Body schema: application/json
required
person_reference_id
required
string <uuid> (Person Reference Id)
External Person Id (string) or External Person Id (null) (External Person Id)

Responses

Request samples

Content type
application/json
{
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "external_person_id": "string"
}

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92"
}

seed

Batch seed records

Seed a batch of records into the database. This endpoint can be used to initialize the MPI with existing Person clusters. The endpoint accepts a list of clusters, such that each cluster represents a Person and contains a list of patient records associated with that Person. This endpoint will create a new Person record for each cluster and create a new Patient records for each patient in the cluster.

The endpoint will return a list of Person objects, each containing a person_reference_id and a list of Patient objects, each containing patient_reference_ids.

NOTE: MySQL does not support bulk insert, so when using this dialect, each patient record will be inserted individually. This will be slower than using a dialect that supports bulk insert.

NOTE: The maximum number of clusters that can be seeded in a single request is 100.

Request Body schema: application/json
required
required
Array of objects (Clusters)

Responses

Request samples

Content type
application/json
{
  • "clusters": [
    ]
}

Response samples

Content type
application/json
{
  • "persons": [
    ]
}

Reset the MPI database

Reset the MPI database by deleting all Person and Patient records.

Responses