User Suppression API

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:

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

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 <SERVICE_ACCESS_TOKEN>.

You can generate a 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

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 HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer 2Le5TOgDjwR0djObWRW6Le5kq3E

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.

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

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.

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

A successful response returns a 201 status.

Supported destinations

RudderStack supports the suppress_with_delete request for the following destinations:

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

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

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

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

Post regulation requests are rate limited.

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.

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.

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