Retrieve Leads

get

https://api.leadboxer.com/v1/leads

Returns a list of leads in JSON format based on the provided filters and query parameters.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Use this endpoint to retrieve leads in JSON format and identify the fields in the response before you map them in your application.

Before you start

Open the Lead Object reference so you can identify the fields returned in each lead record.
Prepare the filters and query parameters you want to send with your request.
Decide how you want to use the response in your app, CRM, or reporting workflow.

Retrieve leads

Send the request with the filters and query parameters for the leads you want to return.
Review the JSON response body.
Match each returned field to the Lead Object reference before you store, transform, or display the data.

Example workflow

If you are building a lead sync, first run the request and inspect the JSON response. Then use the Lead Object reference to confirm what each field means before you map it to fields in your destination system.

This helps you avoid incorrect field mappings and makes it easier to validate the response when you change filters or query parameters.

What success looks like

After a successful request, you should have:

A JSON response containing lead records
A field-by-field reference in the Lead Object documentation
A clear mapping plan for the data you want to store or display

Optional: Test the request in the API reference

If you want to try the request before implementing it in your application, follow the steps in Using the App API to Fetch Leads. That guide walks you through testing the request in the interactive API reference and previewing the response body.

Query Params

site

string

required

The Dataset ID

string

Defaults to *

Keyword or phrase to search across all searchable fields. Search is case-insensitive for text fields. Defaults to '*' to match all results.

limit

int32

Defaults to 50

No of rows to return in response.

locale

string

Defaults to en_US

Locale for formatting the 'prettyLastEvent' field in response. Determines the language and regional formatting (e.g., dates, text) returned by the API.

nextToken

string

Token returned after each request, used to fetch the next page of results. Each token is valid for 10 minutes.

criteriaTextFilter

string

Text-based filter expression used to filter result fields.Format: field|operator|value. Multiple filters are comma-separated.

criteriaNumberFilter

string

Numeric filter expression used to filter results based on numeric fields. Format: field|operator|value. Multiple filters are comma-separated. Supported numeric operators include greaterthan, lessthan, is, isnot, between, and notbetween. The between and notbetween operators use the format min-max.

criteriaTimeFilter

string

required

Time-based filter expression used to filter results by time field. Format: field|operator|value.

Allowed fields (same as timeField parameter):

eventEsTimestamp : Last Seen
first_session_unix_timestamp : First Seen

Supported operators:

exactly → integer value (0 = Today, 1 = Yesterday)
lessthan → integer value (e.g. 6 = last 7 days)
between → date range in format dd/MM/yyyy-dd/MM/yyyy

Locale settings are taken into account while interpreting dates and returning results.

criteriaFieldFilter

string

Field-based filter used to include leads based on field presence.

Format:
operator|field1;field2

Allowed operator:

hasanyvalue

Allowed fields:

firstName
lastName
email

Multiple fields can be provided using semicolons.

criteriaExitLinkFilter

string

Exit link filter used to include or exclude leads based on exit link values.

Format:
field|operator|value

Supported operators:

contains
is
isnot
doesnotcontain

Multiple values can be provided using semicolons.

criteriaLeadscoreFilter

int32

0 to 100

Minimum lead score threshold (optional). Only records with lead scores greater than the provided number (0–100) are returned.

criteriaDisplayFilter

string

Display filter used to control which types of leads are returned.

Supported values:

company
person
unidentified

Selecting 'unidentified' returns leads that could not be identified as a company or a person.

Multiple values can be provided using semicolons.

timeField

string

enum

required

Defaults to eventEsTimestamp

Time field used for filtering.

Allowed values:

eventEsTimestamp : Last Seen
first_session_unix_timestamp : First Seen

Allowed:

usePresetExclusionList

string

enum

Use a preset exclusion list of criteria to exclude from result.

Allowed:

userId

int64

timeZone

string

Defaults to Europe/Amsterdam

Time zone used when parsing timestamps and evaluating time-based filters.
If not provided, the default time zone is Europe/Amsterdam.

sortBy

string

Sort results by a specific field and direction.

Format:
field|direction

Allowed fields:

lastEvent
_score

Allowed directions:

asc
desc

Responses

Before you start

Retrieve leads

Example workflow

What success looks like

Optional: Test the request in the API reference

200OK

400Bad Request: The request is invalid or malformed (missing/incorrect parameters).

402Payment Required: The client has exceeded credit limits.

403Forbidden: The authenticated user does not have permission to access this resource.

404Not Found: The requested resource does not exist.

409Conflict: The request could not be completed due to a resource state conflict.

429Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period

500Interval Server Error: An unexpected error occurred on the server.