User Privacy API

Updated

Important Note:

This article has been moved to our new Developer Center. For the latest info, please see User Privacy API

Table of Contents

In order to ensure that our customers can adhere to end-user data deletion request mandated by global privacy laws such as GDPR and CCPA, we have built a simple and easy-to-use API endpoint that allows you to programmatically submit requests to delete all data for a set of known Amplitude IDs and/or User IDs.

This system also communicates a confirmation update to the administrators of your Amplitude organization so you can be confident you have fully complied with your customers’ privacy requests, e.g. when a request is made for deletion all admins of the account will receive an email with details about the deletion.

In the example requests, the parameters are highlighted purple. The values in red are what you need to replace with the parameters you are specifically interested in. Please feel free to check out the Amplitude Developer centre for more details.

Authenticate via basic authentication with the project's credentials API_Key:Secret_Key. You should literally replace the "API_Key" text with your API Key, and the "Secret_Key" text with your Secret Key. For instructions on how to find these keys, refer here.

Table of Contents

IMPORTANT NOTE: Using this API does not prevent future user tracking for the deleted users. To learn about how to stop tracking users in your application, see the setOptOut() method in our SDKs.

 

API endpoint

https://amplitude.com/api/2/deletions/users

This endpoint uses basic authentication.

 

Response Objects

All API operations will respond with a JSON object composed of the following objects described in this section.

 

Deletion Job

Represents many deletion requests scheduled on some date. This object contains the following fields:

  • day: The day the deletion job is scheduled to begin.
  • status: The status of the deletion job.
  • amplitude_ids: List of deletion requests in this job.
  • app: project/app id, only appears when the deletion is done for multiple projects.

 

Deletion Request

When a request is made, we confirm the validity of the requestor via the secret key and the end-user via the Amplitude ID. We batch multiple requests for deletions to reduce operational impact on the platform and ensure high availability and refresh of the dashboard. We  provide a grace period of three (3) days where the request can be revoked in case it was made in error.

Following the three (3) day grace period, the request will transition to status = 'submitted' after which it cannot be stopped. The purge process will completely remove all data associated with the user from all Amplitude's systems, including associated recovery and back-up systems. Once the job is completed, it will be marked as "done". This object contains the following fields:

  • amplitude_id: The Amplitude ID being deleted.
  • requester: The person who requested the Amplitude ID to be deleted.
  • requested_on_day: The day this deletion was requested.

 

POST

Request a user be scheduled for deletion. Up to 100 users can be specified at a time, and a mix of Amplitude IDs and User IDs is permitted.

/api/2/deletions/users

 

Arguments

  • amplitude_ids: Amplitude IDs to be deleted.
  • user_ids: User IDs to be deleted.
  • requester: The person who requested the Amplitude ID to be deleted. This is useful for auditing.
  • ignore_invalid_id: Ignore any invalid user IDs(users that do no exist in the project) that were passed in
  • delete_from_org: delete from the entire org rather than just this project. Can only be used with portfolio orgs (have the Portfolio feature enabled) and with user ids only. Values can be either 'True' or 'False' and by default it is set to False

 

Content Types

  • application/x-www-form-urlencoded: amplitude_ids and user_ids arguments can be given multiple times.
  • application/json: Request body should be a JSON object like:
{
    "amplitude_ids": [...],
    "user_ids": [...],
    "requester": "",
    "ignore_invalid_id": "False",
    "delete_from_org": 'False'
}

Note: For "ignore_invalid_id" and "delete_from_org", both double and single quotes should work. However, double quotes are JSON standard so it will be more reliable.  

Response

The deletion job that will remove the requested users' data.

 

Usage Example

Request:

curl -s -u API_KEY:SECRET_KEY --data amplitude_ids=1234567890 --data requester='somebody@acmecorp.com' --data ignore_invalid_id='True' --data delete_from_org='True' 'https://amplitude.com/api/2/deletions/users' | json_pp

Response:

[
    {
        "day" : "2018-02-04", 
        "amplitude_ids" : [ 
           { 
                "requested_on_day" : "2018-01-26", 
                "amplitude_id" : 1234567890, 
                "requester" : "somebody@acmecorp.com" 
           } 
         ], 
         "status" : "staging",
         "app" : "1234"
    }
]

In case of multiple projects requested:

