Delete User

Delete a user's data from the Distinct system via the user deletion endpoint.

Endpoint

POST https://api.distinct.so/api/v1/users/delete

Request Headers

Key	Value
Content-Type	application/json
x-distinct-api-key	Your shared API key

Request Body

Key	Type	Required	Description
id	String	Yes	Unique user id provided by the vendor
email	String	Conditional	Email address of the user to delete
phone	String	Conditional	Phone number of the user in E.164 format (e.g. +14155552671)

info

• At least one of email or phone must be provided.
• Optional fields should be omitted from the request body if there are no values — do not send them as empty strings or null.
• When phone is provided, it must be in E.164 format — starting with +, followed by country code and subscriber number, with no spaces, dashes, or parentheses (e.g. +14155552671).
• When both email and phone are provided, both must match the same user for deletion to proceed.

Response

Success (200)

{
  "statusCode": 200,
  "message": "User data deleted successfully.",
  "data": null
}

Example Requests

Delete by Email Only

curl -X POST 'https://api.distinct.so/api/v1/users/delete' \
-H 'Content-Type: application/json' \
-H 'x-distinct-api-key: <shared-api-key>' \
-d '{
"id": "f090a4a1-c447-461e-84aa-8f36b6431b94",
"email": "john.doe@example.com"
}'

Delete by Phone Only

curl -X POST 'https://api.distinct.so/api/v1/users/delete' \
-H 'Content-Type: application/json' \
-H 'x-distinct-api-key: <shared-api-key>' \
-d '{
"id": "f090a4a1-c447-461e-84aa-8f36b6431b94",
"phone": "+14155552671"
}'

Delete by Both Email and Phone

curl -X POST 'https://api.distinct.so/api/v1/users/delete' \
-H 'Content-Type: application/json' \
-H 'x-distinct-api-key: <shared-api-key>' \
-d '{
"id": "f090a4a1-c447-461e-84aa-8f36b6431b94",
"email": "john.doe@example.com",
"phone": "+14155552671"
}'

Replace the placeholders:

• <shared-api-key> — your actual shared API key from Distinct

tip

This endpoint is idempotent — it is safe to call multiple times for the same user. Once a user has been deleted, subsequent calls with the same email or phone will return User not found without raising an error.

Response Structure

Status Code	Description	Example Response
200	User data deleted successfully	{"statusCode": 200, "message": "User data deleted successfully.", "data": null}
200	User not found (no matching record or identifiers do not resolve to the same user)	{"statusCode": 200, "message": "User not found.", "data": null}
400	Neither email nor phone was provided	{"statusCode": 400, "message": "Either email or phone is required.", "data": null}
400	id was not provided	{"statusCode": 400, "message": "User id is required.", "data": null}
400	A valid email address not provided	{"statusCode": 400, "message": "Email must be a valid format (e.g. user@example.com).", "data": null}
400	Phone number not provided in E.164 format	{"statusCode": 400, "message": "Phone number must be a valid E.164 format (e.g. +14155552671).", "data": null}
400	API key has insufficient access to delete users from any organization	{"statusCode": 500, "message": "Insufficient permission scope for this operation.", "data": null}
401	Missing or invalid API key	{"statusCode": 401, "message": "Unauthorized.", "data": null}
403	Requester's IP address is not whitelisted for the API key	{"statusCode": 403, "message": "Request IP address is not allowed for this API key.", "data": null}
403	API key has expired	{"statusCode": 403, "message": "API key has expired.", "data": null}
500	Internal server error	{"statusCode": 500, "message": "Internal server error.", "data": null}

Notes

1. The x-distinct-api-key will be shared with you by the Distinct team and must be included in every API request.
2. The request body must be sent as application/json with id and at least one of email or phone.
3. Optional fields should be omitted from the payload if there are no values — do not send them as empty strings or null.
4. Phone numbers must be in E.164 format (e.g. +14155552671). Do not include spaces, dashes, or parentheses.
5. When both email and phone are provided, both must match the same user for deletion to proceed.
6. Deletion permanently erases all PII fields (name, email, phone, date of birth, address, selfie image, waiver signature) while retaining the record for system integrity.
7. Optional IP allowlisting — You can share a list of IP addresses with the Distinct team to be whitelisted against your API key for an additional layer of security. When configured, requests from any other IP are rejected with 403.