# Heap

## Overview

Heap is a popular web analytics platform that allows you to capture and measure minute user actions on your website or mobile application.
You can use this connector to send server-side data to Heap including user and account properties to enrich your auto-captured dataset.
This connector also includes client-side equivalents of several of Heap's server-side APIs (such as 'Track' and 'Add User Properties'). You are also able to delete users from your Heap workspace.

> **Info:** \*\*API INFO: \*\*The Base URL used for the heap connector is **<https://heapanalytics.com>**. More information can be found on their main [API documentation (v1.0)](https://developers.heap.io/reference/server-side-apis-overview) site.

## Authentication

> **Info:** Please note that authentications are only mandatory for the "Heap data out" trigger and for the "Delete" operations.

Within the builder, click on the Heap connector to display the connector properties panel. Select the 'Authentication' tab and click on the 'New authentication' button.
In the Tray.io authentication pop-up modal name the authentication in a way that will easily identify it within a potentially large list. For example, whether it is a Sandbox or Production auth, etc.
Consider who / how many people will need access to this authentication when choosing where to create this authentication ('Personal' or 'Organisational'). Select the relevant service.
The second page asks you for your 'App ID' and 'API Key':
![heap-auth](https://tray.ai/documentation/images/connectors/service/heap/2krVQiyt0v4YFwAEA5fL7Y_heap-auth.png)
Both can be found within the left hand side menu via: 'Administration' -> 'Account' -> 'Manage' -> 'Privacy & Security'.
Select the 'Use the API' tab. If you have already generated an API key it will simply display the date it was generated.
![heap-app-id-key](https://tray.ai/documentation/images/connectors/service/heap/1cdDEjSCziAWbZaavGGIqm_heap-app-id-key.png)
Once you have added these fields to your Tray.io authentication pop-up window, click the 'Create authentication' button.
Your connector authentication setup should now be complete.

## Heap Triggers

The Heap trigger's allow you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.
Note that there are two types of Heap triggers:

* **Heap**: This trigger is best used for when you want Heap to react to data collection events.
* **Heap (data out)**: This trigger is best used for when you want to synchronise users being added and removed from segments with another service.

### Heap

***

> **Warning:** Make sure to **select the correct 'Heap' trigger** (i.e. NOT 'Heap data-out').

> **Info:** Authentication is not required in order to use this trigger

**The 'Heap trigger' requires the webhook integration to be set up using the Heap UI as well as a Tray.io based authentication**.
For further instructions on how to setup the trigger follow the steps below.
Notice that within the Heap Input tab of the property panel there are no options available to you. This is because they are set up through the Heap UI.

### 1 - Tray authentication

To create a Tray.io based authentication follow the connector Authentication walkthrough above for more details on how to acquire the *API ID* and the *API Key*.
![heap-trigger-auth-1](https://tray.ai/documentation/images/connectors/service/heap/5QfnJNuXciViDQg4AkVLg2_heap-trigger-auth-1.png)

### 2 - Heap integration

1. Once you have selected your Heap trigger copy the 'Workflow public URL' (found under the setting icon).
2. Within the Heap UI head to the left-hand menu and under 'Administration' select 'Integrate' followed by 'Webhooks'.
3. Here you can create/ edit your current webhooks. Simply paste the 'Workflow public URL' into the 'Basic Configuration' section and add your HTTP headers (if relevant).
4. The 'Data to send' section sends your selected JSON data fields in the HTTP body of each request. Any properties not present upon triggering an event are replaced with empty string values.
5. Note that you can have more than one triggering event.
6. Make sure your changes are saved and your Tray.io workflow is \*\*enabled \*\*before testing your trigger.
   ![heap-trigger-setup](https://tray.ai/documentation/images/connectors/service/heap/2IKIG6PFbjgD8ZrNktBK06_heap-trigger-setup.png)

### Heap (data out)

> **Warning:** Make sure to **select the correct 'Heap' trigger** (i.e. NOT 'Heap', it must be "Heap data out').

**The 'Heap (data out) trigger' requires the webhook integration to be set up using the Heap UI as well as a Tray.io based authentication**.
**You must also have a website that already has Heap integrated**. For more details on how this is accomplished follow [this](https://developers.heap.io/docs/web) link.
Notice that within the Heap Input tab of the property panel there are no options available to you. This is because they are set up through the Heap UI.
For further instructions on how to setup the trigger follow the steps below.

### 1 - Tray authentication

1. Once you have selected your Heap (data out) trigger and named it the second page will automatically have 'Segment' checked for you.
2. Click on 'Create authentication' and a new pop up model will appear.
3. Once you are signed in, make sure to select the correct environment otherwise your authentication won't work.
   ![heap-trigger-2-tray](https://tray.ai/documentation/images/connectors/service/heap/4cWMZUqOvcbv9rVT09gnN_heap-trigger-2-tray.png)

### 2 - Heap integration

1. Within you main Heap dashboard head to the left-hand menu and under 'Data management' select 'Definitions' followed by 'Segments'.
2. Select the relevant segment from the options available. If none exist create one that is relevant to your needs. The example here is based on 'Page views'.
3. Within your chosen segment under the sub-heading 'Integrations' you will see 'Tray' listed. Click on the toggle.
4. Decide when and how you want to sync your Heap - Tray integration. This can be immediate and / or recurring.
   ![heap-trigger-2-tray-heap](https://tray.ai/documentation/images/connectors/service/heap/aRPwKx9aHAT9JmaRLRDwo_heap-trigger-2-tray-heap.png)

## Heap terminology

We have outlined below some of the more frequently used Heap terminology:

### Segments

A segment in Heap is any subset of users based on particular criteria defined by you.
Examples of popular types of segments include 'Internal users', 'Frequent buyers', 'European visitors', etc.
![heap-segment-form-fillers](https://tray.ai/documentation/images/connectors/service/heap/1kraEXH4iqXQLgzmvojjA2_heap-segment-form-fillers.png)

### Events

Events are the basic building blocks of reports.
An event is any action associated with a user.
Examples of events you can define in Heap include 'Create Account', 'Login' or 'Received Transactional Email'
![heap-event-eg](https://tray.ai/documentation/images/connectors/service/heap/Qz3CvdlzheobhGrmxEgzL_heap-event-eg.png)

### Environment ID

These are the environments you set up within your Heap project, such as 'Staging', 'Production' etc.
They are found within the left hand side menu via: 'Administration' -> 'Account' -> 'Manage' -> 'Projects'.
Click on the current project or create a new one to view all environment IDs available.
![heap-env-ids](https://tray.ai/documentation/images/connectors/service/heap/4SgYdb1wFgRDWb5HTsrN5j_heap-env-ids.png)

### Account ID

All users associated with 'this' Account ID are grouped into the corresponding Account.
If you do not already have account data within your Heap account you can use the ['Add Account properties'](#add-account-properties) operation to create some.
After you’ve added your account data in Heap navigate to 'Administration' -> 'Account' -> 'Manage' -> 'Features'.
It is the user property you set that denotes the 'Account ID':
![heap-account-id-prop](https://tray.ai/documentation/images/connectors/service/heap/1vDKWfA00UwcoEjyBpwuoK_heap-account-id-prop.png)

### User Identifiers

When selecting a user identifier you will generally use either:

* Email address
* Autogenerated ID pulled in from the originating service (e.g. Salesforce ID or HubSpot ID)
  By using either of these as your user identifier in Heap, any updates coming from the originating service will be able to auto-identify the correct user.
  Places where you set your user identifier include during the Tray.io - Heap App integration stage. As explained in the Heap Triggers: Heap (data out) section below.
  User identifiers are used in the 'Identity' property reference within certain operations such as 'Delete users' and 'Add User Properties'.

### Account properties

Account properties can be used to capture additional data about an account such as 'CEO', 'Turnover' etc.
You can define them through the Heap UI or via the 'Add user properties' operation.
![heap-account-props](https://tray.ai/documentation/images/connectors/service/heap/6drIrirkKrjL1meRjDSmyn_heap-account-props.png)

### User properties

User properties can be used to capture additional data about a user such as first and last name, email address, timezone, and account plan.
You can define them through the Heap UI or via the 'Add Account properties' operation.
![heap-user-props](https://tray.ai/documentation/images/connectors/service/heap/7I1i0WZ2dtzK1glV70oQWr_heap-user-props.png)

### Note on Environment ID

This property value is necessary for three operations: 'Add user properties', 'Add Account Properties', and 'Track event'.
The easiest way to find this information is via your Heap URL. It is the value found after the `env/` section.
Make sure you remove any/ all trailing slashes before adding the value to your property panel.

> **Warning:** IMPORTANT!: Notice that your Heap Environment ID is referred to as your `"app_id"` within your returned Heap payload

![heap-url](https://tray.ai/documentation/images/connectors/service/heap/1O4cx6dzjeMY0QxBV7OiK1_heap-url.png)
If you are not sure which environment ID to use or which project you are using note that all possible options are located within the 'Projects' tab.

## Example Uses

> **Info:** Tray is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray and the heap connector.

The following examples highlight different valuable use cases with the Heap connector.

1. Form Submission (event trigger): A simple Heap trigger workflow demonstrating how you can use Heap to update a Google spreadsheet with user form data.
2. Lead Enrichment: Explains how to combine new user data coming in from multiple services and send it all to Heap.
3. Delete Heap Users: A best practices workflow concerning user deletion and status checking.

### Form Submission (event trigger)

**EXTRA AUTHS**: In order to complete this workflow, you will also need to be authenticated with the [Google sheets](#) connector.
This workflow consists of two steps including the Heap trigger. It is a very simplistic version of how you may wish to automatically capture Heap form data and send it to another third-party service.

#### End Result

![heap-trigger-end-results](https://tray.ai/documentation/images/connectors/service/heap/tAN664JSrK1EFrXgEXVdZ_heap-trigger-end-results.png)

#### Step-by-step breakdown

### Set up Heap Trigger

Make sure to select the correct 'Heap' trigger (i.e. **NOT 'Heap data-out'**).
You will need to make sure that your trigger is properly set up vis the Heap UI as opposed to authenticating within the Tray.io builder.
In this case the chosen trigger event is a 'Submit search form' event. Yours will need to be relevant to your own Heap account setup.
![heap-trigger-step-01](https://tray.ai/documentation/images/connectors/service/heap/7Le1OOAJ0tbXA4i0GCpDSe_heap-trigger-step-01.png)

### Autopopulate Google Spreadsheet

Add a Google sheets connector. Make sure your spreadsheet has already been set up so you can input the 'Spreadsheet ID' directly.
The same goes for when you chose which worksheet to populate. If your setup is correct you will be able to choose from the dropdown options available under 'Worksheet name'.
The properties will now auto-populate the Google spreadsheet with their location details every time someone submits a search query with Heap.
![heap-trigger-step-2](https://tray.ai/documentation/images/connectors/service/heap/2qQhe7dFuYHX1sy95Nfct_heap-trigger-step-2.png)

### Lead Enrichment

**EXTRA AUTHS**: In order to complete this workflow, you will also need to be authenticated with the [Clearbit](https://tray.ai/documentation/connectors/service/clearbit/) connector.
Often user data comes in many formats and from various third-party sources. The great thing about Heap is that once that information is combined it can be analysed.
This example shows how you can use Heap in combination with Clearbit to help generate Lead enrichment for you and your company.
A unique third-party service survey is filled in and Clearbit cross combines their email address as a unique identifier to see what other information can be gathered about them. This is then sent to Heap for analysis.
With the expectation that if there are any new values for the properties found/ created for said user they will be automatically updated when sent to Heap.

#### End Result

![heap-clearbit-end-results](https://tray.ai/documentation/images/connectors/service/heap/7iYO8ezk6yeQ5RMxaLIQ4U_heap-clearbit-end-results.png)

#### Step-by-step breakdown

### 3rd party survey details

In this example we used the Webhook trigger to send dummy data to the Heap workflow. The operation is set to 'Auto respond with HTTP 200'.
Below is some mock data you can also use.
You can of course replace this trigger with another service that suits your needs. So long as **the information is sent in an array format** it should work as expected.

```json
[
  \{
    "survey_id": "NewSurvey1234567890",
    "age": 48,
    "name": "Andrew O'Neal",
    "gender": "male",
    "company": "URBANSHEE",
    "email": "andrew@clearbit.com",
    "phone": "+1 (813) 473-3644",
    "address": "297 Aberdeen Street, Iola, Montana, 4937",
    "suggestions": "I would really like to see a wider range of adult cartoon content\r\n",
    "registered": "2017-04-25T11:57:39 -02:00",
    "device_used": "Laptop",
    "avg_daily_viewing": "3",
    "favoriteShow": "Arcane"
  \}
]

```

![heap-clearbit-step-1](https://tray.ai/documentation/images/connectors/service/heap/5imV3ujVyFjd8MEcpvUucy_heap-clearbit-step-1.png)

### Collect Clearbit info

This step uses the email information given in the survey prior to cross-referencing the Clearbit database.
If any information is found associated with the email address submitted then Clearbit will return everything they have associated with it.
![heap-clearbit-step-02](https://tray.ai/documentation/images/connectors/service/heap/5eIKDGYIgiDg8X3lXeoRL8_heap-clearbit-step-02.png)

### Add user properties to Heap

The 'Identity' is set using the same email address.
If there is a user with this email address within Heap their details will be updated to include the properties you define coming in from both your 3rd party service and Clearbit should you wish to combine them.
![heap-clearbit-step-03-app](https://tray.ai/documentation/images/connectors/service/heap/4CEGPqRT8Q5WBc4x9YI9AF_heap-clearbit-step-03-app.png)

### **Delete Heap Users**

> **Info:** You may wish to set up a system to check how long your loop has been running and if it has been running for too long. You could handle this as a timeout error. Use the example given [here](https://tray.ai/documentation/connectors/core/loop/#example-2---the-loop-forever-operation) for inspiration.

**EXTRA AUTHS**: In order to complete this workflow, you will also need to be authenticated with the [Slack](https://tray.ai/documentation/connectors/service/slack/) connector.
Below is a best practice example of how you could use the Heap connector to delete users and check their completion status.
It minimises the number of calls required during the deletion process and outlines how best to use the `deletion_request_id`.
This example imagines a scenario where a survey was sent out to get clients to update their third-party service tracking cookies. Some have remained while others have opted out. This workflow collects the data and isolates the users who choose to opt-out. It then deletes those users from the Heap database and sends a notification once finished.

#### End Result

![heap-slack-result](https://tray.ai/documentation/images/connectors/service/heap/h58vDMEwEOLDF71RoQF0B_heap-slack-result.png)

#### Step-by-step breakdown

### 3rd Party Service List

A list of users comes in from a third-party service. These are the users that have been identified as deletion candidates as they have all updated their `opt_out` status regarding third-party service site's tracking cookies.
The information has been kept minimal to simplify the use case. See the sample payload below for more details.
![heap-opt-option-1](https://tray.ai/documentation/images/connectors/service/heap/7qyADC7NGYYPBn8xjO53lO_heap-opt-option-1.png)

```json
[
  \{
    "user_name":"john123",
    "email":"john@example.com",
    "identity_type":"identity",
    "value":"310068",
    "opt_out":true
  \},
  \{
    "user_name":"Ant",
    "email":"Ant@example.com",
    "identity_type":"user_id",
    "value":"5954094055083999",
    "opt_out":false
  \},
  \{
    "user_name":"Mary",
    "email":"mary@example.com",
    "identity_type":"identity",
    "value":"498763",
    "opt_out":true
  \},
  \{
    "user_name":"Billy",
    "email":"billy@example.com",
    "identity_type":"user_id",
    "value":"6514974001406129",
    "opt_out":false
  \},
  \{
    "user_name":"Jess",
    "email":"jess@example.com",
    "identity_type":"identity",
    "value":"112017",
    "opt_out":true
  \}
]
```

### List format

To work with the **Delete users (heap-1)** step, later on, **you must make sure that the list of users you want to delete is in an array format BEFORE said step**.
Check out the [List helpers](https://tray.ai/documentation/connectors/helper/list-helper/) page for operations that could potentially help you format your own third-party service lists into a more malleable format.

### Filter for 'opt\_out: true'

The List Helpers step filters out all the clients who decided to opt-out of the tracking cookies associated with the third-party service.
When using the 'Filter' operation make sure to set the 'Filter list' type selector to `type: object`. This will allow you to specify the Key you wish to reference (`opt_out`) and the value (`true`) to filter for.
![heap-opt-option-filter](https://tray.ai/documentation/images/connectors/service/heap/5b10uXmStag11uziKJ9tzn_heap-opt-option-filter.png)

### Collect user\_names

Pluck is similar to Filter. It extracts the value of a specific key from each one returning a flat list of the values for all objects.
In this case a list of user names from the opt-out client objects. These will come in handy later on in the workflow when we are sending the deletion notification.
![heap-opt-option-names](https://tray.ai/documentation/images/connectors/service/heap/7daa0I8lDr3tonw9FBqA2u_heap-opt-option-names.png)

### Delete users

Using the results from **Filter for 'opt\_out: true' (step="list-helpers-1)** this operation will now take this filtered list of clients and send a deletion request to the Heap API.
As you can see the log step has returned green even though the deletion status for this list of clients is `pending`. You can also see that a `deletion_request_id` has been autogenerated.
Heap refers to this ID whenever a deletion or check is required for the users (be they one or many) Heap was requested to remove. Every single deletion request automatically generates one.
![heap-opt-option-delete](https://tray.ai/documentation/images/connectors/service/heap/6hE7ONzLqt1SrT9VNMFiff_heap-opt-option-delete.png)

### Loop collection

Due to the amount of time it takes to delete users from the Heap API **we strongly suggest that you put a timed, regular, check-in place**. As opposed to continuously repeatedly calling the workflow for potentially hours.
Checking the deletion status before allowing your workflow to continue with a 'false positive' is critical. I.e. As mentioned previously you will get a green run step returned even though the users have not yet been removed from the API.
As a result the Loop step is set to 'Loop forever' as the time and the number of calls necessary before deletion of these users has finished is unknowable.
We need to iterate continuously around the list of clients until the deletion status goes from `pending` to `complete`.
![heap-loop-1.](https://tray.ai/documentation/images/connectors/service/heap/4l1f0ihsnsWmBtgSd3vOPc_heap-loop-1.png)

### Get deletion status

Within the forever loop the second Heap connector is set to 'Get Deletion status'.
Jsonpath the 'Deletion request ID' to the ID generated from the previous Heap connector step.
Heap uses the 'Deletion request ID' to confirm the deletion status of that particular deletion request.
![heap-deletion-check](https://tray.ai/documentation/images/connectors/service/heap/4lhn7FqWX20811PAOaxDnT_heap-deletion-check.png)

### Delete complete?

The 'Advanced True/ False Evaluation' boolean check confirms the status returned by the second Heap connector step.
Unless the status is equal to true, the workflow will not continue down the true branch.
![heap-deletion-complete](https://tray.ai/documentation/images/connectors/service/heap/6jIn25AALnmFL3mZcJyGao_heap-deletion-complete.png)

### FALSE branch

### Delay

A Delay connector allows the workflow to make status checks every ten minutes thereby decreasing the number of automatic calls it would have made.
![heap-delay](https://tray.ai/documentation/images/connectors/service/heap/2275WdG2hLSFiuanEJVyOZ_heap-delay.png)

### TRUE branch

### Dynamic json

Using the results gathered from **Collect user\_names (list-helpers-2)** we separate the listed names using a space and a comma so that the text will be returned in a more human-readable sentence format.
![heap-join-names](https://tray.ai/documentation/images/connectors/service/heap/4mG5Udgtq8rCBEbvB0epP7_heap-join-names.png)

### Notify channel

Select the channel and word opening to your notification message as per your preference.
We have used the various list helpers and interpolation within the 'Message' property to make sure that the list of users removed from the Heap database is created dynamically.
![heap-notify-channel](https://tray.ai/documentation/images/connectors/service/heap/5sDMbr3EapYtG3KGzMPMUo_heap-notify-channel.png)
The result will be as follows:
![heap-slack-result](https://tray.ai/documentation/images/connectors/service/heap/38fWDObHj5cdhS39UmwsUf_heap-slack-result.png)

### Break loop

As the Loop connector was set to 'Loop Forever' we need the 'Break Loop' connector to stop the process once all conditions have been met.
![heap-break-loop](https://tray.ai/documentation/images/connectors/service/heap/3O30FgnesO8AtjS5HDN6fq_heap-break-loop.png)

## Operations

A List of Heap operations and how to use them.

### Add user properties

Best used when you have one or several custom user properties to attach.
There are two key properties that you must set up before using this operation. Your user 'Identity' and 'Environment ID'.
You will need to specify the **'Identity'** of your user under the 'User properties' section. This typically corresponds to a pre-existing user.
If no such identity exists then a new one will be created with whatever value you set. So long as that value is a case-sensitive string limited to 255 characters.
To locate your [Environment ID](https://tray.ai/documentation/connectors/service/heap/#environment-id-required) see the section above for more details.
![heap-add-user-prop](https://tray.ai/documentation/images/connectors/service/heap/2hmDYCFrbQacVXmyTFZ9tD_heap-add-user-prop.png)

### Email property

If you want to write your user's email into the built-in 'Email' property, **you must send the email key in lowercase**.
Sending an email value with a non-lowercase key will create an entirely new property to store this data in. You will end up with two email properties within the same object.
![heap-email-1](https://tray.ai/documentation/images/connectors/service/heap/21cm0oYVR8Kw6tmKJDWHXc_heap-email-1.png)

### API limits

There is an API limit of **maximum of 1000 users per each 'Add user properties' request**.
Requests are also **limited to 30 requests per 30 seconds per identity per app\_id**.
See our [note on API Limits](https://tray.ai/documentation/connectors/service/heap/#note-on-api-limits) for more details on how to handle big data collections.
Note also that this operation takes a "users **array** of objects", so be sure to check your JSON formatting.

```json
\{
  "app_id":"123456789",
  "users":[
    \{
      "identity":"test_user@tray.io",
      "properties":\{
        "Account":"tray.io",
        "TV":"Twin Peaks"
      \}
    \}
  ],
  "user_properties":[
    \{
      "identity":"test_user@tray.io",
      "properties":\{
        "Account":"tray.io",
        "Cuisine":"Asian",
        "email":"test_user@tray.io"
      \}
    \},
    \{
      "identity":"test_user@tray.io",
      "properties":\{
        "Fruit":"Kiwi",
        "BikleIn":"2"
      \}
    \}
  ]
\}
```

### Add Account properties

This operation allows you to add one or several custom account properties.
An **'Account ID'** (as well as an [Environment ID](https://tray.ai/documentation/connectors/service/heap/#environment-id-required) is required) for this to work.
In Heap you need to specify a user property to group users into accounts (i.e. 'Account ID'). Heap will associate all users with the same property value under the same account. This is the 'Account ID' you should refer to.
If no such identity exists then create a new one.
![heap-add-account-prop](https://tray.ai/documentation/images/connectors/service/heap/6bgN9Eh8lhB2tYFyMEFR6E_heap-add-account-prop.png)

### API Limits

Used for singular account updates only.
An account ID is required for this to work. If you use a CRM tool to manage account data note that, as your set of accounts and their properties change, you’ll need to periodically call this API with an account ID as well as any account-level properties.
**This can easily be done with a simple Tray.io workflow. One that uses a scheduled trigger and your chosen CRM tool.**
Set your workflow to call your chosen CRM service (such as [Monday](https://tray.ai/documentation/connectors/service/monday/), [Pipedrive](https://tray.ai/documentation/connectors/service/pipedrive/) or [Salesforce](https://tray.ai/documentation/connectors/service/salesforce/) etc) at regular intervals (hourly/ daily/ weekly) by using the Scheduled trigger.
**Integrated with Heap's 'Add Account properties' operation will mean that you can easily and automatically keep your account properties up to date**.

### Delete users

As this operation is user-specific you will need to use a unique user identifier to specify which user/s need to be removed from Heap.
In this case it refers to the 'User ID' or 'Identity' of an individual user.
**Whenever this operation is run it will return green** in the logs. This is regardless of whether the operation has actually finished deleting the users specified.
As you can see from the output the status that is returned is `pending` (and therefore not yet complete) even with a clean run step.
This is why we **strongly recommend** you use this operation in conjunction with the [Get deletion status](https://tray.ai/documentation/connectors/service/heap/#get-deletion-status) operation.
![heap-delete-user-ex-prop](https://tray.ai/documentation/images/connectors/service/heap/3itX5mVBMxXmoAj1rezQYI_heap-delete-user-ex-prop.png)

### List format

Any lists of users you wish to delete MUST be submitted in an array format.
See the **Delete Heap Users** example below for an example walkthrough.

```json
[
  \{
    "user_name":"john123",
    "email":"john@example.com"
  \},
  \{
    "user_name":"Ant",
    "email":"Ant@example.com"
  \},
  \{
    "user_name":"Mary",
    "email":"mary@example.com"
  \}
]
```

### API Limits

It **can take up to 4 hours to delete users from the Heap API**.
While this lag time is normal we **strongly advise you use a delay method as well as the **[**Get deletion status**](https://tray.ai/documentation/connectors/service/heap/#get-deletion-status)** operation in conjunction with this one**.
This will help you save the number of checks/ calls you might otherwise need to make waiting for the process to complete. It will also make sure that your workflow will not miss when the deletion finally completes.
See the **Delete Heap Users** example below for a complete walkthrough.

### Get deletion status

You cannot use this operation without a 'Deletion request ID'. This is auto-generated when you use the [Delete users](https://tray.ai/documentation/connectors/service/heap/#delete-users) operation.
Once this is acquired this operation will check the status of the deletion request with each run.
We advise our users to limit the number of checks made to save on the number of calls required.
See our\*\* Delete Heap Users\*\* example below for a best practices walkthrough using this operation.
![heap-delete-status-ex-prop](https://tray.ai/documentation/images/connectors/service/heap/adJ1KifyeohmGq3YBjwni_heap-delete-status-ex-prop.png)

### Raw HTTP request

> **Warning:** Note that **only the server side API will work with this operation**.

This is a very powerful feature that you can put to use when there is an endpoint in Heap which is not used by any of our operations.
This operation gives you the power to implement any future server side endpoints built by Heap.
To use this you will first of all need to research the endpoint in the [Heap API Server side documentation v1.0](https://developers.heap.io/reference/server-side-apis-overview), to **find the exact format** that Heap will be expecting the endpoint to be passed in.
Note that you will only need to add the suffix to the endpoint, as the base URL will be automatically set (the base URL is picked up from the value you entered when you created your authentication).
The base URL for Heap is: `https://heapanalytics.com`

### Set up

For example, say that the 'Track' operation did not exist in our Heap connector and you wanted to use this endpoint. Track is an operation used to send custom events to Heap server-side.
You would use the Heap API docs to find the relevant endpoint - which in this case is a `POST` request called: `/api/track`. More details about this endpoint can be found [here](https://developers.heap.io/reference/track-1).
As you can see there is also the option to include a query parameter, should you wish to do so. So if you know what your method, endpoint and details of your query parameters are, you can use them to send custom events to Heap server-side information with the following settings:

### Example

Method: `POST`
Endpoint: `/api/track`
Body Type : Raw : `[ "app_id" : "123456789" ] [ "identity" : "123456" ] [ "event" : "raw http workflow event" ]`
![heap-raw-http](https://tray.ai/documentation/images/connectors/service/heap/1DNbi2Rt0YsowbGbSynCEe_heap-raw-http.png)

### Track event

Use this operation to send custom events to Heap server-side. This can be used for singular or multiple events.
We recommend using this for events that need to exactly match your backends such as completed order transaction info or events that are not available for Heap to capture on the client-side.
To locate your [Environment ID](https://tray.ai/documentation/connectors/service/heap/#environment-id-required) see section above.
'Identity' refers to the user's identifier. If no such identity exists then a new one will be created with whatever value you set. So long as that value is a case-sensitive string limited to 255 characters.
The 'Event' refers to the server-side event you wish to track.
![heap-track-ex-prop](https://tray.ai/documentation/images/connectors/service/heap/2F2xB7r1uP5xkBHrcx5m4z_heap-track-ex-prop.png)

### API Limits

This operation takes an **events array of objects**.
Added to this it can only handle up to \*\*1000 events per minute per identity per \*\***`app_id`** and **15,000 events per minute per \*\*\*\*`app_id`**.
Requests are also **limited to 30 requests per 30 seconds per identity per app\_id**
See the [note on API limits](https://tray.ai/documentation/connectors/service/heap/##note-on-api-limits) for more details.

## Important Notes on using Heap

### Note on API limits

Some of the Heap operations are subject to API limits. There are basically two types of limits:

### 1 - API limits on individual requests

The amount of requests that can be made to a Heap endpoint within a certain timeframe. When this applies, it is **30 requests per 30 seconds per identity per app\_id**
This is a point of concern if, for example, you have a workflow triggered by service updates whereby large amounts of individual requests come in one after the other.
Please see our [documentation on API limits](https://tray.ai/documentation/platform/automation-integration/advanced-use-cases/batching-queueing/queueing) for guidance on how to set up a queue system for dealing with such a scenario.

### 2 - API limits on items per request

The number of items that can be updated in a single request. For example a **maximum of 1000 users per each 'Add user properties' request**
This is a concern when you are receiving large lists of e.g. 10,000 new/updated users. The solution here is to chunk the lists into batches of 1000 or less, before looping through each batch and sending to Heap.
If you are pulling data from a service, that service may have a pagination system (such as demonstrated in our [Salesforce pagination template](https://tray.io/documentation/templates/sales/paginate-salesforce-records/)) which allows you to receive data in batches of e.g. 100 which can then be looped through (using the loop connector) and added to Heap.
If pagination is not available and you have a list of e.g. 10,000 users, you could use the **List Helpers 'chunk' operation** to divide this up into smaller batches, which could then be looped through.
The following example shows how you can iterate through a list of incoming user data from a third party service which is more than 1000 user objects per payload.
It breaks down the data into manageable 'chunks' for the Heap API.
![heap-chunk-users](https://tray.ai/documentation/images/connectors/service/heap/4w3dj3WvHxaiclchmzJXDf_heap-chunk-users.png)

### Satisfying input schema requirements

Certain operations, such as **'Add User Properties'**, can be used as bulk updates, so it is possible to send a list of items in one call.
It is important to note that the Heap API has specific input schema requirements for each item in the list. In this case the user object must have a top-level **'identity'** field and a top-level **'properties'** object:

```json
{
  "app_id": "12345",
  "user_properties": [
   {
    "identity": "alice@example.com",
    "properties": \{
      "Role": "Admin",
      "Vertical": "Ecommerce",
      "email": "alice2@example2.com"
      \}
    },
   {
     "identity": "bob@example.com",
    "properties": \{
      "Role": "User",
      "Vertical": "Saas",
      "email": "bob2@example2.com"
      \}
    }
  ]
}

```