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 seven (7) days where the request can be revoked in case it was made in error.
Following the seven (7) 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 indelete_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'
}
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-DDend_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
- 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.
- submitted: The job was submitted to run. It can no longer be modified.
- 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 seven (7) 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.