Heap User Management API Guide

Auth method: API key (app_id passed in request body as JSON field; no Authorization header)

Setup steps

1. Log in to Heap and navigate to Account > Privacy & Security > API.
2. Copy your app_id (environment ID) from the Heap dashboard.
3. Include the app_id field in every server-side API request body as a top-level JSON key.
4. No OAuth flow or bearer token is used for the server-side API.

Track server-side event

• Method: POST
• URL: https://heapanalytics.com/api/track
• Watch out for: Returns 200 even for malformed payloads in some cases; validate identity and app_id carefully.

Request example

{
  "app_id": "11",
  "identity": "user@example.com",
  "event": "Subscription Upgraded",
  "properties": { "plan": "pro" }
}

Response example

HTTP 200 OK
{}

Identify / alias user

• Method: POST
• URL: https://heapanalytics.com/api/identify
• Watch out for: Calling identify ties all prior anonymous sessions to the identity; cannot be undone via API.

Request example

{
  "app_id": "11",
  "identity": "user@example.com",
  "properties": { "role": "admin" }
}

Response example

HTTP 200 OK
{}

Add user properties

• Method: POST
• URL: https://heapanalytics.com/api/add_user_properties
• Watch out for: Properties are additive/overwrite on key collision; there is no partial-update or delete for individual property keys via this endpoint.

Request example

{
  "app_id": "11",
  "identity": "user@example.com",
  "properties": { "plan": "enterprise", "company": "Acme" }
}

Response example

HTTP 200 OK
{}

Batch track events

• Method: POST
• URL: https://heapanalytics.com/api/batch_track
• Watch out for: Maximum 1,000 events per batch request. Exceeding this limit may result in dropped events.

Request example

{
  "app_id": "11",
  "events": [
    {"identity":"u1@x.com","event":"Login","properties":{}},
    {"identity":"u2@x.com","event":"Login","properties":{}}
  ]
}

Response example

HTTP 200 OK
{}

Delete user (GDPR/CCPA)

• Method: POST
• URL: https://heapanalytics.com/api/delete_user
• Watch out for: Deletion is asynchronous and irreversible. All event history associated with the identity is removed.

Request example

{
  "app_id": "11",
  "identity": "user@example.com"
}

Response example

HTTP 200 OK
{}

• Rate limits: Heap does not publish explicit rate limit numbers in official documentation. Requests that exceed undisclosed limits may be throttled or dropped silently.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: No rate-limit headers or retry-after headers are documented. Heap recommends batching events (up to 1,000 per batch call) to reduce request volume.
• Pagination method: none
• Default page size: 0
• Max page size: 0
• Pagination pointer: Not documented

• Webhooks available: No
• Webhook notes: Heap does not offer outbound webhooks for user-management events in its documented API surface.
• Alternative event strategy: Use Heap's data connectors (Redshift, BigQuery, Snowflake) or the Heap Connect feature to export event and user data to a warehouse for downstream processing.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: Provisioned via Okta SCIM integration (Okta-hosted SCIM connector); Heap does not publish a standalone SCIM base URL in public docs.

• Supported operations: Create user, Deactivate user, Update user attributes, Push groups (via Okta)

Limitations:

• SCIM provisioning is only documented for Okta; Entra ID, Google Workspace, and OneLogin are not officially supported.
• SSO (SAML) must be configured before enabling SCIM.
• Enterprise plan required.
• SCIM base URL and bearer token are obtained from within the Okta Heap app configuration, not from Heap's developer portal.
• Group-to-role mapping capabilities are limited; consult Heap support for role assignment via SCIM.

Three integration patterns cover the primary lifecycle operations. First, SCIM provisioning via Okta: requires an active Enterprise plan with SAML SSO already configured; the SCIM bearer token is managed inside the Okta app config, not Heap's developer portal - if SSO is absent, SCIM calls will fail silently.

Second, server-side identity enrichment: POST to /api/identify immediately after sign-up to anchor anonymous sessions to a known identity, then use /api/add_user_properties for subsequent attribute updates. properties overwrite on key collision, so send only the keys you intend to change.

Third, GDPR/CCPA deletion: POST to /api/delete_user with the exact identity string used at track/identify time - deletion is asynchronous, irreversible, and case-sensitive, so 'User@Example. com' and 'user@example.

com' resolve to different identities.

Provision a new user via SCIM (Okta)

1. Ensure Heap Enterprise plan is active and SAML SSO is configured in Okta.
2. In Okta, add the Heap application and navigate to the Provisioning tab.
3. Enable SCIM provisioning; Okta will use the SCIM 2.0 endpoint and bearer token provided in the Heap Okta app config.
4. Assign the user to the Heap Okta app; Okta sends a SCIM POST /Users request to create the user in Heap.
5. Verify the user appears in Heap's People section.

Watch out for: If SSO is not yet configured, SCIM provisioning will fail. SCIM bearer token is managed inside Okta, not Heap's developer portal.

Enrich user profile with server-side properties after sign-up

1. After a user completes sign-up in your backend, POST to https://heapanalytics.com/api/identify with the user's email as identity and initial properties (plan, role).
2. Subsequently POST to https://heapanalytics.com/api/add_user_properties to add or update additional attributes (e.g., company, subscription tier).
3. Confirm properties appear in Heap's user profile within a few minutes.

Watch out for: Properties are overwritten on key collision; send only the keys you intend to update to avoid accidentally clearing existing values.

Delete a user for GDPR compliance

1. Receive a data deletion request for a user identified by their email.
2. POST to https://heapanalytics.com/api/delete_user with app_id and the user's identity string.
3. Log the 200 response and timestamp for compliance records.
4. Note that deletion is asynchronous; confirm with Heap support if immediate verification is required.

Watch out for: Deletion is irreversible. Ensure the identity string exactly matches what was used during identify/track calls (case-sensitive).

The silent-200 response pattern is the most dangerous integration trap: malformed payloads, wrong app_id values, and unrecognized identity strings can all return 200 with no error body, making broken pipelines invisible without external validation.

The write-only API surface means any identity graph enrichment or user-state reconciliation must be routed through Heap Connect or a warehouse export (Redshift, BigQuery, Snowflake) - there is no read endpoint to confirm what Heap has stored for a given identity.

Rate limits are undisclosed and carry no retry-after headers, so batch_track's 1,000-event cap per request is the only documented ceiling; exceeding it may result in silent event drops with no observable signal.

SCIM's Okta-only constraint means teams building identity graph pipelines on Entra ID or other providers cannot rely on SCIM and must instrument lifecycle events entirely through the server-side API with all the validation burden that entails.