API to manage the Suppression Lists in REACH
This document defines the URL structure, inputs, and behavior of the public Versium REACH Suppression List API. The RESTful Suppression List API enables programmatic management of a REACH account’s suppression lists.
For more details please see Suppression Lists.
The following functions are supported by the Suppression List API:
- Upload a file and create a suppression list
- View an account’s suppression lists
- View a single suppression list
- Delete a suppression list
- Download the file
API Overview
API URL: https://api.versium.com/v2/suppression-lists
Authentication: Authentication is done by passing the API key in the “x-versium-api-key” header. Please see Authentication sections for full details.
Response Structure
The API only supports returning JSON.
Successful response structure
{
"versium": {
"version":"2.0",
"query_id":"48f9238a-ba98-4c45-97df-74f405c97527",
"query_time":1.340619087219238,
"results":[{}], //this value can be a single suppression list object OR an array of suppression list objects, depending on the API
}
}
Error Responses
When an error occurs, the response object will contain an “errors” property, which is a string of arrays.
{
"versium": {
"version":"2.0",
"query_id":"48f9238a-ba98-4c45-97df-74f405c97527",
"query_time":1.340619087219238,
"results":[{}],
"errors": \[]
}
}
Suppression List Object Structure
Most of the Suppression List APIs will either:
- return one or more suppression list objects inside of the “results” array
- return a single suppression list object as the value of “results”
Suppression List object example:
{
"id": 51, //id for referencing the list
"guid": "1361f1bd-713b-4571-9a7a-1e93b140989a", //unique guid
"name": "Suppression-Emails.csv", //name of uploaded file
"status": 4, //current processing status of the list
"records": 6, //how many records were in the uploaded file
"meta_data": { //various meta data about the list
"errors": 0, //how many errors occurred during processing
"field_counts": { //how many of each field where found in the file
"Phone": 0,
"Domain": 0,
"EmailAddr": 5
},
"callback_url": "" //callback URL for when list processing is complete
},
"created_at": "2024-01-24T20:01:07.000000Z", //create at timestamp
"deleted_at": null, //delete at timestamp
"header_map": { //a list of column that contain suppression values
"email": [
0
]
},
"has_header": true //a boolean indicating whether the file has a header
}
HTTP Status Codes
The API will attempt to return HTTP Status Codes for successful and failed requests. Use these codes to determine whether the request was successful. When an error code is returned, check the “errors” property in the response object for more details.