User Privacy API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

Requests go to https://amplitude.com (default) or https://analytics.eu.amplitude.com (EU). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not analytics.amplitude.com.

Considerations

Note the following when using the User Privacy API:

• You can delete data for an end user across a single project or across your entire organization. By default, deletion requests create jobs for the project that the request's API key identifies. To delete a user across your entire organization, set the delete_from_org parameter to true. When delete_from_org is true, the API creates one deletion job per project that contains data for the requested users, and treats ignore_invalid_ids as true regardless of the input.
• When you make a deletion request, Amplitude emails all account admins with the deletion details.
• Amplitude deletes all events and user properties added up until the time the job runs for each Amplitude ID in a deletion job.
• Running a deletion job for a user doesn't block new events for that user. Amplitude accepts new events from a deleted user.
• If Amplitude receives events for a deleted user, Amplitude counts the deleted user as a new user. Because deletion removes all user data from Amplitude servers, Amplitude doesn't recognize the new user as the deleted user.
• Amplitude schedules batch jobs for deletions to reduce resource impact and ensure high availability. The batch's first request date is the reference point for scheduling. In line with GDPR articles 12.3 and 17, Amplitude processes deletion requests within 30 days after receiving the request. The actual timeline depends on the complexity and number of requests. If your data volume is large (>1BB/month), Amplitude may reduce your frequency of deletion scheduling.
• You can revoke requests in the batch until three (3) days before the job's scheduled run date. During the three (3) day period, you can't edit the batch. Amplitude adds deletion requests made during this period to a new batch.
• After the three (3) day period, the request's status changes to submitted, and you can't stop the job. The deletion process removes all data associated with the user from all of Amplitude's systems, including associated recovery and back-up systems. After the job completes, its status changes to done.
• To check the progress of your deletion requests, use the GET API to inspect the job status for each project, using each project's API key.

Limits

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. There is also a limit of 8 requests running in parallel for a given project.

Make up to 100 deletion requests per second if you batch 100 users in each request.

Delete users

POST /deletions/users

Add a user for deletion using a JSON body. Specify up to 100 users at a time. You can use a mix of Amplitude IDs and User IDs.

JSON body parameter

The body parameter is required. It's the deletion request object listing the user_ids and amplitude_ids for the users to delete.

Response

The response for a POST request contains these fields:

The amplitude_ids key contains these fields:

Get deletion jobs

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

Retrieves a list of deletion jobs scheduled in a time range. The time range should include the date you made the request on plus 30 days. For example, if you made a deletion request on August 1st, 2018, your query should have start_day = 2018-08-01 and end_day = 2018-08-31.

If the request returns no values, no jobs are scheduled for that time range. The largest permitted time range is six months.

# You can also use wget
curl -X GET https://amplitude.com/api/2/deletions/users?start_day=string&end_day=string \
  -H 'Accept: application/json' \
  -U API_KEY:API_SECRET

Query parameters

Response

The success response for a GET request contains these fields:

• day
  • Description: The day the deletion job is scheduled to begin.
• status
  • Description:
    • The deletion job's status.
    • Staging: The job hasn't started, and you can modify it. More deletion requests may get scheduled into this job and you can remove requests from this job.
    • Submitted: The job is submitted to run. You can't modify it.
    • Done: The job has finished running. You can't modify it.
• amplitude_ids
  • Description: List of the Amplitude Ids of users to delete.
• app
  • Description: Project or app ID. Appears if the deletion is applied to more than one project.
• active_scrub_done_date
  • Description: The date the scrub completed and the data is no longer accessible. After this date, Amplitude waits 5 days for any backups to clear automatically. The status changes to done only after the backups are removed.

The amplitude_ids key contains these fields:

[
  {
    "day": "string",
    "amplitude_ids": [
      {
        "amplitude_id": 0,
        "requested_on_day": "string",
        "requester": "string"
      }
    ],
    "status": "string"
  }
]

Delete a user from a deletion job

Removes the specified Amplitude ID from a deletion job.

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

curl -X DELETE \
  'https://amplitude.com/api/2/deletions/users/AMPLITUDE_ID/JOB_START_DAY' \
  -H 'Content-Type: application/json' \
  -U API_KEY:API_SECRET

Path variables

Response

A successful request returns a response with this schema:

{
  "amplitude_id": 1234567,
  "requested_on_day": "string",
  "requester": "string"
}

Status codes