Send custom events to Heap that aren't automatically captured, such as purchase information, backend events, email sends, or completed transactions. Use this when you need to track server-side events or events that happen outside of the user's browser. Either identity or user_id is required, but not both. Event names are limited to 255 characters.

Send a custom event and update user properties in a single API call. This is useful for tracking events like user signup where you want to both record the event and attach user metadata (name, email, account tier, etc.) at the same time. Either identity or user_id is required, but not both.

Track multiple custom events efficiently in a batch. This is useful when you need to send many events at once, such as importing historical data, processing batch jobs, or syncing offline events. Note: This creates multiple API calls internally, one per event.

Link an anonymous user_id from the Heap SDK to a known identity (such as email address or user ID). When this is called, all events associated with the provided user_id are migrated to the user with the provided identity. This enables you to track users across sessions, devices, and browsers. IMPORTANT: Only 1 identity can be mapped to a user_id. Maximum of 10 different user_ids can be mapped to one identity within a one-month period. Subsequent calls that exceed these limits are ignored.

Attach custom properties to identified users from your server, such as Sign Up Date (in ISO8601 format), Total Transactions Completed, Total Dollars Spent, Subscription Tier, Account Type, etc. These properties are associated with all of the user's past activity and future activity. Properties are stateless - only the most recent value is stored. Heap will create a new property if it doesn't exist, or overwrite the previous value if one exists with the same name. IMPORTANT: To write to the built-in Email property, use lowercase 'email' as the key. Rate limit: 30 requests per 30 seconds per identity per app_id.

Attach custom properties to a single account for B2B analytics and account health analysis. Use this to send account-level properties like payment tier, account owner, account name, company size, subscription status, renewal date, etc. You must configure the Account ID setting in Heap before using this API. As your accounts and properties change, periodically call this API with the account ID and updated properties. This is useful for measuring account health and analyzing B2B customer behavior.

Attach custom properties to multiple accounts at once for efficient B2B data enrichment. Use this when you need to update many accounts, such as importing account data from your CRM, syncing subscription changes, or updating account health scores across your customer base. Maximum of 1000 accounts per request. Each account object must have an account_id and properties object.

Associate a user with an account for B2B account-level analytics. This enables you to analyze behavior at the account level (e.g., which accounts are most engaged, which accounts are at risk of churn). The account_id must match an account that has been configured in Heap. Use this after identifying a user to establish the user-to-account relationship.

Obtain a temporary authentication token for the User Deletion API. This token is required before calling Delete Users or Check Deletion Status. The token expires in 5 minutes. Uses HTTP Basic Authentication with your app_id and api_key. IMPORTANT: The app_id must be from your Main Production environment - other environment IDs will result in an Unauthorized response. The deletion API checks all environments in your account.

Submit users for deletion from your Heap account to comply with GDPR and data privacy regulations. This API checks all environments in your account and deletes user records and data across all of them. You can submit up to 10,000 users in a single request using either user_id or identity. Returns a deletion_request_id that you can use to check the deletion status. IMPORTANT: You must first call Get Auth Token and use the returned access_token as a bearer token for this request. The deletion process may take time to complete - use Check Deletion Status to monitor progress.