User Suppression API

This guide explains how to use the User Suppression API to suppress and delete user data in accordance with the compliance and user suppression policies of your organization.

Overview

With RudderStack’s User Suppression API, 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:

• Add a suppression regulation to drop user events at the source. These events will not be available for debugging, replay, or forwarded to destinations.
• Add a suppression with delete regulation to delete any user data sent to a destination.
• List all regulations created with the User Suppression API.
• Delete a specific regulation created previously.

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.

How is the User Suppression API helpful?

You can use the User Suppression API to comply with data regulation statutes and users’ privacy choices by:

• Suppressing incoming source data for a user or list of users.
• Deleting the collected user data in a given downstream 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.

Authorization

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

Generate a workspace-level Service Access Token in the RudderStack dashboard.

For production use cases, RudderStack recommends using a Service Access Token instead of Personal Access Token.

Base URL

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

https://api.rudderstack.com

https://api.eu.rudderstack.com

Specify source and destination IDs in your regulation

To name specific sources for your Suppress regulation, or specific destinations for your Suppress with Delete regulation, you will first need to obtain the respective source and destination IDs.

Retrieve source ID

You can review the source ID of a particular source from your RudderStack dashboard, as shown:

Alternatively, you can retrieve the source ID by using the /v2/sources endpoint of the API:

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

Retrieve destination ID

You can review the destination ID of a particular destination from your RudderStack dashboard, as shown:

Alternatively, you can retrieve the destination ID by using the /v2/destinations endpoint of the API:

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 at the source.

RudderStack processes most suppression requests within 24 hours. However, in some cases, it may take up to 30 days depending on the number of requests in the queue for your workspace.

Request body:

See Request body for details on the request parameters.

Example request:

POST /v2/regulations HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E
Content-Type: application/json
Content-Length: 182

{
  "regulationType": "suppress",
  "sourceIds": [
    "27OeyCriZ4vGFiOFPihSMgr0Nt1"
  ],
  "users": [
    {
      "userId": "54321",
      "phone": "+12125551212",
      "email": "user@email.com"
    },
    {
      "userId": "54322",
      "randomKey-1": "randomVal-1",
      "randomKey-2": "randomVal-2"
    }
  ]
}

curl --location --request POST 'https://api.rudderstack.com/v2/regulations' \
--header 'Authorization: Bearer 2345678Dv9J5NZsEqVJWLQutE4E' \
--header 'Content-Type: application/json' \
--data-raw '{
  "regulationType": "suppress",
  "sourceIds": [
    "27OeyCriZ4vGFiOFPihSMgr0Nt1"
  ],
  "users": [
    {
      "userId": "54321",
      "phone": "+12125551212",
      "email": "user@email.com"
    },
    {
      "userId": "54322",
      "randomKey-1": "randomVal-1",
      "randomKey-2": "randomVal-2"
    }
  ]
}'

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"
        }
    }
]

Status codes:

A successful request returns a 201 response status.

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 sources you want to suppress by specifying the source IDs in the request body.

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.

Add a suppression with delete regulation

Add a new regulation to suppress and delete a given user’s data. See Limitations before using this regulation.

Request body:

See Request body for details on the request parameters.

Example request:

POST /v2/regulations HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E
Content-Type: application/json
Content-Length: 182

{
    "regulationType": "suppress_with_delete",
    "destinationIds": [
        "27OeyCriZ4vGFiOFPihSMgr0Nt1"
    ],
    "users": [
        {
            "userId": "54321",
            "phone": "+12125551212",
            "email": "user@email.com"
        },
        {
            "userId": "54322",
            "randomKey-1": "randomVal-1",
            "randomKey-2": "randomVal-2"
        }
    ]
}

curl --location --request POST 'https://api.rudderstack.com/v2/regulations' \
--header 'Authorization: Bearer 2345678Dv9J5NZsEqVJWLQutE4E' \
--header 'Content-Type: application/json' \
--data-raw '{
    "regulationType": "suppress_with_delete",
    "destinationIds": [
        "27OeyCriZ4vGFiOFPihSMgr0Nt1"
    ],
    "users": [
        {
            "userId": "54321",
            "phone": "+12125551212",
            "email": "user@email.com"
        },
        {
            "userId": "54322",
            "randomKey-1": "randomVal-1",
            "randomKey-2": "randomVal-2"
        }
    ]
}'

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"
        }
    }
]

Status codes:

A successful request returns a 201 response status.

Supported destinations

RudderStack supports the suppress_with_delete request for the following destinations:

• Amplitude
• AppsFlyer
• Braze
• CleverTap
• Google Analytics
• Intercom
• Mixpanel
• Redis
• S3

You can delete a user for these destinations 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.

The RudderStack team is actively working on adding more destinations supported for the Deletion regulation. You can contact the team if you need a destination that is not yet supported.

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.

The User Suppression API can delete data only for destinations connected to RudderStack in cloud mode.

Limitations

Before using the Suppression with Delete regulation, note that:

• While RudderStack forwards the deletion request, it does not guarantee deletion within a 30-day window. You will need to check with the respective destination provider if the request is fulfilled.
• The requests made to the User Suppression API are rate-limited. See Rate limits for more details.

Request body

Specify either sourceIds or destinationIds in your request body — do not specify both.

List user suppressions

List your existing user suppression regulations.

Example request:

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

curl --location --request GET 'https://api.rudderstack.com/v2/regulations' \
--header 'Authorization: Bearer 23456pCURNbcG0fGRfkgAdcWQsW'

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:

Cancel a user suppression

Cancel an existing user suppression regulation.

Query parameters:

Example request:

DELETE /v2/regulations/f0222ce9-bbaf-4585-9c17-18cde664c0af HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E

curl --location --request DELETE 'http://api.rudderstack.com/v2/regulations/e44c5f3b-b4ca-4b17-8147-7bc1c9620fe3' \
--header 'Authorization: Bearer 12345nuDv9J5NZsEqVJWLQutE4E'

A successful response returns a 204 No Content status.

Rate limits

Requests to the User Suppression API are rate-limited:

Note that:

• In case of user 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 m users with n destinations, the total number of tokens would be m * n.

Questions? Contact us by email or on Slack