Philter’s API provides access to Philter’s ability to detect and remove PHI and PII and to monitor Philter’s status. The available methods are available via Philter’s REST interface. Pre-built API clients are available for use in your projects in the Philter SDK. The SDK is licensed under the business-friendly Apache License, version 2.0.

The curl examples shown on this page are written assuming Philter has been enabled for SSL. If launched from the AWS or Windows Azure marketplaces or DockerHub, SSL will automatically be enabled. See the Configuration for more information on SSL.

Filter API

Filtering PHI and PII in Text

This API endpoint receives text and removes PHI from the text based on Philter’s enabled and configured filters. If not provided, the context defaults to none, and if not provided, the filter profile name defaults to default.

Endpoint HTTP Method Parameters Example
/api/filter POST c – The context (optional).
p – The name of a filter profile (optional).
curl -k -X POST "https://localhost:8080/api/filter?c=context" -d @file.txt -H Content-Type "text/plain"


The response will consist of the plain-text filtered text. The response will have a header called x-document-id that contains the Philter-assigned document ID of the submitted text. This document ID will be required if you wish to retrieve the locations of identified PHI/PII in the text at a later time. If you are not using the Filtered Replacements Store and are not interested in retrieving the locations of the identified PHI/PII you can discard the value of this header.

Retrieving PHI/PII Replacement Values

This API endpoint returns the status of Philter which will either be HTTP 200 OK or HTTP 503 Service Unavailable. This endpoint is well suited for use by an external application or service to monitor the status of Philter, such as for health checks when deployed behind an AWS EC2 load balancer.

Endpoint HTTP Method Parameters Example
/api/staus GET None curl -k https://localhost:8080/api/status


Note that Philter will return HTTP 503 Service Unavailable during initialization. Initial health checks during Philter’s initialization should be delayed by at least 2 minutes to allow adequate time for Philter to initialize.

HTTP Status Description Response
HTTP 503 Service Unavailable Philter is initializing or unhealth. {"status":"Philter is currently initializing or unhealthy if status persists."}
HTTP 200 OK Philter is healthy. {"status":"Philter is healthy."}

Filter Profiles API

The Filter Profiles API provides endpoints for retrieving, uploading, and deleting filter profiles.

Get the Available Filter Profiles

This endpoint will return a list of available filter profiles.

Endpoint HTTP Method Parameters Example
/api/profiles GET None curl -k https://localhost:8080/api/profiles

Get a Filter Profile

This endpoint will retrieve and return the JSON content of the filter profile.

Endpoint HTTP Method Parameters Example
/api/profiles/{filterProfileName} GET None curl -k https://localhost:8080/api/profiles/exprofile

Upload a Filter Profile

This endpoint will save or overwrite an existing filter profile with the given name. The body of the request should be the JSON filter profile. Note that the name of the JSON file must match the value of the name property inside the profile. The endpoint will respond with HTTP OK upon success.

Endpoint HTTP Method Parameters Example
/api/profiles PUT None curl -k https://localhost:8080/api/profiles -d @profile.json

Delete a Filter Profile

This endpoint will delete a filter profile. The endpoint will respond with HTTP OK upon success.

Endpoint HTTP Method Parameters Example
/api/profiles/{filterProfileName} DELETE None curl -k https://localhost:8080/api/profiles/exprofile
Was this article helpful to you? Yes No

How can we help?