NEneosapien
Start / Stop

Start a session

Changed on

Start a recording session for a user in your organization.

The user is identified by user_id, interpreted according to id_type (phone, email, or neosapien_uid). The user must belong to your organization; otherwise the request fails with 404 user_not_found and nothing is recorded.

A start for a user who already has an open session with a different context_id closes that session first. If no stop arrives, the session ends automatically after the organization's auto stop timeout (set by an admin), or after the organization's maximum session length when no timeout is set.

queued: false means the event was accepted but could not be queued for session processing.

post/api/v1/start

Request

  • Base URL
    https://api.neosapien.xyz (the document declares no server; this is the origin it was published from)
  • URL
    https://api.neosapien.xyz/api/v1/start
  • Auth
    HTTP bearer

Request body

user_idstring required

Identifier of the user in your organization. Interpreted according to id_type.

id_type'phone' | 'email' | 'neosapien_uid' required

How user_id identifies the NeoSapien user.

timestampstring date-time required

When the session started or stopped. ISO 8601 with a timezone offset, e.g. '2026-10-05T09:30:00Z' or '2026-10-05T15:00:00+05:30'.

context_idstring nullable

Your identifier for where or what the session is about (a store, site, customer, job...). A start with a different context_id closes the user's open session.

latitudestring nullable

Latitude as a decimal string, e.g. '12.9716'. -90 to 90.

longitudestring nullable

Longitude as a decimal string, e.g. '77.5946'. -180 to 180.

metadataobject nullable

Flat key/value pairs stored with the event. At most 20 keys; keys 1-64 characters without null bytes; values are strings (up to 256 characters), finite numbers (integers within 64 bits), or booleans; at most 4096 bytes as compact JSON.

Example request

{
  "context_id": "store-42",
  "id_type": "phone",
  "latitude": "12.9716",
  "longitude": "77.5946",
  "metadata": {
    "priority": 2,
    "visit_reason": "restock"
  },
  "timestamp": "2026-10-05T09:30:00Z",
  "user_id": "+919812345678"
}

Response

Successful Response

successboolean required

The request was accepted.

neo_user_idstring required

The resolved NeoSapien user ID.

queuedboolean required

The event was queued for session processing. false means it was accepted but could not be queued.

event_idstring nullable

ID of the stored event record, or null if it was not stored.

Changes