> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/analytics/heap/heap-server.md). # Heap server This destination sends events to Heap using the server-side HTTP API, so it is not affected by ad blockers or browser restrictions. Heap is part of Contentsquare. See [Heap](/activate/event-streaming/destinations/analytics/heap.md) for how this version and the [Heap browser](/activate/event-streaming/destinations/analytics/heap/heap-browser.md) version fit together. ## Getting started You need one value: * **App ID (Environment ID)**: found in **Account > Manage > Projects** in the Heap dashboard. Each project (environment) has its own App ID. ## Settings * **Destination Name** (required): a name to tell this destination apart. * **App ID** (required): your Heap Environment ID, found in **Account > Manage > Projects** in the Heap dashboard. * **Data Region** (optional): send events to the US or EU Heap endpoint. Enter `us` (default) or `eu`. Set it to `eu` if your Heap project uses EU data residency. * **Send Page Events** (optional): if on, `page` events are forwarded to Heap as track events named `"Page View"`, or `"Page View - "` followed by the page name when the event has one. On by default. If off, page events are silently dropped. * **Enable Anonymous User Profiles** (optional): if on, events from anonymous users (no `userId`) are forwarded. Off by default. * **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md). ## Connect Add **Heap** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps. ## Event mapping | Chord event | Heap event | Notes | | ----------- | ------------------------------- | --------------------------------------------------------------------------- | | `track` | `POST /api/track` | Event name and properties forwarded as-is. Skipped if the event has no name | | `page` | `POST /api/track` | Sent as a `"Page View"` event if **Send Page Events** is on | | `identify` | `POST /api/add_user_properties` | User traits sent as Heap user properties | Other event types are not sent. **Track events** | Chord source (priority order) | Heap field | Notes | | ------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------- | | Configured App ID | `app_id` | Required | | `userId` > `context.traits.email` > `traits.email` > `anonymousId` | `identity` | `anonymousId` is used only when **Enable Anonymous User Profiles** is on. If nothing is found, the event is skipped | | `event` (event name) | `event` | | | `properties` | `properties` | All event properties forwarded | | `timestamp` | `timestamp` | Sent as received | **Page events** If **Send Page Events** is on, page events are forwarded as track events. | Chord source (priority order) | Heap field | Notes | | --------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- | | Configured App ID | `app_id` | Required | | `userId` > `context.traits.email` > `traits.email` > `anonymousId` | `identity` | `anonymousId` is used only when **Enable Anonymous User Profiles** is on. If nothing is found, the event is skipped | | `"Page View - "` followed by `name`, or `"Page View"` when there is no name | `event` | | | `properties` | `properties` | All event properties forwarded. Page details from `context.page` are not added | | `timestamp` | `timestamp` | Sent as received | **Identify events** Identify events are sent to Heap's `/api/add_user_properties` endpoint to associate traits with a user. | Chord source (priority order) | Heap field | Notes | | -------------------------------------------------- | ------------ | ------------------------------------------------------------------------- | | Configured App ID | `app_id` | Required | | `userId` > `context.traits.email` > `traits.email` | `identity` | Required. The event is skipped if identity cannot be resolved | | `traits` merged with `context.traits` | `properties` | All traits forwarded except `email`. If a trait is in both, `traits` wins | {% hint style="info" %} Heap's `add_user_properties` endpoint requires a resolved identity. Identify events without a `userId` or email are always skipped, regardless of the **Enable Anonymous User Profiles** setting. {% endhint %} ## Custom events Every track event is sent to Heap under its own name, with all its properties. ## Data regions Any value other than `eu` sends to the US endpoint. | Region | Endpoint | | -------------- | --------------------------- | | `us` (default) | `https://heapanalytics.com` | | `eu` | `https://c.eu.heap-api.com` | ## Testing and validation After connecting the destination: 1. Trigger a test event from your storefront, or use [Live events](/activate/event-streaming/live-events.md) in Chord. 2. In Heap, go to **Account > Manage > Projects** and verify events appear in the event stream. 3. Check the Live events diagnostics in Chord for any API errors or credential issues. ## Property mappings [Property mappings](/activate/event-streaming/property-mappings.md) on the connection run before this destination. A mapping to `properties.customer_type` reaches Heap as an event property, and a mapping to `traits.plan` reaches Heap as a user property on identify events. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.chord.co/activate/event-streaming/destinations/analytics/heap/heap-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.