API docs by Redocly

Record Linker (25.3.0)

Download OpenAPI specification:

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"
}

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-Input)

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
{
  • "prediction": "match",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2"
}

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 FHIR bundle with updated references to existing patients.

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
{
  • "prediction": "match",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "updated_bundle": { }
}

Match Record

Similar to the /link endpoint, but does not save the incoming data.

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

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
{
  • "prediction": "match",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ]
}

Match FHIR

Similar to the /link/fhir endpoint, but does not save the incoming data.

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
{
  • "prediction": "match",
  • "person_reference_id": "8e5a91ce-4436-4673-9cc9-9835a59dfb92",
  • "results": [
    ],
  • "updated_bundle": { }
}

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": [
    ]
}

mpi

Create a new Person cluster

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

Request Body schema: application/json
required
patients
required
Array of strings <uuid> (Patients) non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

Assign Patients to existing Person

Assign the Patients to an existing Person cluster.

path Parameters
person_reference_id
required
string <uuid> (Person Reference Id)
Request Body schema: application/json
required
patients
required
Array of strings <uuid> (Patients) non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

Retrieve a person cluster

Retrieve an existing person cluster in the MPI

path Parameters
person_reference_id
required
string <uuid> (Person Reference Id)

Responses

Response samples

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

Delete an empty Person

Delete an empty Person from the MPI database.

path Parameters
person_reference_id
required
string <uuid> (Person Reference Id)

Responses

Response samples

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

Retrieve orphaned persons

Retrieve person_reference_id(s) for all Persons that are not linked to any Patients.

query Parameters
Limit (integer) or Limit (null) (Limit)
Default: 50
Cursor (string) or Cursor (null) (Cursor)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {}
}

Merge Person clusters

Merges Person cluster(s) into the Person cluster referenced by merge_into_id. Optionally delete the merged Person clusters.

path Parameters
merge_into_id
required
string <uuid> (Merge Into Id)
query Parameters
delete_person_clusters
boolean (Delete Person Clusters)
Default: false
Request Body schema: application/json
required
person_reference_ids
required
Array of strings <uuid> (Person Reference Ids) non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

Create a patient record and link to an existing person

Create a new patient record in the MPI and link to an existing person.

Request Body schema: application/json
required
person_reference_id
required
string <uuid> (Person Reference Id)
required
object (PIIRecord-Input)

The schema for a PII record.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "external_patient_id": "string"
}

Retrieve orphaned patients

Retrieve patient_reference_id(s) for all Patients that are not linked to a Person.

query Parameters
Limit (integer) or Limit (null) (Limit)
Default: 50
Cursor (string) or Cursor (null) (Cursor)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {}
}

Retrieve a patient record

Retrieve an existing patient record in the MPI

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",
  • "record": {
    },
  • "external_patient_id": "string",
  • "external_person_id": "string"
}

Update a patient record

Update an existing patient record in the MPI

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "patient_reference_id": "266c775e-4b03-489b-b290-03181bfdfea2",
  • "external_patient_id": "string"
}

Delete a Patient

Delete a Patient from the mpi database.

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

Responses

Response samples

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

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