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.

Suppression List API Functions

Upload and Create a Suppression List
View the list of Suppression Lists of an Account
View Details Of A Single Suppression List
Delete a Suppression List
Download a Suppression List