This reference explains the core concepts behind the REST-based LeadBoxer API and Platform

Responses are returned in JSON. The API is stateless; every request must include a valid API key. Cross-Origin Resource Sharing is supported.

Core Concepts

The LeadBoxer data model consists of four building blocks:

• Users (Leads)
• Sessions
• Events
• Properties

These objects form the structure behind all API endpoints.

Users (Leads)

A user represents a uniquely identifiable person or browser.

A User ID is created the first time a visitor loads a site containing the LeadBoxer tracking pixel. This ID is stored in a first-party cookie and used to recognise returning visitors.

This endpoint supports rich filtering and parameterisation to tailor the output to your needs.

Sessions

A session captures a single visit or browsing period.

Each session has its own Session ID that can be used to retrieve the underlying events.

Events

Historically, analytics focused on pageviews. LeadBoxer tracks a much broader range of behavioural signals – all of which are treated as events.

What is an event?

An event is any signal sent to LeadBoxer via an HTTPS request.

Examples include:

• Pageviews
• Email opens
• Email clicks
• Video plays
• File downloads
• Link clicks
• Form interactions
• Server-side events

How events relate to sessions and users

• Events belong to a session
• Sessions belong to a user
• A user can have many sessions; a session can have many events

This hierarchy forms the basis for how the API structures data.

Each has its own dedicated endpoint. Together, they make up the foundation of the LeadBoxer API.

Properties

What is a property?

A property is a name/value pair you attach to an event to describe its meaning or context.

Examples: industry = manufacturing stage = evaluation cta_clicked = true

How properties behave

• Properties applied to an event are automatically propagated to its parent session and user
• Updating a property is simple – send the same name with a new value
• You can attach unlimited properties and send unlimited events

This makes properties a flexible way to enrich behavioural data.

Retrieving a Full Lead Profile (User → Sessions → Events)

To build a complete behavioural profile for a lead, chain the three main calls:

1. Users

Query and filter users based on the available parameters.

2. Sessions

Use the User ID to fetch all sessions belonging to that user.

3. Events

Use each Session ID to retrieve all events within that session.

By stitching these responses together on your side, you can reconstruct the full clickstream and behavioural history of any lead.