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
- Go to the Identity Lite web app and enter your API key.
- Upload a CSV file containing up to 15,000 records. See CSV Format for details. (If you have more records, use the CLI tool.)
- Click “Hash File” to hash the data.
- Review the hashed data, if desired, and click “Submit Hashed Data” to initiate the matching operation.
- Browse the record matches or download a CSV file containing the original data with a
PersonID
column added.
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:
submit-csv
to hash the data locally and send the hashed data to the Identity API in one step.
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’
Option |
Description |
-c |
File containing up to 100,000 records. See CSV Format for details. Always starts with data/ since the working folder was mounted as /app/data . |
-a |
Your Orchestrate API key. |
The result is saved as two separate CSV files:
Output |
Description |
ORIGINALFILENAME_with_person_ids.csv |
The original CSV with a PersonID column appended to each row. |
ORIGINALFILENAME_sorted_by_person_id.csv |
Same as ‘with_person_ids’, but sorted by ID to make it easier to scan for matches. |
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’
Option |
Description |
-c |
File containing up to 100,000 records. See CSV Format for details. Always starts with data/ since the working folder was mounted as /app/data . |
-a |
Your Orchestrate 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:
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’
Option |
Description |
-F |
Output file from the hash-csv command. Always starts with data/ since the working folder was mounted as /app/data . |
-a |
Your Orchestrate 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.
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.