User Privacy API v2

What's new in v2

If you're already integrated with v1, the most important change is how deletion scope is interpreted. v1 defaulted to single-app (project) deletion when scope was unspecified. v2 always deletes across your entire organization. v2 also takes a smaller request body: amplitudeIds and userIds are renamed and the only parameters it accepts.

Endpoints

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.

Use the host that matches your project's data residency.

Authentication

Bearer token authentication with your org-level secret key.

Authorization: Bearer <org-secret-key>

Submit a deletion request

POST /api/user-deletions/org/{orgId}/requests

Add users for deletion using a JSON body (DeletionRequest). Specify up to 100,000 users at a time. You can use a mix of Amplitude IDs and User IDs. Every request deletes user data across your entire organization.

Body parameters

List deletion requests

GET /api/user-deletions/org/{orgId}/requests

Returns all deletion requests for the organization.

curl --request GET 'https://privacy.amplitude.com/api/user-deletions/org/{orgId}/requests' \
  --header 'Authorization: Bearer <org-secret-key>' \
  --header 'Accept: application/json'

Get a deletion request

GET /api/user-deletions/org/{orgId}/requests/{requestId}

Returns a single deletion request by ID.

curl --request GET 'https://privacy.amplitude.com/api/user-deletions/org/{orgId}/requests/{requestId}' \
  --header 'Authorization: Bearer <org-secret-key>' \
  --header 'Accept: application/json'

Job lifecycle

A job moves from STAGING to SUBMITTED 3 days before its scheduled run date. After a job becomes SUBMITTED, it cannot be canceled.

Response bodies

Every endpoint returns JSON with camelCase field names. Two shapes cover all three endpoints.

DeletionResponse

The POST endpoint returns a DeletionResponse. A 202 carries the ID of the request Amplitude created, and a 400 carries the reason it rejected the request. Exactly one of the two fields is present.

{ "requestId": "20000042" }

{ "error": "at least one amplitudeId or userId must be provided" }

DeletionFetchResponse

Both GET endpoints return a DeletionFetchResponse. The list endpoint returns an array of them, one per request, and the get endpoint returns a single object. A 404 from the get endpoint carries an error field instead.

{
  "status": "DONE",
  "requestedAt": "2026-05-22T00:00:00Z",
  "completedAt": 1747872000.0,
  "idStatus": [
    { "userId": "user_1", "ampId": null, "status": "NOT_FOUND" },
    { "userId": null, "ampId": 123456789, "status": "DONE" }
  ]
}

Request status

IN_PROGRESS and RESOLVED are transient. A request passes through both on its way from STAGING to SUBMITTED, usually within minutes.

ID resolution

Each entry in idStatus reports one ID from the original request. userId and ampId echo what you submitted, so exactly one of them is set and the other is null.

A NOT_FOUND entry is the only way to tell that an ID matched nothing. The request as a whole still reports DONE, even if every ID in it was unknown.

Org-wide deletion

All v2 deletion requests are org-wide. When you submit a request, Amplitude fans the deletion out to every project in the organization that contains data for the listed users.

• One deletion job is created for each project that has matching data.
• All account admins receive an email with the full list of Amplitude IDs scheduled for deletion across the org.

If you previously used v1 without setting delete_from_org, your historical deletion requests may have only deleted from a single project. Re-submit those users through v2 to ensure org-wide deletion.

Service-level commitments and timing

Important behaviors

Deletion doesn't stop future tracking

The User Privacy API removes existing data. It does not prevent Amplitude from accepting new events for the deleted user. If your SDK continues to send events for them, those events are ingested as a brand-new user. Amplitude has no memory of the deleted identity to re-link against.

To stop future tracking, use the setOptOut() method on the Amplitude SDK you're using.

Warehouse / CDC reingestion

If you ingest data into Amplitude from a data warehouse through Change Data Capture (CDC) or other warehouse-native ingestion methods, deletion in Amplitude does not propagate back to the source. On the next sync, the deleted data may be reingested.

To ensure complete deletion, delete the data in your warehouse source as well, then re-run the User Privacy API request. This applies to:

• Snowflake / BigQuery / Databricks / Redshift CDC sources
• Mirror Sync
• Any other warehouse-native ingestion path

Future event identity

After a deletion, if new events arrive for the same userId, they are treated as a new user with a fresh Amplitude ID. There is no automatic re-stitching.

Statsig data

Migrating from v1

1. Update your endpoint

- POST https://amplitude.com/api/2/deletions/users
+ POST https://privacy.amplitude.com/api/user-deletions/org/{orgId}/requests

Use the list and get-by-ID GET routes above instead of v1's date-range query. v2 does not yet support DELETE to remove users from staging — keep using v1 for that workflow if needed.

2. Update authentication

v2 uses Bearer authentication with an org-level secret key instead of v1's project API key + secret key.

- Authorization: Basic <base64(api_key:secret_key)>
+ Authorization: Bearer <org-secret-key>

Generate an org-level secret key under Settings → API Keys → Org-level Secret Keys.

3. Batch your requests

v2 accepts up to 100,000 IDs per request. Batch IDs in each request to delete users efficiently.

4. Remove unused parameters

delete_from_org, requester, ignore_invalid_ids, and include_mapped_user_ids are v1-only. On v2, all requests delete org-wide by default and invalid ids are ignored by default - you don't need to (and can't) set these flags.

  {
-   "user_ids": ["user_1"],
-   "requester": "privacy@yourcompany.com",
-   "delete_from_org": true
+   "userIds": ["user_1"]
  }

If you were using v1 without delete_from_org, your requests only deleted from a single project. Migrating to v2 automatically upgrades those requests to org-wide deletion.

5. Use request status visibility

v2 exposes GET endpoints to list deletion requests and fetch a single request by requestId, including lifecycle state (staging / submitted / done).

Status codes