Querying Lists via the API in SuppressionList

Your lists can be queried for the existence of an item in the list via API. You may query the list for an item using either the items original value or a MD5 hashed version of that value.

Query a Single List

You can check a single list for the existence of an item. Use an HTTP GET request to:

https://app.suppressionlist.com/exists/{{list_id}}/{{query term}}:

Query

$ curl -X GET https://app.suppressionlist.com/exists/my\_list/test@email.com \
-H ‘Accept: application/json’ \
-uAPI:fc36c8168cbb16784f6a29f89695dd92v

Query Term Found

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
“specified_lists”: [
“my_list”
],
“key”: “test@email.com”,
“found”: true,
“exists_in_lists”: [
“my_list”
],
“entries”: [
{
“list_id”: “57b4c77bf92ea11d7d000001”,
“list_url_name”: “my_list”,
“added_at”: “2018-10-08T11:01:32Z”
}
]
}

Query Term Not Found

HTTP/1.1 404 NOT FOUND
Content-Type: application/json; charset=utf-8
{
“specified_lists”: [
“my_list”
],
“key":"test@email.com”,
“found”:false
}

Standardizing Data

Upon receiving a item to add to a List or a term to query, SuppressionList will take the following steps:

1. Strip leading and trailing whitespace from the query string
2. Downcase all characters in the query string
3. MD5 hash the query string before performing the add or query.

Note that punctuation is not removed, only whitespace. So phone number formats, for example, are not standardized. We recommend that you standardize all data before adding it to a list as well as before querying.

Querying Multiple Lists

You can also check for the existence of an item across multiple lists in a single query. Use an HTTP GET request to:

https://app.suppressionlist.com/exists/{{list\_id\_1}}|{{list_id_2}}/{{query_term}}:

Query

$ curl -X GET https://app.suppressionlist.com/exists/my\_list|my\_other\_list|my\_third\_list/test@email.com \
-H ‘Accept: application/json’ \
-uAPI:fc36c8168cbb16784f6a29f89695dd92

Query Term Found

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
“specified_lists”: [
“my_list”,
“my_other_list”,
“my_third_list”
],
“key”: “test@email.com”,
“found”: true,
“exists_in_lists”: [
“my_list”,
“my_third_list”
],
“entries”: [
{
“list_id”: “5a5635e0ec89931a8932f565”,
“list_url_name”: “my_list”,
“added_at”: “2018-10-08T14:27:38Z”
},
{
“list_id”: “568d396eec8d938c48000002”,
“list_url_name”: “my_third_list”,
“added_at”: “2018-10-08T14:28:13Z”
}
]
}

Query Term Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
“specified_lists”: [
“my_list”,
“my_other_list”,
“my_third_list”
],
“key":"test@email.com”,
“found”:false
}