---
title: "Create a new session"
url: https://docs.gleap.ai/en/reference/rest-api/create-session
method: POST
path: "/sessions"
api: "API Reference"
tag: "Session"
operationId: "CreateSession"
updatedAt: "2026-11-01T18:40:15.677Z"
language: en
---

# Create a new session

`POST https://api.gleap.io/v3/sessions`

Create a session (contact) in the project from the `project` header. When `userId` is supplied this is an upsert: an existing contact with that userId is updated and returned instead of a new one being created (one session per project + userId). Without `userId` the contact is an email contact: an email contact with the same `email` is updated and returned, so inbound email and later identifies find it and a repeated import creates no duplicates.

## Authorization

- `Authorization` (header, required): `Bearer <token>`

## Headers

- `project` (string, required)

## Request body (`application/json`, required)

- `gleapId` (string): Read-only; generated by the server, ignored on create/update.
- `gleapHash` (string): Read-only; generated by the server, ignored on create/update.
- `lang` (string): Contact language. Ignored by POST /sessions for new email/guest sessions (created with "en"); settable via the SDK identify call or session update.
- `firstActivity` (any)
- `lastHeardFrom` (any)
- `lastActivity` (any)
- `lastFeedbackReport` (any)
- `project` (string): Read-only; derived from the `project` header, ignored if sent.
- `organisation` (string): Read-only; derived from the `project` header, ignored if sent.
- `unsubscribed` (boolean)
- `unsubscribedAt` (any)
- `unsubscribeReason` (string)
- `lastPageView` (any)
- `userId` (string)
- `name` (string)
- `location` (any)
- `email` (string)
- `avatar` (string)
- `companyId` (string)
- `emailOnly` (boolean)
- `companyName` (string)
- `deviceType` (string)
- `platform` (string)
- `sla` (number<double>)
- `phone` (string)
- `blocked` (boolean)
- `plan` (string)
- `value` (number<double>)
- `sessions` (number<double>): Read-only; server-maintained counter.
- `facebookId` (string)
- `instagramId` (string)
- `instagramUsername` (string)
- `telegramChatId` (string)
- `telegramUsername` (string)
- `outboundHistory` (any)
- `countFeedbackReports` (number<double>)
- `countFeedbackComments` (number<double>)
- `tags` (string[])
- `checklistTasks` (any)
- `customData` (any)
- `eventData` (any)

## Example request

```bash
curl --request POST \
  --url https://api.gleap.io/v3/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'project: <project>' \
  --header 'Content-Type: application/json' \
  --data '{
  "gleapId": "<gleapId>",
  "gleapHash": "<gleapHash>",
  "lang": "<lang>",
  "project": "<project>"
}'
```

## Responses

### 200 (`application/json`)

Ok