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.
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
.
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.
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.
text/plain
.default
if not provided.none
if not provided.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"
/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.text/plain
.default
is not provided.none
if not provided.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": []}}
[{"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}}}"}]
There will be no response content.
Example request to retrieve replacement values:
curl -k "https://localhost:8080/api/replacements?d=88beeff6db87a543a629fdfbbeefc192"
{"status":"Philter is healthy."}
{"status":"Philter is currently initializing or unhealthy if status persists."}