A protected health information (PHI) annotator implements several endpoints that take as input a clinical note and outputs a list of predicted PHI annotations found in the clinical note. This OpenAPI document describes the specification of the NLP Sandbox PHI Annotator API. This specification includes the schemas of the input and output data, and the requirements that this annotator must meet if you want to benchmark its performance on nlpsandbox.io.
The GitHub repository nlpsandbox/phi-annotator-example provides an example implementation of the NLP Sandbox PHI Annotator API in Python-Flask. By the end of the tutorial available in the README, you will have built a Docker image for this NLP Sandbox tool. You will then be able to submit this image to nlpsandbox.io to benchmark its performance.
Your NLP Sandbox tool must meet the following requirements before evaluating its performance on nlpsandbox.io.
The endpoint
/must redirect to/api/v1/tool.The endpoint
/uimust redirect to the Swagger User Interface (UI).The output of this tool must be reproducible: a given input should always generate the same output.
To ensure the results are reproducible and robust, and the data are secured, this tool must not connect to any remote server. When benchmarked on nlpsandbox.io, this tool will not be able to connect to remote servers.
Annotate contact information in a clinical note
Return the contact annotations found in a clinical note
Request Body schema: application/json
required | object (Note) A clinical note |
Responses
Request samples
- Payload
{- "note": {
- "identifier": "awesome-note",
- "text": "On 12/26/2020, Ms. Chloe Price met with Dr. Prescott in Seattle. Her phone number is 203-555-4545.\n",
- "type": "loinc:LP29684-5",
- "patientId": "awesome-patient"
}
}Response samples
- 200
- 400
- 500
{- "textContactAnnotations": [
- {
- "start": 42,
- "length": 11,
- "text": "dave@uw.edu",
- "contactType": "email",
- "confidence": 95.5
}
]
}Annotate dates in a clinical note
Return the date annotations found in a clinical note
Request Body schema: application/json
required | object (Note) A clinical note |
Responses
Request samples
- Payload
{- "note": {
- "identifier": "awesome-note",
- "text": "On 12/26/2020, Ms. Chloe Price met with Dr. Prescott in Seattle.",
- "type": "loinc:LP29684-5",
- "patientId": "awesome-patient"
}
}Response samples
- 200
- 400
- 500
{- "textDateAnnotations": [
- {
- "start": 42,
- "length": 10,
- "text": "10/26/2020",
- "dateFormat": "MM/DD/YYYY",
- "confidence": 95.5
}
]
}Annotate IDs in a clinical note
Return the ID annotations found in a clinical note
Request Body schema: application/json
required | object (Note) A clinical note |
Responses
Request samples
- Payload
{- "note": {
- "identifier": "awesome-note",
- "text": "On 12/26/2020, Ms. Chloe Price met with Dr. Prescott in Seattle. Her SSN is 123-45-6789.\n",
- "type": "loinc:LP29684-5",
- "patientId": "awesome-patient"
}
}Response samples
- 200
- 400
- 500
{- "textIdAnnotations": [
- {
- "start": 42,
- "length": 11,
- "text": "203-11-4535",
- "idType": "ssn",
- "confidence": 95.5
}
]
}Annotate person names in a clinical note
Return the person name annotations found in a clinical note
Request Body schema: application/json
required | object (Note) A clinical note |
Responses
Request samples
- Payload
{- "note": {
- "identifier": "awesome-note",
- "text": "On 12/26/2020, Ms. Chloe Price met with Dr. Prescott in Seattle.",
- "type": "loinc:LP29684-5",
- "patientId": "awesome-patient"
}
}Response samples
- 200
- 400
- 500
{- "textPersonNameAnnotations": [
- {
- "start": 42,
- "length": 11,
- "text": "Chloe Price",
- "confidence": 95.5
}
]
}Annotate locations in a clinical note
Return the location annotations found in a clinical note
Request Body schema: application/json
required | object (Note) A clinical note |
Responses
Request samples
- Payload
{- "note": {
- "identifier": "awesome-note",
- "text": "On 12/26/2020, Ms. Chloe Price met with Dr. Prescott in Seattle.",
- "type": "loinc:LP29684-5",
- "patientId": "awesome-patient"
}
}Response samples
- 200
- 400
- 500
{- "textLocationAnnotations": [
- {
- "start": 42,
- "length": 7,
- "text": "Seattle",
- "locationType": "city",
- "confidence": 95.5
}
]
}Response samples
- 200
- 404
- 500
{- "name": "awesome-nlp-tool",
- "version": "1.0.6",
- "license": "apache-2.0",
- "repository": "github:awesome-org/awesome-nlp-tool",
- "description": "An awesome NLP Tool that takes as input X and outputs Y.",
- "author": "Awesome Team",
- "authorEmail": "author@example.com",
- "type": "nlpsandbox:date-annotator",
- "apiVersion": "1.2.0"
}Response samples
- 200
- 404
- 500
{- "tools": [
- {
- "name": "awesome-nlp-tool",
- "version": "1.0.6",
- "license": "apache-2.0",
- "repository": "github:awesome-org/awesome-nlp-tool",
- "description": "An awesome NLP Tool that takes as input X and outputs Y.",
- "author": "Awesome Team",
- "authorEmail": "author@example.com",
- "type": "nlpsandbox:date-annotator",
- "apiVersion": "1.2.0"
}
]
}