Session Management

Endpoints

Create Session

POST /api/visitors/session

Creates a new visitor session with device and location information.

Request Body:

• site_id (string, UUID, required): The ID of the site.
• id (string, UUID, optional): Existing session ID.
• fingerprint (string, optional): Browser fingerprint.
• device (object, optional): Device details (type, OS, screen size).
• location (object, optional): Location details (country, city).
• referrer (string, optional): Referrer URL.
• utm_params (object, optional): UTM parameters.

Get Session

GET /api/visitors/session

Retrieves session data by session ID.

Query Parameters:

• session_id (string, UUID, required): The ID of the session.
• site_id (string, UUID, required): The ID of the site.

Update Session

PUT /api/visitors/session

Updates an existing session with new activity data.

Request Body:

• session_id (string, UUID, required): The ID of the session.
• site_id (string, UUID, required): The ID of the site.
• last_activity_at (number, optional): Timestamp of last activity.
• current_url (string, URL, optional): Current page URL.
• page_views (number, optional): Updated page view count.

End Session

POST /api/visitors/session/end

Explicitly closes a visitor session.

Request Body:

• session_id (string, UUID, required): The ID of the session.
• exit_url (string, URL, optional): The URL where the session ended.
• exit_type (string, optional): Type of exit (‘exit’, ‘bounce’, ‘timeout’).
• duration (number, optional): Total session duration.

Identify Session

POST /api/visitors/session/[session_id]/identify

Associates a lead with a specific visitor session.

Path Parameters:

• session_id (string, UUID, required): The ID of the session.

Request Body:

• lead_id (string, UUID, optional): The lead ID.
• email (string, email, optional): Lead email.
• name (string, optional): Lead name.
• create_task (boolean, optional): Whether to create a follow-up task (default: false).