> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Heap

> Integration details and setup guide for the Heap connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                        |
| ----------------------------------- | ---------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Client Credentials)                 |
| **Two-Way Sync**                    | No                                             |
| **Events Supported**                | No                                             |
| **Realtime**                        | No (Polling)                                   |
| **Supports Rate Limiting**          | Yes                                            |
| **Authentication Scopes Supported** | N/A (Client Credentials grant full API access) |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Heap**:

* **Events**
* **Users**
* **Accounts**
* **Segments**
* **Funnels**
* **Analytics Data**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                  |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Heap offers a free tier with limited features and data retention. Sign up at [https://heap.io/](https://heap.io/). |
| **Requires paid sandbox?**                         | No. You can use the free tier or your production account for testing.                                                   |
| **Requires partnership to obtain authentication?** | No. API access is available to all Heap customers.                                                                      |

***

### Authentication (OAuth 2.0 Client Credentials)

Heap uses OAuth 2.0 Client Credentials flow, which is suitable for server-to-server authentication.

#### Obtain your API credentials

1. Log in to your Heap account at [https://heapanalytics.com](https://heapanalytics.com)
2. Navigate to **Account Settings** → **Projects**
3. Select the project you want to integrate with
4. Go to **APIs & Integrations** or **Account** → **Manage** → **API**
5. Look for the **API Access** section
6. Generate new API credentials if needed:
   * Click **Generate API Key** or **Create New Token**
   * You'll receive a **Client ID** and **Client Secret**
7. Copy both the **Client ID** and **Client Secret**
8. **Important**: Store these credentials securely—they provide full access to your Heap analytics data

#### Token Exchange

Heap uses the OAuth 2.0 Client Credentials flow:

* Token URL: `https://heapanalytics.com/api/public/v0/auth_token`
* Content-Type: `application/json`
* Authentication Method: `client_secret_basic` (credentials sent in Authorization header)
* The API will return an access token that should be used for subsequent requests

#### Getting Started

* **Sign up for Heap**: [https://heap.io/](https://heap.io/)
* **Heap Dashboard**: [https://heapanalytics.com](https://heapanalytics.com)
* **API Documentation**: [https://developers.heap.io/reference](https://developers.heap.io/reference)
* **Getting Started Guide**: [https://help.heap.io/](https://help.heap.io/)

***

## Use Cases

### 1) Product analytics data pipeline

Export user behavior events, session data, and conversion funnels from Heap into your data warehouse for custom analysis, cross-platform reporting, and integration with other business intelligence tools.

### 2) Customer segmentation sync

Pull Heap user segments and behavioral cohorts into your marketing automation platform or CRM to trigger personalized campaigns based on product usage patterns and engagement metrics.

### 3) Event tracking validation

Automatically compare events tracked in Heap against your event tracking specification to identify missing events, incorrect properties, or implementation gaps across your digital properties.

### 4) User journey analysis

Extract sequential event data to build comprehensive user journey maps that combine Heap's automatic event tracking with data from other customer touchpoints in your ecosystem.

### 5) A/B test results integration

Sync A/B test results, statistical significance data, and winning variants from Heap to your experiment tracking system or product roadmap tools for centralized experiment management.

***

## API Gotchas

* **Client Credentials flow**: Heap uses OAuth 2.0 Client Credentials instead of the more common Authorization Code flow. This means tokens are obtained server-to-server without user interaction, making it ideal for backend integrations.

* **Access token expiration**: Access tokens have a limited lifetime and must be refreshed periodically. Implement automatic token refresh logic to prevent authentication failures during long-running operations.

* **Rate limiting**: Heap enforces rate limits on API requests to ensure system performance. Monitor rate limit headers in responses and implement exponential backoff when you approach or hit limits.

* **Data export delays**: Analytics data in Heap may have processing delays, especially for recent events. When pulling data for real-time use cases, account for potential latency between event occurrence and API availability.

* **Query complexity limits**: Complex queries with multiple filters or large date ranges may timeout or return partial results. Break large data requests into smaller chunks and implement pagination for reliable data extraction.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.