---
title: Contentsquare Heap (Cloud)
slug: contentsquare-heap-cloud
docTags: 
createdAt: 2026-03-30T15:23:55.507Z
---

## Introduction

**Heap** (part of **Contentsquare**) is a digital analytics platform that automatically captures every user interaction — clicks, taps, form submissions, page views — and lets you retroactively define events without re-instrumenting your code. This destination sends events to Heap using the **server-side HTTP API**, making it immune to ad blockers and browser restrictions.

Use this destination alongside the [Heap device-mode destination](#) for maximum coverage.

## Getting Started

This is a cloud-mode destination. You will need:

- **App ID (Environment ID)** — found in **Account > Manage > Projects** in the Heap dashboard. Each project (environment) has its own App ID.

## Connecting to the Heap CDP Destination

:::hint{type="warning"}
Before connecting destinations in the Chord CDP, please verify with all Destination owners that all non-Chord CDP configured destinations are disabled. Running external destinations alongside configured Chord CDP destinations can result in duplicate events downstream.
:::

1. Log into the Chord data platform.
2. Navigate to the CDP.
3. Click the **"Add"** button next to Destinations.
4. Select **Heap** from the destination catalog.
5. Enter the destination name and **App ID**.
6. Optionally configure:
   - **Data Region** — `us` (default) or `eu`. Controls which Heap endpoint receives your events.
   - **Send Page Events** — if enabled (default), `page` events are forwarded to Heap as track events named `"Page View"`.
   - **Enable Anonymous User Profiles** — if enabled, events from anonymous users (no `userId`) are forwarded. Disabled by default.
7. Click **"Create"** to connect.

## Events

### Event Mapping

| Chord Event Type | Heap API Endpoint               | Notes                                                            |
| ---------------- | ------------------------------- | ---------------------------------------------------------------- |
| `track`          | `POST /api/track`               | Event name and properties forwarded as-is                        |
| `page`           | `POST /api/track`               | Sent as a `"Page View"` event if **Send Page Events** is enabled |
| `identify`       | `POST /api/add_user_properties` | User traits sent as Heap user properties                         |

### Track Events

Track events are forwarded to Heap's `/api/track` endpoint.

| Heap Field   | Chord Source (Priority Order)                      | Notes                                                       |
| ------------ | -------------------------------------------------- | ----------------------------------------------------------- |
| `app_id`     | Configured App ID                                  | Required                                                    |
| `identity`   | `userId` > `context.traits.email` > `traits.email` | If absent and anonymous profiles disabled, event is skipped |
| `event`      | `event` (event name)                               |                                                             |
| `properties` | `properties`                                       | All event properties forwarded                              |
| `timestamp`  | `timestamp`                                        | ISO 8601 format                                             |

### Page Events

If **Send Page Events** is enabled, page events are forwarded as track events named `"Page View"`.

| Heap Field   | Chord Source (Priority Order)                      | Notes                                                           |
| ------------ | -------------------------------------------------- | --------------------------------------------------------------- |
| `app_id`     | Configured App ID                                  | Required                                                        |
| `identity`   | `userId` > `context.traits.email` > `traits.email` | If absent and anonymous profiles disabled, event is skipped     |
| `event`      | *(hardcoded)* `"Page View"`                        |                                                                 |
| `properties` | `properties` merged with page context              | Includes `url`, `path`, `referrer`, `title` from `context.page` |
| `timestamp`  | `timestamp`                                        | ISO 8601 format                                                 |

If **Send Page Events** is disabled, page events are silently dropped.

### Identify Events

Identify events are sent to Heap's `/api/add_user_properties` endpoint to associate traits with a user.

| Heap Field   | Chord Source (Priority Order)                      | Notes                                                     |
| ------------ | -------------------------------------------------- | --------------------------------------------------------- |
| `app_id`     | Configured App ID                                  | Required                                                  |
| `identity`   | `userId` > `context.traits.email` > `traits.email` | Required; event is skipped if identity cannot be resolved |
| `properties` | `traits` merged with `context.traits`              | All user traits forwarded                                 |

:::BlockQuote
**Note:** 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.
:::

## Data Regions

| Region         | Endpoint                    |
| -------------- | --------------------------- |
| `us` (default) | `https://heapanalytics.com` |
| `eu`           | `https://heapanalytics.eu`  |

Set the **Data Region** option to `eu` if your Heap project is configured for EU data residency.

## Testing and Validation

After connecting the destination:

1. Trigger a test event from your storefront or use the **Live Events** tab in the Chord CDP
2. In Heap, navigate to **Account > Manage > Projects** and verify events appear in the event stream
3. Check the **Live Events** diagnostics in the Chord CDP for any API errors or credential issues

## Property Mappings

| Destination Path | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `properties.*`   | All event properties forwarded to Heap unchanged     |
| `traits.*`       | All user traits forwarded to Heap as user properties |