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

# REST

This package allows you to track server-side customer events.

## Base URL

The API host depends on the [data region](/documentation/guides/data-regions) of your project:

| Data region  | API host                  |
| ------------ | ------------------------- |
| EU (default) | `https://api.gleap.io`    |
| US           | `https://api.us.gleap.ai` |

<Info>
  The examples on this page use the EU host. If your project lives in another region, replace `https://api.gleap.io` with your region's host. API tokens are per project and only valid in the project's region.
</Info>

## Identify users

```
POST https://api.gleap.io/admin/identify
```

**Request headers:**

```
Content-Type: application/json
Api-Token: YOUR_SECRET_API_TOKEN
```

Please replace *YOUR\_SECRET\_API\_TOKEN* with your secret API token, which can be found in your *project settings* -> *API token*.

**Request content:**

```
{
    "userId": "19283",
    "name": "John Doe",
    "email": "john@doe.com",
    "value": 1928,
    "phone": "+1 (129) 18283 8292",
    "createdAt": "2022-09-28T10:11:18.156Z",
    "companyId": "acme-inc",
    "companyName": "ACME inc.",
    // You can also track custom user properties
}
```

The optional `value` field is the contact's MRR: monthly recurring revenue, in your billing currency, in major units.

Set `companyId` to associate the user with a company. The optional `companyName`
is a fallback label and never overwrites a name set authoritatively via the
Companies endpoint (below).

### Last activity update

By default the last activity gets updated to `new Date()`. You can prevent this by adding `?preventLastActivityUpdate=true` to your request params.

```
POST https://api.gleap.io/admin/identify?preventLastActivityUpdate=true
```

## Companies

Create, update, read and delete companies. Companies hold authoritative
attributes (plan, value, SLA, address and custom data) shown in the dashboard
and used for company-level SLAs. All endpoints use the same `Api-Token` header
as above.

### Create or update a company

```
PUT https://api.gleap.io/admin/companies/{companyId}
```

`{companyId}` is your own immutable identifier for the company (URL-encode it) —
the same id you pass to identify as `companyId`. The company is created on
first use and updated on subsequent calls.

**Request headers:**

```
Content-Type: application/json
Api-Token: YOUR_SECRET_API_TOKEN
```

**Request content:**

```
{
    "name": "ACME inc.",
    "plan": "Growth plan",
    "value": 4990,
    "sla": 3600,
    "domain": "acme.com",
    "address": {
        "line1": "1 Infinite Loop",
        "city": "Cupertino",
        "state": "CA",
        "postalCode": "95014",
        "country": "US"
    },
    "customData": {
        "tier": "gold"
    }
}
```

`sla` is the response-time SLA in seconds. Unknown fields are ignored; `companyId`
cannot be set from the body. Returns the saved company.

`value` is the company's MRR: monthly recurring revenue, in your billing
currency, in major units. Kai PM scores a company account with the maximum of
the company `value` and its members' contact `value`s, counted once per
company. Update it from your billing webhooks; set `0` on cancellation.

### Get a company

```
GET https://api.gleap.io/admin/companies/{companyId}
```

Returns the company, or `404` if it does not exist.

### Delete a company

```
DELETE https://api.gleap.io/admin/companies/{companyId}
```

Permanently deletes the company. Its members (contacts) and their conversations
are not deleted.

## Pipelines (CRM)

Manage CRM pipeline entries from your backend: put a company or contact on a
pipeline, move it through stages, set field values, or remove it. All endpoints
use the same `Api-Token` header as above.

Entries are addressed by your own identifiers — the `companyId` you pass to
the Companies endpoints for company pipelines, or the `userId` you pass to
identify for contact pipelines (URL-encode both). Whether a pipeline holds
companies or contacts is its `recordType`.

### List pipelines

```
GET https://api.gleap.io/admin/pipelines
```

Returns every pipeline of the project with its stages and fields — everything
needed for the entry endpoints below:

