--- title: Heap API Integration on Truto slug: heap category: Analytics canonical: "https://truto.one/integrations/detail/heap/" --- # Heap API Integration on Truto **Category:** Analytics **Status:** Generally available ## MCP-ready AI tools Truto exposes 7 tools for Heap that AI agents can call directly. - **create_a_heap_event** — Send a custom server-side event to Heap, such as backend order/transaction info or events not capturable client-side. Returns an empty JSON object on success. Requires app_id and event; you must supply either identity or user_id, but not both. - **update_a_heap_identity_by_id** — Identify a Heap user by mapping an anonymous SDK user_id to a known identity such as an email, migrating all associated events to that identity. Returns an empty JSON object on success. Requires app_id, user_id, and identity. Heap allows only 1 identity per user_id and at most 10 user_ids per identity in a one-month window; extra calls are ignored. - **update_a_heap_user_by_id** — Attach custom key-value properties to an identified Heap user from your servers; unknown identities are created as new users and existing properties are overwritten by name. Returns an empty JSON object on success. Required: app_id, identity. - **update_a_heap_account_by_id** — Attach or update custom account properties for one or more accounts in Heap. Returns a plain-text 'OK' success acknowledgment with no structured body. Required: app_id, plus either account_id and properties (single-account update) or accounts (bulk update). - **create_a_heap_auth** — Create a temporary Heap auth token by exchanging API credentials via HTTP Basic Authentication. Returns: access_token. - **create_a_heap_user_deletion** — Submit up to 10,000 users for deletion from Heap. Returns: deletion_request_location, deletion_request_id, status, access_token. Required: users — each entry needs user_id or identity. Deletion is asynchronous; poll the deletion status endpoint with the returned deletion_request_id. - **get_single_heap_user_deletion_by_id** — Get the status of a user deletion request in Heap by id. Returns: deletion_request_id, status, access_token. Required: id — the deletion_request_id returned when the deletion was submitted. ## How it works 1. **Link your customer's Heap account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Heap.** The Proxy API is a 1-to-1 mapping of the Heap API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Enrich Heap with Server-Side Billing Events** — Subscription and billing platforms can push backend events like upgrades, downgrades, and payment failures into their customers' Heap workspaces, so Product teams can correlate revenue outcomes with frontend behavior. - **Close the Loop on Email and Campaign Attribution** — Marketing automation and lifecycle tools can stitch email identities to anonymous Heap visitors and log server-side campaign events, giving mutual customers a true end-to-end funnel from email click to in-product activation. - **Sync Customer Health and Firmographics for Account-Level Analysis** — CRM, CS, and data enrichment tools can bulk-sync account traits (ARR, plan tier, health score) and user traits (role, title) into Heap, unlocking B2B cohort analysis and letting PMs filter sessions by at-risk or high-value accounts. - **Automate GDPR/CCPA Deletion Workflows** — Privacy and trust platforms can programmatically submit bulk user deletion requests to Heap and poll for completion, delivering zero-touch Right to Be Forgotten compliance with auditable proof for mutual customers. ## What you can build - **Server-Side Event Forwarding** — Pipe backend events (payments, API usage, email engagement) into a customer's Heap workspace using create_a_heap_event, keyed to either a known identity or anonymous user_id. - **Identity Stitching on Form Submit** — Automatically call update_a_heap_identity_by_id when a lead fills out a form or logs in, merging anonymous browsing history into the known user profile. - **Nightly Account Trait Sync** — Schedule bulk update_a_heap_account_by_id jobs to refresh firmographics, plan tier, MRR, and health scores so Heap's account objects stay aligned with your source of truth. - **User Profile Enrichment** — Push custom user traits like role, lifecycle stage, or feature entitlements into Heap via update_a_heap_user_by_id, auto-creating profiles for identities Heap hasn't seen yet. - **Automated Right-to-Be-Forgotten Pipeline** — Batch deletion requests through create_a_heap_user_deletion and run background polling against get_single_heap_user_deletion_by_id to confirm completion and generate audit logs. - **Self-Serve Heap Connection Flow** — Let end users connect their Heap workspace through a managed auth flow using create_a_heap_auth, so your product can start writing events and traits without customers hand-managing API keys. ## FAQs ### How do end users authenticate their Heap account? Truto handles the Heap connection through create_a_heap_auth, which captures the credentials needed to write events, identities, users, and accounts into the end user's Heap workspace. Your product never has to store or rotate Heap API keys directly. ### What are the limits on identity mapping? Heap enforces strict identity rules: each anonymous user_id can be mapped to only 1 identity, and a single identity can accept a maximum of 10 user_ids within a rolling 30-day window. Integrators should design identity stitching logic to respect these limits and handle rejections gracefully. ### Can I send events for users who aren't yet identified? Yes. create_a_heap_event requires either a known identity (e.g., email) or an anonymous user_id generated by Heap's web SDK. This lets you log backend events for both logged-in users and anonymous visitors tied to a browser session. ### How are user and account updates handled if the record doesn't exist yet? update_a_heap_user_by_id will automatically create a new user profile when called with an identity Heap hasn't seen before. update_a_heap_account_by_id supports bulk property updates and returns a simple 'OK' acknowledgment, making it ideal for nightly firmographic syncs. ### Is user deletion synchronous? No. create_a_heap_user_deletion accepts up to 10,000 users per request and is processed asynchronously. You'll receive a deletion_request_id that must be polled via get_single_heap_user_deletion_by_id until the status resolves — Truto makes it straightforward to orchestrate this polling loop. ### Can I read analytics data (events, funnels, reports) back from Heap? The current tool inventory is write-focused — sending events, updating identities, users, and accounts, and managing deletions. If you need read access to Heap data, Truto builds integrations on request, so reach out and we can scope additional endpoints. ## Related reading - [Connect Heap to Claude: Enrich User Profiles and Govern Data](https://truto.one/blog/connect-heap-to-claude-enrich-user-profiles-and-govern-data/) — Learn how to build a secure MCP server for Heap to give Claude read and write access to product analytics, user identities, and account telemetry.