LeadBoxer API introduction

This reference helps you to understand the RESTful LeadBoxer API. 

This API uses a JSON format for output and is capable of handling CORS (Cross-Origin Resource Sharing) requests. The API is stateless – all requests are validated against an API key (token). 

Detailed technical (developer) information

Technical (developer) documentation for the LeadBoxer API can be found online here:

• developers.leadboxer.com

Concepts

In this document we will briefly describe the main concepts of the LeadBoxer API: 

• Users (leads)
• Sessions
• Events
• Properties

Users (leads)

Users can be seen as uniquely identifiable persons and each user has its own user ID. The User ID is generated the first time a browser connects to a website with the LeadBoxer Pixel installed, and this user ID is saved in a cookie. We use first-party cookies and the cookie us only used to recognise returning visitors/users. 

You can retrieve a list of users using the  GET /api/views/c_view_leads request located under 'lead-board' 
Using the available parameters and filters you can customise the output to your needs.

Sessions

Sessions (or visits) are stored for each time a user visits the site. Sessions have an ID that can be used to retrieve the events.

Events

More then 2 decades ago, technology was developed to measure pageviews generated by mouse-clicks. The definition of what we track has now expanded. We track a broader range of signals which we call events. Examples are a page-view, playing a movie, making a tweet, getting a download, or an ajax/javascript event.

 What are events?

LeadBoxer defines an event as any signal sending a http(s) request to our servers for collection.

An event can represent any type of activity.

How do events relate to session and users?

• At LeadBoxer we group the events we receive into sessions and users.
• A session is made up of a series of events.
• A user is made up of a series of sessions. A single user can generate multiple sessions.

The following diagram illustrates this: 

Data structure 

To access the data using our API, you need to use the logic as outlined above. The data is stored in the 3 ‘tables’ with the same names:

1. Users
2. Sessions
3. Events

These 3 tables all have their own API call and these form the pillars of the LeadBoxer API

Properties

What is a Property?

• A property is a name/value pair you add to your events, to describe the event specifics or give it meaning; Wikipedia describes this concept: name/ value pairs.
• You can set the properties of an event. These properties are automatically passed to the parent objects: users and sessions. After inserting an event with property name/ value, the session and user will also have this property name/value.
• The last provided property will be stored and can easily be updated by sending the same name with a new value.
• You can send as many events as you like.
• You can add as many properties to an event as you want.

Show Lead Profile & clickstream

To get all the information from one specific lead you need to ‘stitch’ or loop through the 3 main api calls together the data at your end to mak a complete behavioural view of a visitor.

1. Users (leads) 
Get a list of users/visitors/leads specified using the parameters available, 

2. Sessions 
This API call allows you to get all sessions from a single user. See further on in the document for details.

3. Events 
This API call allows you to get all events from a single session. See further on in the document for details.