PHI-IDENTIFICATION-API

Introduction

Shaip's PHI Entity Recognition API uses advanced NLP to detect Protected Health Information (PHI) in medical texts and EHRs, ensuring data accuracy and regulatory compliance. It aligns with the Safe Harbour guidelines, promoting patient data security in line with HIPAA. Rather than erasing data, the API identifies and classifies PHI, allowing healthcare organizations flexibility in data anonymization, be it through placeholders or dummy information.

Authentication

The PHI Entity Recognition API requires authentication using an API key to ensure secure access and prevent unauthorized usage. When making requests to the API, you must include the API key in the request headers. The x-api-key header should contain your unique API key, which will be provided to you upon registration and subscription to the API service.

Please ensure that you keep your API key confidential and do not share it in publicly accessible areas, such as client-side code, version control repositories, or public forums. The API key grants access to your account and holds the necessary privileges to interact with the PHI Entity Recognition API.

To authenticate your API requests, include the x-api-key header in each POST request as shown in the example curl request above. This way, our server can verify your credentials and provide access to the PHI Entity Recognition service.

PHI Entity Recognition API Endpoint:

URL: https://haiapi.shaip.com/phi-predict
Method: POST
Headers:
Content-Type: "application/json"
x-api-key:"wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1"

By including the appropriate authentication details and headers with each API call, you can confidently access the PHI Entity Recognition API and utilize its sophisticated capabilities to handle PHI in a secure and compliant manner. Rest assured that our authentication process is designed to protect sensitive healthcare data and ensure that only authorized users can access this critical functionality.

CURL

1curl -X POST "https://haiapi.shaip.com/phi-predict" 
2-H "Content-Type: application/json" 
3-H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1" 
4-d '{
5"data": "{YOUR_UNSTRUCTURED_TEXT}"
6}'
7

API Request

Request Parameter

To interact with the PHI Entity Recognition API, you need to make a POST request to the designated endpoint. Please refer the structure of the API request along with the required fields:

data (String, Required): This field is mandatory and must contain the actual content string of the medical document that requires entity and relationship extraction from unstructured data.

Example Request Explanation:

In this example, we perform a POST request to the API endpoint https://haiapi.shaip.com/phi-predict. The request is made with the necessary headers, including "Content-Type" as "application/json" and the "x-api-key" for authentication.

The request body contains a JSON object with the "data" field, which is essential for the API to extract entities and relationships from unstructured data. The value of the "data" field is the actual medical text that requires analysis and extraction. Please replace the sample data with the specific medical content you wish to process.

Ensure that you follow the proper API guidelines and provide valid JSON data within the "data" field to receive accurate unstructured data extraction results.

CURL

JAVA

Python

NodeJS

Ruby

PHP

.NET(C#)

1curl -X POST "https://haiapi.shaip.com/entity-relationship"
2-H "Content-Type: application/json"
3-H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1"
4-d "{
5"data": """
6DATE OF VISIT: May 25, 2017
7
8DATE OF BIRTH: July 23, 1937
9
10REASONS FOR VISIT:
11
121. Elevated CEA with history of colon cancer: CT scans negative, PET ordered to evaluate for occult disease. Colonoscopy pending.
13
142. Leukopenia and thrombocytopenia: Likely related to Sjogren's disease. Workup to date has been negative. Marrow on hold for now. See below for splenomegaly.
15
163. Splenomegaly: Unexplained. This could be related to rheumatologic disease, but given the increased risk of lymphoma in patients with Sjogren's syndrome, we will discuss further after the PET scan has been obtained as above.
17
184. Significant family history: Her family history is concerning, given her father with what sounds like primary central nervous system malignancy, a sister with pancreatic cancer, a sister with ovarian cancer, and a sister with breast cancer. Her sister with breast cancer is still alive and I have encouraged that her sister would be the best person to have genetic testing, but if she is unwilling or unable, then Annette should have genetic testing. I recommended referral to Burlington to see Dr. Wendy McKinnon, they were a bit resistant to that. We will discuss further at the time of next visit.
19"""
20}"

CURL

JAVA

Python

NodeJS

Ruby

PHP

.NET(C#)

1curl -X POST "https://haiapi.shaip.com/entity-relationship"
2-H "Content-Type: application/json"
3-H "x-api-key: wVxnqO9v773XDTxAnTadUa94v6eN1L4MWJDygVs1"
4-d "{
5"data": """
6DATE OF VISIT: May 25, 2017
7
8DATE OF BIRTH: July 23, 1937
9
10REASONS FOR VISIT:
11
121. Elevated CEA with history of colon cancer: CT scans negative, PET ordered to evaluate for occult disease. Colonoscopy pending.
13
142. Leukopenia and thrombocytopenia: Likely related to Sjogren's disease. Workup to date has been negative. Marrow on hold for now. See below for splenomegaly.
15
163. Splenomegaly: Unexplained. This could be related to rheumatologic disease, but given the increased risk of lymphoma in patients with Sjogren's syndrome, we will discuss further after the PET scan has been obtained as above.
17
184. Significant family history: Her family history is concerning, given her father with what sounds like primary central nervous system malignancy, a sister with pancreatic cancer, a sister with ovarian cancer, and a sister with breast cancer. Her sister with breast cancer is still alive and I have encouraged that her sister would be the best person to have genetic testing, but if she is unwilling or unable, then Annette should have genetic testing. I recommended referral to Burlington to see Dr. Wendy McKinnon, they were a bit resistant to that. We will discuss further at the time of next visit.
19"""
20}"