[
    {
        "day" : "2018-02-04", 
        "amplitude_ids" : [ 
            { 
                "requested_on_day" : "2018-01-26", 
                "amplitude_id" : 1234567890, 
                "requester" : "somebody@acmecorp.com" 
            } 
        ], 
        "status" : "staging",
        "app" : "1234"
    },
    {
        "day" : "2018-02-08", 
        "amplitude_ids" : [ 
            { 
                "requested_on_day" : "2018-01-26", 
                "amplitude_id" : 1234567890, 
                "requester" : "somebody@acmecorp.com" 
            } 
        ], 
        "status" : "staging",
        "app" : "234"
    }
]

 

GET

List deletion jobs scheduled in a time range; this time range should include the date you made the request on plus 30 days. For example, you made a deletion request on August 1st, 2018. Your deletion request should have `start_day = 2018-08-01` and `end_day = 2018-08-31`.

If this returns no values, then this means no jobs were scheduled for that time range. Note: The largest permitted time range is six months.

/api/2/deletions/users?start_day=YYYY-MM-DD&end_day=YYYY-MM-DD

 

Arguments

  • start_day: YYYY-MM-DD
  • end_day: YYYY-MM-DD

 

Response

A list of deletion jobs in the specified time range.

 

Usage Example

Request:

curl -s -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/deletions/users?start_day=2018-01-15&end_day=2018-02-15' | json_pp

Response:

[
    {
        "day" : "2018-02-04",
        "status" : "staging",
        "amplitude_ids" : [
            {
                "requested_on_day" : "2018-01-26",
                "amplitude_id" : 1234567890,
                "requester" : "somebody@acmecorp.com"
            }
        ]
    }
]

 

DELETE

A DELETE request to the following endpoint will remove the specified Amplitude ID from a deletion job.

/api/2/deletions/users/AMPLITUDE_ID/YYYY-MM-DD

 

Response

The deletion request that was removed.

 

Usage Example

Request:

curl -s -XDELETE -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/deletions/users/1234567890/2018-02-04' | json_pp

NOTE: The date from the "Cancel Deletion" request should be equivalent to the day when this job is scheduled to start (the field "day" in the above example). 

Response:

{
    "requested_on_day" : "2018-01-26",
    "requester" : "somebody@acmecorp.com",
    "amplitude_id" : 1234567890
}

 

Job Statuses

  1. staging: The job has not begun and can still be modified. More deletion requests may get scheduled into this job and you can remove requests from this job.
  2. submitted: The job was submitted to run. It can no longer be modified.
  3. done: The job has been completed. It can no longer be modified.

 

FAQ

1. What data is deleted about a user?
For all Amplitude IDs in a deletion job we delete all events and user properties seen up to the time that job runs for that user.

 

2. Are events from a deleted user blocked from being sent to Amplitude automatically?
No, if a deletion job runs for user X, then later events are received for user X, we will accept those events.

 

3. If a user is deleted and more events are sent are they re-counted as a new user?
Yes, Amplitude will no longer recognize the user once their data has been deleted from our servers.

 

4. When can I expect the data to be deleted?
When a request is made, we add it to a batch to increase the number of deletions that run simultaneously to reduce impact on the platform. This also provides a grace period of three (3) days where the request can be revoked in case it was made in error.

NOTE: If your data volume is large (>1BB/month), then we may need to reduce your frequency of deletion scheduling. We will reach out to you about this in case it is necessary.

 

5. What is the API rate limit?
The endpoint /api/2/deletions/users has a rate limit of 1 HTTP request per second. Each HTTP request can contain up to 100 amplitude_ids or user_ids. Hence, you can request 100 users deleted per second assuming you batch up to 100 users into each of your requests.

 

6. What happens if I send duplicate deletion requests? 
We will log the duplicate delete requests but there is no impact with having duplicates. What that means is we'll return a 200 status response on the duplicate request so long as it is formatted correctly. We don't immediately block duplicates and return a 400 response saying it is a duplicate. But sending duplicates will not create any issues. If it's the same request, we will be able to return the same request ID back. Thus in that sense the duplicate calls are effectively "ignored and thrown away" in terms of what happens in our backend. 

Was this article helpful?
5 out of 7 found this helpful
Have more questions? Submit a request
Return to top

Related articles