Core API

Describes Philter's core API methods.

Philter’s core API provides access to Philter’s ability to filter sensitive information from text and to retrieve the status of Philter.

The curl example commands shown on this page are written assuming Philter has been enabled for SSL. If launched from a cloud marketplace, SSL will be enabled automatically with a self-signed SSL certificate. The example commands also assume API authentication is disabled. See the Settings for more information on SSL and API authentication.

Contexts and Document IDs

Each filter request requires a context. When not provided in the request the context defaults to none. Contexts provide a means for logically grouping your documents during filtering. For example, documents pertaining to one health care provider may be submitted under the context hospital1, and documents pertaining to another health care provider may be submitted under the context hospital2.

Contexts and Consistent Anonymization

The context for each filter request impacts how sensitive information is replaced when found in the text. Consistent anonymization can be enabled at either the context or document level. When enabled at the context level, all instances of a given piece of sensitive information will be replaced consistently by the same value. This allows for maintaining meaning across all documents in the context.

Document Identifiers

Each filter request submitted to Philter is automatically assigned a document identifier. The document identifier is an alphanumeric value unique to that request. No two documents should be assigned the same document identifier. The document identifier is returned in the x-document-id header with each filter or explain API response.

When the replacements store is enabled, the document identifier can be used to retrieve information about the sensitive information identified in the text, such as the character-based start and end positions of the sensitive information, the type (phone number, SSN, etc.) of the sensitive information, and other attributes.

post
Filtering Text

https://philter:8080/api/filter
This method receives text and removes sensitive information from the text based on the specified filter profile. The text to process must be provided in the body of the request.
Request
Response
Request
Headers
Content-Type
required
string
The value should be set to text/plain.
Query Parameters
d
optional
string
A document ID that uniquely identifies the text being submitted. Leave empty and Philter will generate a document ID derived from a hash of the submitted text.
p
optional
string
The name of a filter profile to use for filtering. Defaults to default if not provided.
c
optional
string
The filtering context. Defaults to none if not provided.
Response
200: OK
The response will consist of the plain-text filtered text. The response will have an x-document-id header that contains a document identifier assigned by Philter.
{{{REDACTED-entity}}} was a patient and his ssn was {{{REDACTED-ssn}}}.

Example request to filter text:

curl -k -X POST "https://localhost:8080/api/filter?c=context" -d @file.txt -H Content-Type "text/plain"

post
Filtering Text with Explanation

https://philter:8080/api/explain
This method receives text and removes sensitive information from the text based on the specified filter profile. The text to be filtered must be provided in the body of the request. This method is identical to /api/filter except the response contains detailed information on how the text was processed. This method can be useful in understanding why (or why not) sensitive information was filtered.
Request
Response
Request
Headers
Content-Type
required
string
The value should be set to text/plain.
Query Parameters
optional
string
A document ID that uniquely identifies the text being submitted. Leave empty and Philter will generate a document ID based on a hash of the submitted text.
p
optional
string
The name of a filter profile to use for filtering. Defaults to default is not provided.
c
optional
string
The filtering context. Defaults to none if not provided.
Response
200: OK
The response contains information about the sensitive information that was found. The appliedSpans section details the sensitive information that was manipulated.Sensitive information that was identified but not manipulated will be listed under ignoredSpans. A span will be ignored if it fails to meet some condition, is explicitly ignored, or is a smaller part of a larger span.
{
"filteredText": "{{{REDACTED-entity}}} was a patient and his ssn was {{{REDACTED-ssn}}}.",
"context": "none",
"documentId": "7a906866-4fc9-44d6-9bc3-22728b93a602",
"explanation": {
"appliedSpans": [
{
"id": "c78fb69c-84d6-4189-b376-63791793cbd2",
"characterStart": 0,
"characterEnd": 17,
"filterType": "NER_ENTITY",
"context": "C1",
"documentId": "7a906866-4fc9-44d6-9bc3-22728b93a602",
"confidence": 0.9189682900905609,
"text": "George Washington",
"replacement": "{{{REDACTED-entity}}}",
"ignored": false
},
{
"id": "f4556f62-2f80-4edc-96f0-aa1d44802157",
"characterStart": 48,
"characterEnd": 59,
"filterType": "SSN",
"context": "C1",
"documentId": "7a906866-4fc9-44d6-9bc3-22728b93a602",
"confidence": 1,
"text": "123-45-6789",
"replacement": "{{{REDACTED-ssn}}}",
"ignored": false
}
],
"ignoredSpans": []
}
}

get
Retrieving Replacement Values

https://philter:8080/api/values
This API endpoint allows you to query a history of values that were filtered for each request. The replacement store must be enabled for this API method to be available.
Request
Response
Request
Query Parameters
d
required
string
The document identifier.
Response
200: OK
The response will be a list of JSON objects containing attributes of the sensitive information identified for the given document.
[
{
"characterStart": 76,
"characterEnd": 81,
"filterType": "zip-code",
"context": "C1",
"documentId": "a288a9c4-48a8-4593-9702-d063f28c6ccc",
"confidence": 1,
"replacement": "{{{REDACTED-zip-code}}}"
},
{
"characterStart": 48,
"characterEnd": 59,
"filterType": "ssn",
"context": "C1",
"documentId": "a288a9c4-48a8-4593-9702-d063f28c6ccc",
"confidence": 1,
"replacement": "{{{REDACTED-ssn}}}"
}
]
404: Not Found
Will be returned if there is no document for the given document identifier.
There will be no response content.

Example request to retrieve replacement values:

curl -k "https://localhost:8080/api/replacements?d=88beeff6db87a543a629fdfbbeefc192"

get
Status

https://philter:8080/api/status
This API method returns the status of Philter. This endpoint is well-suited for use by an external application monitoring system to periodically check the status of Philter, such as for health checks when deployed behind an AWS EC2 load balancer.There are no parameters required for this request.
Request
Response
Request
Response
200: OK
Indicates that the Philter service is healthy and prepared to accept requests.
{"status":"Philter is healthy."}
503: Service Unavailable
This response indicates Philter is either currently initializing or has encountered an error. If the message persists check Philter's log for more information.
{"status":"Philter is currently initializing or unhealthy if status persists."}