API Response

Response Parameter

Entity : A list of PHI entities within the provided unstructured text.

type (Enum, Required): This field contains detected entity types, which are classified into the following categories

PERSON_NAME: Represents a person’s name.
HOSPITAL_NAME: Refers to the name of a hospital or medical facility.
ORG_NAME: Represents the name of an organization or institution.
AGE: Denotes the age of the individual mentioned in the text.
DATE: Represents a specific date mentioned in the text.
LOCATION: Refers to a location or place mentioned in the text.
ROOM_NO: Represents a room number in a hospital or building.
ID: Denotes an identification number or code mentioned in the text.
TELEPHONE_NO: Represents a telephone or contact number.
EMAIL_ID: Refers to an email address mentioned in the text.
WEB_URL: Represents a web URL or website address.
SEASON: Denotes a specific season mentioned in the text.

textSpans (List<TextSpan>, Required): This field contains a list of text spans, each representing the content of a detected entity.

beginOffset (Integer, Required): This field contains the calculated beginning offset of the text span within the original unstructured text.
text (String, Required): This field contains the actual text content of the text span

Note: The API response will include information about various entities found in the input text. Each entity will have a type field indicating its category and a list of textSpans providing details about the location and content of the entity within the original text.

Response Parameter Values

Entity Type Values: We have a set of defined PHI entities that are important to de-identify the clinical document. These are stand-alone entities like person name, hospital name, date, age, etc (listed below).

Person Name
1. Patient name
2. Physician name
3. Nurse practitioner name
4. Family member name
5. Other Name
Hospital Name
1. Medical center name
2. Clinic name
3. Nursing home name
Organization
1. Company name
2. Univeristy name
3. Department name
Age
Date
1. Date pattern
2. Day
3. Month
4. Year
Location
1. Country
2. State
3. City
4. Street
5. Zip Code
6. Other Location
Room Number
1. Suite Number
2. Floor Number
ID
1. Social security number
2. Medical record number
3. Health plan beneficiary number
4. Account number
5. Certificate/License number
6. Biometric id
7. Record id
8. Accession number
9. Vehicle identification number
10. License plate number
11. Device identifiers and serial number
12. Other id
Telephone Number
1. Fax number
Email address
Web URL
Season

JSON

1{
2  "processed_output": {
3    "phiEntities": [
4      {
5        "id": 0,
6        "phiType": "date",
7        "textSpans": [
8          {
9            "beginOffset": 15,
10            "text": "May 25, 2017"
11          }
12        ]
13      },
14      {
15        "id": 1,
16        "phiType": "date",
17        "textSpans": [
18          {
19            "beginOffset": 43,
20            "text": "July 23, 1937"
21          }
22        ]
23      },
24      {
25        "id": 2,
26        "phiType": "person_name",
27        "textSpans": [
28          {
29            "beginOffset": 1008,
30            "text": "Annette"
31          }
32        ]
33      },
34      {
35        "id": 3,
36        "phiType": "location",
37        "textSpans": [
38          {
39            "beginOffset": 1071,
40            "text": "Burlington"
41          }
42        ]
43      },
44      {
45        "id": 4,
46        "phiType": "person_name",
47        "textSpans": [
48          {
49            "beginOffset": 1093,
50            "text": "Wendy McKinnon"
51          }
52        ]
53      }
54    ]
55  },
56  "requestId": 261
57}

JSON

1{
2  "processed_output": {
3    "phiEntities": [
4      {
5        "id": 0,
6        "phiType": "date",
7        "textSpans": [
8          {
9            "beginOffset": 15,
10            "text": "May 25, 2017"
11          }
12        ]
13      },
14      {
15        "id": 1,
16        "phiType": "date",
17        "textSpans": [
18          {
19            "beginOffset": 43,
20            "text": "July 23, 1937"
21          }
22        ]
23      },
24      {
25        "id": 2,
26        "phiType": "person_name",
27        "textSpans": [
28          {
29            "beginOffset": 1008,
30            "text": "Annette"
31          }
32        ]
33      },
34      {
35        "id": 3,
36        "phiType": "location",
37        "textSpans": [
38          {
39            "beginOffset": 1071,
40            "text": "Burlington"
41          }
42        ]
43      },
44      {
45        "id": 4,
46        "phiType": "person_name",
47        "textSpans": [
48          {
49            "beginOffset": 1093,
50            "text": "Wendy McKinnon"
51          }
52        ]
53      }
54    ]
55  },
56  "requestId": 261
57}

Error

When interacting with the Shaip API, you may encounter specific error codes, along with standard HTTP response statuses and corresponding error messages in the response body. Below is a table summarizing the possible error codes, along with their respective HTTP status and updated response body:

Response Code	HTTP Status	Response Body
400	Bad Request	{ "error": "The request was unacceptable, often due to missing a required parameter." }
401	Unauthorized	{ "error": "No valid API key provided." }
402	Token Expired	{ "error": "Token expired. Please contact administrator" }
403	Forbidden	{ "error": "The API key doesn't have permissions to perform the request." }
429	Trial Quota Excceded	{ "error": "Trial quota for API calls exceeded. Please upgrade your plan or try again later." }
500	Internal Server Error	{ "error": "Something went wrong on the server's end. Please try again later." }

400

401

402

403

429

500

1{
2	"error": "The request was unacceptable, often due to missing a required parameter."
3}