Reach out with questions, bugs, or suggestions. We'll respond ASAP. Your message is sent! We'll respond via email shortly.

Server-Side API

Our server-side APIs can be used to add additional user and event data to your users in Heap that might not be available on the client-side or at the time of a user-interaction. When sending server-side data, the properties and/or event will be associated with the Heap user with the identity provided in the request. A new user will be created with the given identity if that identity doesn’t already exist in Heap.Generally, we recommend you use our automatic client-side trackers for web and iOS whenever possible.

Some key points to note when integrating with our server-side APIs:

We've built dedicated server-side libraries for the following platforms. These libraries currently do not support our bulk API:

To send data from a different platform, just follow the HTTP spec below.

Track

Heap allows you to send custom events from any of your servers. A server-side event can be created by issuing a POST to https://heapanalytics.com/api/track with a JSON body containing the following keys:

This example CURL command logs a "Send Transactional Email" event for a hypothetical user identified as alice@example.com:

  $ curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "11",
    "identity": "alice@example.com",
    "event": "Send Transactional Email",
    "timestamp": "2017-03-10T22:21:56+00:00", 
    "properties": {
      "subject": "Welcome to My App!",
      "variation": "A"
    }
  }' \
  https://heapanalytics.com/api/track

To send multiple events at once see our bulk track api.

Add User Properties

You can also assign custom properties to any of your users from your servers. This can be done by issuing a POST to https://heapanalytics.com/api/add_user_properties with a JSON body containing the following keys:

This example CURL command assigns demographic data to a hypothetical user identified as bob@example.com:

  $ curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "11",
    "identity": "bob@example.com",
    "properties": {
      "age": "25",
      "language": "English",
      "profession": "Scientist"
    }
  }' \
  https://heapanalytics.com/api/add_user_properties

To send properties to multiple users at once at once see our bulk addUserProperties api.

Bulk APIs

Our bulk APIs allow you to send several events or update several users at once. The max number of events (track) or identities (add_user_properties) that can be sent is 1000 per request.

Bulk Track

If you have many custom events to send at once, you can use our bulk track api. Issue a POST request to https://heapanalytics.com/api/track with a JSON body containing the following keys:

Example

  $ curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "12343283";
  "events": [{
    "identity": "alice@gmail.com",
    "timestamp": "2016-05-10T22:21:56+00:00",
    "event": "Phone Call",
    "properties": {
      "Sales Rep": "Joe Smith",
      "Duration" : "15 minutes",
      "Purpose" : "Discovery Call"
  },
  {
    "identity": "mike@gmail.com",
    "timestamp": "2016-05-10T22:23:56+00:00",
    "event": "Phone Call",
    "properties": {
      "Sales Rep": "Susie Smith",
      "Duration" : "30 minutes",
      "Purpose" : "Discovery Call"
  }]
  }'\
  https://heapanalytics.com/api/track

Bulk Add User Properties

Add user properties to multiple users by issuing a POST to https://heapanalytics.com/api/add_user_properties with a JSON body containing the following keys:

Example

   $ curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "12345";
  "users":[{
    "identity": "alice@example.com",
    "properties": {
      "Role": "Admin",
      "Vertical": "Ecommerce"
      }
  },
   {"identity": "bob@example.com",
    "properties": {
      "Role": "User",
      "Vertical": "Saas"
      }
  }]
  }' \
  https://heapanalytics.com/api/add_user_properties