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

# HTTP API

> Hightouch's HTTP API endpoint for collecting events

## 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"
}

```

## Batch

Use the **batch** endpoint to submit multiple events to the collector in a single request. Each item in `batch` is a full event payload (`identify`, `track`, `page`, `screen`, `group`, or `alias`) and must include a `type` field.

Each request can contain at most **10,000 events** and must fit within **1 MiB (1,048,576 bytes)**.

Requests with more than 10,000 events return HTTP `400`. The collector rejects the entire request without accepting any events. Split larger batches into smaller requests.

You can optionally set top-level `context` and `sentAt` values. Hightouch applies those defaults to every event in the batch.

*Example `batch` call*

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

```
{
  "batch": [
    {
      "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"
    },
    {
      "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"
    }
  ],
  "context": {
    "library": {
      "name": "my-server",
      "version": "1.0.0"
    }
  },
  "sentAt": "2023-09-22T18:12:00.585Z"
}
```