Data regulation API

RudderStack’s Data Regulation API lets you create regulations to suspend data collection and delete data for particular users.

The Data regulation API is applicable only for destinations configured to send events using cloud mode.

What is data regulation?

In order to comply with data regulation statutes and users’ privacy choices, we provide tools that allow you to:

• Suppress incoming source data for a user or list of users
• Delete collected data for users that resides in a given destination

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. After suppression, events:

• Will not be shown in any debuggers
• Will not be forwarded to any destinations
• Will not be available for Event Replay

API Overview

With our regulation APIs, perform the following actions:

• Add a suppression regulation. A suppression regulation drops the user events at the source, and they will not be available for debugging, replay, or forwarded to destinations.
• Add a suppress and delete regulation. A suppress/delete regulation deletes any user data that was sent to a destination.
• List all regulations
• Delete a specific regulation

Authorization

Our data regulation APIs use Bearer authentication in the format Authorization: Bearer <PERSONAL_ACCESS_TOKEN>.

Retrieve your Personal Access Token from the RudderStack web app.

Retrieve source and destination IDs

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

Retrieve source and destination IDs for your data regulations 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 data 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": "email@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": "email@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": "email@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 succesful response will return 201 Status Code.

Add a suppression with delete regulation

Add a new data 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": "email@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": "email@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": "email@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 will return the 201 status code.

RudderStack supports the suppress_with_delete request for the following destinations:

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

For the above-mentioned 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 in addition to the userId.

Request body

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

List data regulations

List your existing data 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@surname.com"
      }
    }
  ],
  "paging": {
    "next": "/v2/regulations?after_cursor=a450395bb52f4acb99e492c358e104eb"
  },
}

Response object parameters:

Cancel a data regulation

Cancel an existing data 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 succesful response will return 204 No Content.

Questions? Contact us by email or on Slack