HTTP API Source

Hightouch's HTTP Tracking API enables you to record data from any website or application.

Headers

Authentication

To authenticate Hightouch's tracking API, send your projects Write Key along with a request. Authentication uses HTTP Basic Auth.

To do this, you should include an Authorization header that includes Basic followed by your base64 encoded write key. This looks like this:

Authorization: Basic YmJjYmU434YTNmRlNWRkYjM3MDUzMDRlMzN2JjM2NiY2RjYWJmZTA5YTA3ZGYxWNkNjQ5Zg==

Content-Type

Ensure your content-type header is set to 'application/json'

Identify

Identify events capture data about who your users are. This user context is vital for understanding and targeting your users. For example, you might use the collected identifiers in followup email campaigns, to segment your users by location, or to link anonymous and authenticated events.

Example identify call:

POST https://us-east-1.hightouch-events.com/v1/identify

{
	"type":  "identify",
	"messageId":  "111e984d-c93c-444c-b29c-f499a117c500",
	"traits":  {
		"email":  "kevin@hightouch.io"
	},
	"anonymousId":  "ce576487-95f9-4262-9315-2c7942b061c8",
	"userId":  "123",
	"originalTimestamp":  "2023-09-22T18:05:47.063Z",
	"sentAt":  "2023-09-22T18:05:47.064Z"
}

Track

Track events capture data on what the user is doing. Track events can capture a broad range of actions, such as clicking a button, completing a purchase, or creating a new account.

Example track call

POST https://us-east-1.hightouch-events.com/v1/track

{
	"type":  "track",
	"messageId":  "7b1e2872-4ebb-4779-b9ad-e7aa1a8eab82",
	"anonymousId":  "ce576487-95f9-4262-9315-2c7942b061c8",
	"userId":  "123",
	"event":  "Purchase completed",
	"properties":  {
		"cart_total":  24.99
	},
	"originalTimestamp":  "2023-09-22T18:12:00.584Z",
	"sentAt":  "2023-09-22T18:12:00.585Z"
}

Page events

Page events track the webpages users interact with. In most situations, you should automatically call the page load event when a page is loaded.

For single page apps, you should simulate page events in your routing layer.

Example page call

POST https://us-east-1.hightouch-events.com/v1/page

{
  "type": "page",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Screen events

Screen events are the equivalent of page views for mobile apps. Like page events, you should automatically call the screen event when a mobile screen view is loaded.

Example screen call

POST https://us-east-1.hightouch-events.com/v1/screen

{
  "type": "screen",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Group events

Group events let you associate users with a larger group. For example, a user may be part of an organization, or family.

The traits field is optional, and can include information on traits on the group. For example, if linking a user to a company, you may include traits on the company such as the company size or location.

Example group call

POST https://us-east-1.hightouch-events.com/v1/group

{
  "type": "group",
  "messageId": "d87596da-5f1e-40f4-a28a-7099290548b7",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "groupId": "456",
  "traits": { "company_name": "Hightouch" },
  "originalTimestamp": "2023-09-22T18:46:23.098Z",
  "sentAt": "2023-09-22T18:46:23.099Z"
}