Data Regulation API | RudderStack Docs

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 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:

You can delete a user by specifying userId or any custom identifier in the event for all the above destinations except Redis and S3. For Redis and S3, RudderStack supports deleting a user only by specifying the userId.

`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 or any other custom identifier.

Only userId is a mandatory field. In addition, you can pass any custom key to identify a user as per your requirement.

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": "name@surname.com"
        }
    ]
}'

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": "name@surname.com"
        }
    ]
}'

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": "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@surname.com"
            }
        }
    ],
  "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 more information on the topics covered on this page, email us or start a conversation in our Slack community.