To delete a user from your Heap account, follow these instructions. These instructions apply to Heap data in both US and EU data centers.

Auth

All endpoints require an auth_token, which is obtained through HTTP Basic Authentication of an app_id and api_key, where app_id is the username and api_key is the password:

    Authorization: Basic <app_id>:<api_key>

Admins can generate and retrieve an API key by navigating to Account > Manage > Privacy & Security. If generated, the API key will be listed on that page. If it hasn't been generated yet, steps to generate a new API key are provided. For convenience, your app ID is also listed on this page.

🚧

Environment ID must be correct

The user deletion API checks all environments in your account for a matching user and deletes their records and data. The API auths using a combination of the environment id of your Main Production environment ( app_id ) and an api_key. Using any other environment id in the request will result in an Unauthorized response.

Once an auth_token is acquired, other endpoints can be accessed by passing the auth_token as a bearer token in the Authorization header:

    Authorization: Bearer <token>

API Endpoints

POST /api/public/v0/auth_token

This endpoint uses HTTP Basic Authentication to acquire a temporary auth_token from API credentials. The returned auth_token is used for authentication on the other endpoints.

Request

• Headers
  • Basic auth header: app_id:api_key

Response

• Code: 200 if credentials are valid.
• Body:
  • err (if unsuccessful)
  • access_token (if successful)

Example
Request:

    curl -X POST https://heapanalytics.com/api/public/v0/auth_token -u '<app_id>:<api_key>'

Response:

    { "access_token": "<access_token>" }

POST /api/public/v0/user_deletion

Submits users to be deleted from Heap, and returns a unique identifier for the request (deletion_request_id). Up to 10,000 users can be submitted in a single request.

Request

• Body:
  • users[]
    • user_id or identity
• Headers
  • Bearer auth header: auth_token
  • Content-type: Application/json

Response

• Status: 201 if successful, 401 if unauthorized

If unsuccessful:

• Body:
  • error (if unsuccessful)
  • message (human readable)
  • Maybe other fields (symbolic reason, code, etc.)

If successful:

• Body:
  • deletion_request_location: https://heapanalytics.com/api/public/v0/deletion_status/<deletion_request_id>
  • deletion_request_id: <deletion_request_id>
  • status: <deletion_request_status>

Example

Request:

curl -X POST https://heapanalytics.com/api/public/v0/user_deletion \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-type: Application/json' \
        -d '{ "users": [{ "user_id": 1 }, { "user_id": 2 }] }'

curl -X POST https://heapanalytics.com/api/public/v0/user_deletion \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-type: Application/json' \
        -d '{ "users": [{ "identity": "[email protected]" }, { "identity": "[email protected]" }] }'

Response:

{
  "deletion_request_location": "https://heapanalytics.com/api/public/v0/deletion_status/c93fae81-f67a-46d6-acf1-0c3ba1c3e5a6",
  "deletion_request_id": "c93fae81-f67a-46d6-acf1-0c3ba1c3e5a6",
  "status": "pending"
}

GET /api/public/v0/deletion_status/:deletion_request_id

Fetches the status of the user deletions submitted in the request identified by deletion_request_id.

Request

• Headers
  • Bearer auth header: token

Response

• Status: 200 if found, 404 if does not exist
• Body:
  • deletion_request_id
  • status (‘pending’ or ‘complete’)

Example
Request:

    curl -G https://heapanalytics.com/api/public/v0/deletion_status/<deletion_request_id> \
        -H 'Authorization: Bearer <token>'

Response:

    {
      "deletion_request_id": <deletion_request_id>,
      "status": pending
    }

Errors

Errors will manifest in the response code and on an err object in the response body.

Status Codes

• 200 - The request completed successfully
• 401 - Unauthorized. Occurs when the credentials are invalid for a specific request (e.g. bad api_key when requesting an auth_token, or requesting a user deletion in an env that the supplied auth_token does not authorize)
• 404 - Not found. Occurs when requesting a deletion_request_id that does not exist, or belongs to an env the auth_token does not authorize.

err Object

The err object will appear only when an error occurs, and will have the following properties:

• message - A human-readable description of the error
• Other properties may be present.

Did you find what you were looking for?