Heap

Send events, user properties, and account properties to Heap for product analytics. Zeotap syncs your warehouse data to Heap via the Server-Side API, enriching your autocaptured dataset with server-side context.

Prerequisites

• A Heap account with a project configured
• Your Heap environment App ID (found in Account > Manage > Projects)

Authentication

Heap uses App ID authentication. The App ID is included in every API request body (not as an HTTP header).

1. In Heap, navigate to Account > Manage > Projects
2. Select your environment (e.g., Production)
3. Copy the App ID
4. Enter the App ID in Zeotap when configuring the destination

Note: Heap does not return authentication errors for invalid App IDs. Requests with incorrect App IDs are silently accepted. Verify your App ID is correct before running syncs.

Configuration

Target Settings

Supported Operations

Sync Modes

Heap’s Server-Side API is append/set-only. Events are always appended, and properties are overwritten on each call. There is no concept of deleting or updating previously sent events.

Audience Sync Modes

Heap does not have a list or segment membership API, so audience syncs are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Track Events: identity, event, timestamp, properties

User Properties: identity, email, properties

Account Properties: account_id, properties

How It Works

Track Events

Zeotap sends events to the Heap Bulk Track API (POST /api/track). Each batch request includes up to 1,000 events. The request body contains:

{
  "app_id": "YOUR_APP_ID",
  "events": [
    {
      "identity": "user@example.com",
      "event": "Purchase Completed",
      "timestamp": "2024-01-15T10:30:00Z",
      "properties": {
        "amount": "49.99",
        "currency": "USD"
      }
    }
  ]
}

User Properties

Zeotap sends user properties to the Heap Bulk Add User Properties API (POST /api/add_user_properties). Each batch includes up to 1,000 users:

{
  "app_id": "YOUR_APP_ID",
  "users": [
    {
      "identity": "user@example.com",
      "properties": {
        "plan": "Enterprise",
        "email": "user@example.com"
      }
    }
  ]
}

Account Properties

Zeotap sends account properties to the Heap Bulk Add Account Properties API (POST /api/add_account_properties). Each batch includes up to 1,000 accounts:

{
  "app_id": "YOUR_APP_ID",
  "accounts": [
    {
      "account_id": "acme-corp",
      "properties": {
        "industry": "Technology",
        "arr": "150000"
      }
    }
  ]
}

Rate Limits

Heap enforces the following rate limits:

Zeotap batches requests (up to 1,000 items per request) and includes automatic retry with exponential backoff for transient failures.

Best Practices

• Use the Bulk endpoints: Zeotap automatically batches rows into bulk API calls (up to 1,000 per request), minimizing API calls and staying within rate limits
• Use lowercase email key: To populate Heap’s built-in Email property on user profiles, map to the email field (lowercase). Other casings create custom properties instead
• Verify your App ID: Since Heap silently accepts requests with invalid App IDs, confirm your App ID by checking for data in Heap after the first sync
• ISO 8601 timestamps: Provide timestamps in ISO 8601 format (e.g. 2024-01-15T10:30:00Z) for accurate event timing
• Property value limits: Each property key and value must be a string or number with fewer than 1,024 characters

Troubleshooting

Events not appearing in Heap

Heap can take several minutes to process incoming server-side events. Check the Live View or Users section in Heap. If events still don’t appear after 15 minutes, verify your App ID is correct and that the identity matches an existing or new user.

Invalid App ID (no error returned)

Heap silently accepts requests with invalid App IDs (returns 200). Double-check your App ID in Account > Manage > Projects and ensure you are using the correct environment (Production vs. Development).

User properties not updating

Ensure the identity field value matches the identity Heap has for the user (case-sensitive). If the identity doesn’t exist, Heap creates a new user record that merges when events arrive.

Account properties require Account ID setup

Account properties require that Account ID tracking is configured in Heap. Navigate to Account > Manage > Account Tracking to verify your setup before syncing account data.

EU data center connection issues

If your Heap data is in the EU datacenter, make sure you selected European Union as the Data Center in Zeotap. Using the US endpoint for EU data will result in data being sent to the wrong environment.

Property values truncated or missing

Heap requires all property keys and values to be strings or numbers, each under 1,024 characters. Arrays are converted to pipe-delimited strings. Nested objects are not supported as property values.