Data Regulation API

Detailed technical documentation on the RudderStack Data Regulation API for suppressing and deleting user data.

RudderStack's Data Regulation API lets you specify regulations to suspend data collection and delete data for a particular user.

This guide covers the data regulation feature in detail and details the Data Regulation API endpoints.

The Data Regulation API is applicable only for the destinations configured to sent events using the RudderStack cloud mode.

What is data regulation?

RudderStack respects the users' data privacy choices.

You can leverage RudderStack's data regulation feature to suppress any incoming data for a given user. RudderStack will drop the events for that user at the source - these events will not be shown in any debugger or forwarded to any destinations.

You can also use this feature to direct RudderStack to suppress any incoming events for a user and delete any collected data for a given destination.

Once a user is suppressed, it is not possible to replay their events.

Prerequisites

You need to generate a personal access token to authenticate the Data Regulation API and use it successfully.

API authorization

The Data Regulation API uses the Bearer Token Authentication for authenticating all the requests.

The Personal Access Token should be used as the bearer token for authentication.

Adding a new data regulation

This request lets you add a new data regulation to suppress/suppress and delete a given user's data.

Adding a suppression regulation

• Request type: POST

• Request format:

https://api.rudderstack.com/v2/regulations

• Request body:

{
  "regulationType": "suppress",
  "sourceIds": [<source_IDs>],
  "users": [{
    "userId": "<user_ID>",
    "phone": "<phone_number>",
    "email": "<user_email>"
  }]
}

Adding a suppression with delete regulation

• Request type: POST

• Request format:

https://api.rudderstack.com/v2/regulations

• Request body:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": [<dest_IDs>],
  "users": [{
    "userId": "<user_ID>",
    "phone": "<phone_number>",
    "email": "<user_email>"
  }]
}

RudderStack supports the suppress_with_delete request for the following destinations:

• Amplitude

• Braze

• Intercom

• S3

• Redis

regulationType

This field lets you define the data regulation type. It supports the following values:

Parameter Name	Description
suppress	Directs RudderStack to suppress the incoming user data.
suppress_with_delete	Directs RudderStack to suppress any incoming user data and delete any events from the user-specified destinations.

destinationIds and sourceIds

You can set these optional fields to specify the sources or destinations from which the data should be suppressed or deleted.

• Specify only sourceIds when setting the regulationType to suppress. If no sourceIds are specified, RudderStack will suppress data from all the sources present in the workspace associated with the access token.

• Specify only destinationIds when setting the regulationType to suppress_with_delete. If no destinationIds are specified, RudderStack will delete the data for all the destinations present in the workspace.

• Use the https://api.rudderstack.com/v2/sources endpoint to get the source IDs.

• Use the https://api.rudderstack.com/v2/destinations endpoint to get the destination IDs.

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

users

The API lets you specify the users for whom you want to set the data regulation. These users can be identified either by their userId, phone, or email.

Only userId is a mandatory field. The other fields are optional as some destinations require phone number or email to associate a given user and do not strictly identify a user by their user ID.

We recommend that you provide the user's phone and email at your own discretion and only if it is required.

• Sample suppression request

curl --location --request POST 'https://api.rudderstack.com/v2/regulations' \
--header 'Authorization: Bearer 2345678Dv9J5NZsEqVJWLQutE4E' \
--header 'Content-Type: application/json' \
--data-raw '{
    "regulationType": "suppress",
    "sourceIds": [
        "src-1"
    ],
    "users": [
        {
            "userId": "123",
            "phone": "9876543210",
            "email": "[e-mail]"
        }
    ]
}'

• Sample suppression with delete request

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": [
        "dest-1"
    ],
    "users": [
        {
            "userId": "123",
            "phone": "9876543210",
            "email": "[e-mail]"
        }
    ]
}'

• Expected response

Created

List all data regulations

This request lists all your data regulations.

• Request type: GET

• Request format:

https://api.rudderstack.com/v2/regulations

• Parameters:

Parameter	Type	Description
after_cursor	String	Fetches the regulations after this position. This cursor position is obtained from the paging object from the previous request. Refer to the sample response below for more information.

• Sample request

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

• Expected response

{
    "data": [
        {
            "id": "c8fae8a7-1555-4807-89d8-972837671071",
            "workspaceId": "216AlUz1kdkhkh7RFFvJVA9THlq",
            "canceled": false,
            "regulationType": "suppress",
            "attributes": {
                "userId": "12",
                "phone": "1234567890",
                "email": "[e-mail]"
            }
        },
        {
            "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": "[e-mail]"
            }
        }
    ],
  "paging": {
    "next": "/v2/regulations?after_cursor=a450395bb52f4acb99e492c358e104eb"
  },
}

Cancel a data regulation

This request cancels an existing data regulation.

• Request type: DELETE

• Request format:

https://api.rudderstack.com/v2/regulations/{regulation_id}

• Parameters:

Parameter	Type	Description
regulation_id	String	Refers to the ID of the data regulation to be cancelled.

• Sample request:

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

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.