Orchestrate - Identity Lite

Identity Lite offers two client tools: an interactive web app where you can process your records with a click of a button, and a command-line tool (CLI) with a larger data limit.

Getting Your API Key

Before using either Identity Lite tool, you will need to create an account in the Developer Portal and get your personal API key.

Using the Identity Lite Web App

1. Go to the Identity Lite web app and enter your API key.
2. Upload a CSV file containing up to 15,000 records. See CSV Format for details. (If you have more records, use the CLI tool.)
3. Click “Hash File” to hash the data.
4. Review the hashed data, if desired, and click “Submit Hashed Data” to initiate the matching operation.
5. Browse the record matches or download a CSV file containing the original data with a PersonID column added.

Using the Identity Lite Command-Line Tool

The Identity Lite CLI tool runs on Docker, so you will need to install Docker Desktop and download the Identity Lite Docker Image.

You can then execute commands from the docker container using Docker syntax:

docker run -it -v “//c/Users/Path/To/Working/Folder:/app/data” careevolution/identity-lite-cli [COMMAND] [COMMAND OPTIONS]

• The -it option is required to run the command in an interactive mode with feedback.
• The -v option mounts a working folder (where the file containing the records is located) as a volume within the container.
• careevolution/identity-lite-cli is the container name.

The CLI commands are described in detail below. There are two ways to process the data:

1. submit-csv to hash the data locally and send the hashed data to the Identity API in one step.
2. hash-csv to hash the data and then submit-hashed-records to send the hashed data to the Identity API. You can use this two-step version if you wish to preview the hashed data before it’s sent to the server.

submit-csv

This command will hash the data locally and send the hashed data to the Identity API in one step.

docker run -it -v "//c/Users/Path/To/Working/Folder:/app/data"  careevolution/identity-lite-cli submit-csv -c data/records.csv -a ‘YOUR_API_KEY’

The result is saved as two separate CSV files:

hash-csv

This command will hash the data locally. Nothing is sent to the server until you use the submit-hashed-records command.

docker run -it -v "//c/Users/Path/To/Working/Folder:/app/data"  careevolution/identity-lite-cli hash-csv -c data/records.csv -a ‘YOUR_API_KEY’

The result is a JSON file (ORIGINALFILENAME.json) containing the hashed data and any permutations. The row number is used as an identifier to associate fields from each row. For example:

"Identifier": "46",    <--- Row ID
    "Fields": [
      {
        "Type": "FirstName",    <--- A field from this row
        "Hash": "6dcd4ce23d...",  <--- Hash for the original data (e.g., "John")
        "Permutations": [
          {
            "Hash": "ae4f281df5a...",   <--- Hashes for variants of the data (e.g., "john", "Jon")
            "Similarity": 1
          },
          {
            "Hash": "32096c2e0e...",
            "Similarity": 0.64
          },
          ...

submit-hashed-records

This command will submit hashed data (from the hash-csv command) to the Identity API.

docker run -it -v "//c/Users/Path/To/Working/Folder:/app/data"  careevolution/identity-lite-cli submit-hashed-records -f data/records.json -a ‘YOUR_API_KEY’

The result is saved as a CSV file (ORIGINALFILENAME_only_person_ids.csv) containing a list of person identifiers, one per row, in the same order as the rows of the original CSV.

CSV Format

All Identity Lite tools operate on a single Comma-Separated Values (CSV) file.

• One row per record.
• All columns are optional, but the more data you can provide, the better the matches will be.
• A header row is required to identify each column using the field names below. There is no required column order.
• Both the web app and CLI tool will report an error if they encounter an invalid code, format, or column header.

Available Fields

• FirstName

• MiddleName

• LastName

• MaidenName

• Gender - A HL7 administrative gender category code (i.e., male, female, other, unknown).

• Race - A HL7 race category code (e.g., 2054-5 means “Black or African American”).

• HomePhoneNumber

• CellPhoneNumber

• Email

• Dob - Date of birth in yyyy/mm/dd or yyyy-mm-dd format.

• Street - Street address.

• City

• State - Two-letter state abbreviation.

• ZipCode - Postal or Zip code.

• Mrn - A medical record number, often used by electronic medical record systems.

• Hcid - A Health Card Identifier, such as an enrollee ID on an insurance plan.

• Ssn - Either the full 9 or last 4 digits of a Social Security Number.

• MedicaidId - The Medicaid ID number.

• MedicareBeneficiaryIdentifier - The Medicare Beneficiary Identifier.