User Suppression API

Suppress and delete user data in accordance with your user suppression policies.
Available Plans
  • enterprise

With RudderStack’s user suppression APIs, you can create regulations to suspend data collection and delete data for specific users. You can apply these regulations across multiple destination integrations simultaneously, simplifying the process of implementing compliance requests.

With these APIs, you can:

success
The User Suppression API is a part of RudderStack’s Data Governance toolkit that ensures the quality and integrity of your data in a secure and compliant manner.

Authorization

The User Suppression API uses Bearer Authentication in the format Authorization: Bearer <PERSONAL_ACCESS_TOKEN>.

You can retrieve your personal access token from the RudderStack dashboard.

Base URL

Use the base URL for your API requests depending on your region:

Specifying source and destination IDs in your regulation

When creating user suppressions with our API, you may wish to name specific sources for a suppress regulation, and specific destinations for a suppress and delete regulation. To do so, you must first obtain the source and/or destination IDs.

Retrieving source and destination IDs

Retrieve source and destination IDs from your RudderStack dashboard or by using the /v2/sources and /v2/destinations endpoints:

GET
/v2/sources
GET /v2/sources HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E
GET
/v2/destinations
GET /v2/destinations HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E

Add a suppression regulation

Add a new user suppression regulation to suppress a given user’s data.

POST
/v2/regulations

See Request body for details on the request parameters.

Example Request:

Example Response:

[
    {
        "id": "b287a287-6b83-4402-902e-d2793b3e4ba4",
        "workspaceId": "2H2WbKP1613awrY1YgA9Q58wBOc",
        "canceled": false,
        "regulationType": "suppress",
        "attributes": {
            "email": "user@email.com",
            "phone": "+12125551212",
            "userId": "54321"
        }
    },
    {
        "id": "f57475da-5f00-4f77-a22a-26be261ad3b6",
        "workspaceId": "2H2WbKP1613awrY1YgA9Q58wBOc",
        "canceled": false,
        "regulationType": "suppress",
        "attributes": {
            "randomKey-1": "randomVal-1",
            "randomKey-2": "randomVal-2",
            "userId": "54322"
        }
    }
]
success
A successful response returns a 201 status.

Add a suppression with delete regulation

Add a new regulation to suppress and delete a given user’s data.

POST
/v2/regulations

See Request body for details on the request parameters.

Example Request:

Example Response:

[
    {
        "id": "5d2417f6-655f-494b-aab7-b0dac55a9b52",
        "workspaceId": "2H2WbKP1613awrY1YgA9Q58wBOc",
        "canceled": false,
        "regulationType": "suppress_with_delete",
        "attributes": {
            "email": "user@email.com",
            "phone": "+12125551212",
            "userId": "54321"
        }
    },
    {
        "id": "f2414ddd-e664-4a22-bd7a-b165138ccd8f",
        "workspaceId": "2H2WbKP1613awrY1YgA9Q58wBOc",
        "canceled": false,
        "regulationType": "suppress_with_delete",
        "attributes": {
            "randomKey-1": "randomVal-1",
            "randomKey-2": "randomVal-2",
            "userId": "54322"
        }
    }
]
success
A successful response returns a 201 status.

Supported destinations

RudderStack supports the suppress_with_delete request for the following destinations:

info

For the above destinations, you can delete a user by specifying the userId in the event.

Except for Redis and S3 destinations, you can also specify a custom identifier (optional) in the event along with the userId.

Request body

regulationType
required
string
Defines the user suppression type. Can be one of suppress, which suppresses incoming user data or suppress_with_delete which suppresses and deletes events from your specified destinations.
Possible Values: suppress, suppress_with_delete
sourceIds
optional
array
Specify only sourceIds with the suppress regulation. If no sourceIds are specified, RudderStack will suppress data from all sources in the workspace associated with your access token.
destinationIds
optional
array
Specify only destinationIds with the suppress_with_delete regulation. Otherwise, RudderStack throws an error.
users
required
array
An array of user objects identifying users to be suppressed. The userId field is mandatory for all users. You can pass additional custom identifiers such as email in the users object.


warning
Do not specify both sourceIds and destinationIds in your request body.

List user suppressions

List your existing user suppression regulations.

GET
/v2/regulations

Example request:

Example response:

{
  "data": [
    {
      "id": "c8fae8a7-1555-4807-89d8-972837671071",
      "workspaceId": "216AlUz1kdkhkh7RFFvJVA9THlq",
      "canceled": false,
      "regulationType": "suppress",
      "attributes": {
        "userId": "12",
        "phone": "1234567890",
        "email": "abc@xyz.com"
      }
    },
    {
      "id": "1ac629bf-d795-45df-8bfb-be06d22a636b",
      "workspaceId": "216AlUz1kdkhkh7RFFvJVA9THlq",
      "canceled": false,
      "regulationType": "suppress_with_delete",
      "attributes": {
        "userId": "rudder-1"
      }
    },
    {
      "id": "7bdf698f-80bd-4278-bb85-414ad8d27888",
      "workspaceId": "216AlUz1kdkhkh7RFFvJVA9THlq",
      "canceled": true,
      "regulationType": "suppress",
      "attributes": {
        "userId": "123",
        "phone": "9876543210",
        "email": "name@email.com"
      }
    }
  ],
  "paging": {
    "next": "/v2/regulations?after_cursor=a450395bb52f4acb99e492c358e104eb"
  },
}

Response object parameters:

paging
object
Provides a next URL for fetching paginated results. The next URL contains an after_cursor query parameter.

Cancel a user suppression

Cancel an existing user suppression regulation.

DELETE
/v2/regulations{regulation_id}

Query parameters:

regulation_id
required
string
The ID of the regulation to be canceled. The regulation_id is the id that is returned for a regulation in GET /v2/regulations.

Example request:

success
A successful response returns a 204 No Content status.

Rate Limits

Post regulation requests are rate limited.

TypeLimit (tokens per hour)
Suppression4,000
Deletion200,000
info
In the case of suppression, 1 user is equivalent to 1 token. For deletion, RudderStack calculates the number of tokens by multiplying the number of users with the number of destinations. For example, if there are n users with m destinations, the total number of tokens would be n * m.

Suppression across multiple sources

You can leverage the User Suppression API to suppress all incoming data for a given user. RudderStack drops the events for that user at the source of collection. Suppression applies across all sources, however you can also specify the specific sources you want to suppress.

warning

Note that after suppression, the events:

  • Will not be shown in any debuggers.
  • Will not be forwarded to any destinations.
  • Will not be available for event replay.

Deletion across multiple destinations

When a user requests that their data be deleted, you can leverage the User Suppression API to delete user data across multiple downstream destinations like Amplitude, Braze, Redis, and others.

We are continually adding to the list of destinations supported for deletion. If you need a destination that is not yet supported, reach out to our team.

info
The User Suppression API can delete data only for destinations running in cloud mode.

FAQ

How is the User Suppression API helpful?

To comply with data regulation statutes and users’ privacy choices, you can use RudderStack’s User Suppression API to:

  • Suppress incoming source data for a user or list of users.
  • Delete collected data for users that reside in a given destination or across multiple destinations.

For example, if a user updates their preferences to opt-out of being tracked, you can implement a regulation in the User Suppression API that stops RudderStack from collecting their data at the source, and ensuring no data is sent to downstream destinations. Also, if the user requests to be forgotten, you can delete their data from multiple downstream destinations like Amplitude and Braze with one API call.



Questions? Contact us by email or on Slack