```
[
    {
        "id": "665f1c2e8b4d2a0012345678",
        "name": "Onboarding",
        "recordType": "COMPANY",
        "stages": [{ "id": "stage-id", "name": "New", "color": "#6B7CFF" }],
        "fields": [{ "fieldId": "dealsize", "label": "Deal size", "type": "CURRENCY", "currency": "USD" }]
    }
]
```

Stage ids are the same ids the v3 API calls `laneId` (a pipeline's `lanes`) —
if you use both surfaces, they are interchangeable.

### Add a record to a pipeline

```
POST https://api.gleap.io/admin/pipelines/{pipelineId}/companies/{companyId}
POST https://api.gleap.io/admin/pipelines/{pipelineId}/contacts/{userId}
```

**Request content (all fields optional):**

```
{
    "stageId": "stage-id",
    "values": { "dealsize": 4990 }
}
```

`stageId` defaults to the pipeline's first stage. `values` are keyed by
`fieldId`; values must be primitives (string, number, boolean or null).
Returns `201` with the created entry. Adding is idempotent: if the record is
already on the pipeline, the existing entry is returned unchanged with `200` —
use the PUT endpoint to also update an existing entry. A genuine add runs the
pipeline's automations, exactly like the same action in the dashboard.

### Create or update an entry

```
PUT https://api.gleap.io/admin/pipelines/{pipelineId}/companies/{companyId}
PUT https://api.gleap.io/admin/pipelines/{pipelineId}/contacts/{userId}
```

Same body as above. If the record is not on the pipeline it is added;
otherwise its entry is updated: `stageId` moves it (running the stage's
automations), and `values` are merged — fields you do not send are left
untouched, `null` clears a field.

**Response:**

```
{
    "id": "665f1d4a8b4d2a0087654321",
    "pipelineId": "665f1c2e8b4d2a0012345678",
    "recordType": "COMPANY",
    "companyId": "acme-inc",
    "stageId": "stage-id",
    "values": { "dealsize": 4990 },
    "createdAt": "2026-08-12T09:00:00.000Z",
    "updatedAt": "2026-08-12T09:00:00.000Z"
}
```

### Get an entry

```
GET https://api.gleap.io/admin/pipelines/{pipelineId}/companies/{companyId}
GET https://api.gleap.io/admin/pipelines/{pipelineId}/contacts/{userId}
```

Returns the entry, or `404` if the record is not on the pipeline.

### Remove an entry

```
DELETE https://api.gleap.io/admin/pipelines/{pipelineId}/companies/{companyId}
DELETE https://api.gleap.io/admin/pipelines/{pipelineId}/contacts/{userId}
```

Removes the record from the pipeline. The company or contact itself is kept.

### Errors

Unknown pipelines, records or entries return `404`. An unknown `stageId`, an
unknown `values` key or a non-primitive value returns `400` with a message
naming the valid ids. Using a companies URL on a contact pipeline (or vice
versa) returns `400` with the correct route.

## Track events

```
POST https://api.gleap.io/admin/track
```

**Request headers:**

```
Content-Type: application/json
Api-Token: YOUR_SECRET_API_TOKEN
```

**Request content:**

```
{
    "events": [{
            "date": "2022-09-28T10:11:18.156Z",
            "name": "Subscription started",
            "data": {
                "name": "Sub 1232",
                "value": 1200
            },
            "userId": "19283"
        }, {
            "date": "2022-09-28T10:11:18.156Z",
            "name": "Subscription canceled",
            "data": {
                "name": "Sub 1259",
                "value": 1200,
                "reason": "Stopped working on the project.",
            },
            "userId": "19283"
        }]
}
```

## Rate limit

Please note that the identify and track APIs enforce a rate limit of 1500 requests / 60 seconds per API token. If you exceed the limit, requests are rejected with `429 Too Many Requests` and the token is blocked for a short period before requests are accepted again.