---
updatedAt: 2026-04-21T05:03:04.000Z
agentTools:
  projectIndex: https://developers.leadboxer.com/llms.txt
---

# Retrieve Leads

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

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

1. Open the [Lead Object](https://developers.leadboxer.com/docs/lead-object) reference so you can identify the fields returned in each lead record.
2. Prepare the filters and query parameters you want to send with your request.
3. Decide how you want to use the response in your app, CRM, or reporting workflow.

## Retrieve leads

1. Send the request with the filters and query parameters for the leads you want to return.
2. Review the JSON response body.
3. Match each returned field to the [Lead Object](https://developers.leadboxer.com/docs/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](https://developers.leadboxer.com/docs/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](https://developers.leadboxer.com/docs/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](https://developers.leadboxer.com/v1.0/docs/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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Leadboxer API",
    "description": "# LeadBoxer API Documentation\n\nHere you can find the technical documentation needed for using the LeadBoxer API, including the option to generate requests and review the outcomes.\n\n## Getting Started\n\nTo get started, please have a look at these pages that include introductions, use-cases, and additional information for the LeadBoxer API: [LeadBoxer API Documentation](https://docs.leadboxer.com/category/112-all)\n\nThese documents are intended for LeadBoxer CUSTOMERS that have a valid API license & Key. Please contact us before using the LeadBoxer API.\n\n## Warning\n\nPlease be aware that any actions you perform through this reference testing functionality will involve operations with your production data. To test your applications against some sandbox data, we recommend creating a new, separate LeadBoxer account for sandboxing purposes.\n\nThis API is under active maintenance, and we are constantly adding new functionality to this version.\n\n[**All requests to the API must be made over SSL (https, not http).**]",
    "termsOfService": "https://www.leadboxer.com/resources/terms",
    "contact": {
      "name": "Wart Fransen",
      "url": "wart@leadboxer.com",
      "email": "hello@leadboxer.com"
    },
    "license": {
      "name": "",
      "url": "https://www.leadboxer.com/resources/privacy"
    },
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "https://api.leadboxer.com",
      "description": "Production Server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Leads",
      "description": "Get your top leads with fine grained filtering criteria."
    }
  ],
  "paths": {
    "/v1/leads": {
      "get": {
        "tags": [
          "Leads"
        ],
        "summary": "Retrieve Leads",
        "description": "Returns a list of leads in JSON format based on the provided filters and query parameters.",
        "operationId": "users",
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "description": "The Dataset ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Keyword or phrase to search across all searchable fields. Search is case-insensitive for text fields. Defaults to '*' to match all results.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "*"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "No of rows to return in response.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 50
            }
          },
          {
            "name": "locale",
            "in": "query",
            "description": "Locale for formatting the 'prettyLastEvent' field in response. Determines the language and regional formatting (e.g., dates, text) returned by the API.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "en_US"
            },
            "example": "en_US"
          },
          {
            "name": "nextToken",
            "in": "query",
            "description": "Token returned after each request, used to fetch the next page of results. Each token is valid for 10 minutes.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "criteriaTextFilter",
            "in": "query",
            "description": "Text-based filter expression used to filter result fields.Format: field|operator|value. Multiple filters are comma-separated.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Does not contain – organization name": {
                "description": "Does not contain – organization name",
                "value": "organizationName.raw|doesnotcontain|Cirrus"
              },
              "Employee range with tag exclusion": {
                "description": "Employee range with tag exclusion",
                "value": "organizationEmployeeCountRangeName.raw|is|51-200;201-500,lead_tags.raw|isnot|customer;competitor"
              },
              "Industry contains": {
                "description": "Industry contains",
                "value": "organizationIndustryName.raw|contains|Computer Software"
              },
              "Is – single country": {
                "description": "Is – single country",
                "value": "organizationCountry.raw|is|Denmark"
              },
              "URL exact match": {
                "description": "URL exact match",
                "value": "original_url.raw|is|http://www.justpayy.com"
              },
              "Multiple filters combined": {
                "description": "Multiple filters combined",
                "value": "organizationName.raw|contains|scuba equipment,last_country_name.raw|inregion|APAC,organizationIndustryName.raw|is|water sports"
              },
              "Complex real example": {
                "description": "Complex real example",
                "value": "organizationName.raw|is|google trends boutech,last_country_name.raw|is|Philippines"
              },
              "In region": {
                "description": "In region",
                "value": "last_country_name.raw|inregion|APAC"
              },
              "Is – multiple countries": {
                "description": "Is – multiple countries",
                "value": "organizationCountry.raw|is|Sweden;Norway;Denmark"
              },
              "Contains – URL path": {
                "description": "Contains – URL path",
                "value": "original_url.raw|contains|/solutions/clinicalkey"
              },
              "Contains – organization name": {
                "description": "Contains – organization name",
                "value": "organizationName.raw|contains|bank"
              },
              "In category": {
                "description": "In category",
                "value": "organizationIndustryName.raw|incategory|Construction"
              }
            }
          },
          {
            "name": "criteriaNumberFilter",
            "in": "query",
            "description": "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.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Between range": {
                "description": "Between range",
                "value": "user.total_pages_viewed|between|10-50"
              },
              "Less than": {
                "description": "Less than",
                "value": "user.total_number_visits|lessthan|50"
              },
              "Combined exclusion and range": {
                "description": "Combined exclusion and range",
                "value": "user.total_number_visits|isnot|21,user.total_pages_viewed|between|10-100"
              },
              "Greater than": {
                "description": "Greater than",
                "value": "user.total_number_visits|greaterthan|12"
              },
              "Not between range": {
                "description": "Not between range",
                "value": "user.total_pages_viewed|notbetween|5-20"
              },
              "Multiple numeric filters": {
                "description": "Multiple numeric filters",
                "value": "user.total_number_visits|greaterthan|12,user.total_pages_viewed|greaterthan|10"
              },
              "Not equal": {
                "description": "Not equal",
                "value": "user.total_number_visits|isnot|21"
              },
              "Exact match": {
                "description": "Exact match",
                "value": "user.total_number_visits|is|12"
              }
            }
          },
          {
            "name": "criteriaTimeFilter",
            "in": "query",
            "description": "Time-based filter expression used to filter results by time field. Format: field|operator|value.\n\nAllowed fields (same as `timeField` parameter):\n- eventEsTimestamp : Last Seen\n- first_session_unix_timestamp : First Seen\n\nSupported operators:\n- exactly   → integer value (0 = Today, 1 = Yesterday)\n- lessthan  → integer value (e.g. 6 = last 7 days)\n- between   → date range in format dd/MM/yyyy-dd/MM/yyyy\n\nLocale settings are taken into account while interpreting dates and returning results.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Today": {
                "description": "Today",
                "value": "eventEsTimestamp|exactly|0"
              },
              "Last 30 days": {
                "description": "Last 30 days",
                "value": "eventEsTimestamp|lessthan|29"
              },
              "Yesterday": {
                "description": "Yesterday",
                "value": "eventEsTimestamp|exactly|1"
              },
              "Last 7 days": {
                "description": "Last 7 days",
                "value": "eventEsTimestamp|lessthan|6"
              },
              "Custom date range": {
                "description": "Custom date range",
                "value": "eventEsTimestamp|between|04/11/2025-10/12/2025"
              }
            }
          },
          {
            "name": "criteriaFieldFilter",
            "in": "query",
            "description": "Field-based filter used to include leads based on field presence.\n\nFormat:\noperator|field1;field2\n\nAllowed operator:\n- hasanyvalue\n\nAllowed fields:\n- firstName\n- lastName\n- email\n\nMultiple fields can be provided using semicolons.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Has any value (email)": {
                "description": "Has any value (email)",
                "value": "hasanyvalue|email"
              },
              "Has any value (first or last name)": {
                "description": "Has any value (first or last name)",
                "value": "hasanyvalue|firstName;lastName"
              }
            }
          },
          {
            "name": "criteriaExitLinkFilter",
            "in": "query",
            "description": "Exit link filter used to include or exclude leads based on exit link values.\n\nFormat:\nfield|operator|value\n\nSupported operators:\n- contains\n- is\n- isnot\n- doesnotcontain\n\nMultiple values can be provided using semicolons.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Contains exit link": {
                "description": "Contains exit link",
                "value": "exitLinkFilter|contains|leads"
              }
            }
          },
          {
            "name": "criteriaLeadscoreFilter",
            "in": "query",
            "description": "Minimum lead score threshold (optional). Only records with lead scores greater than the provided number (0–100) are returned.",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 0,
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "criteriaDisplayFilter",
            "in": "query",
            "description": "Display filter used to control which types of leads are returned.\n\nSupported values:\n- company\n- person\n- unidentified\n\nSelecting 'unidentified' returns leads that could not be identified as a company or a person.\n\nMultiple values can be provided using semicolons.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Person leads only": {
                "description": "Person leads only",
                "value": "person"
              },
              "Company and unidentified leads": {
                "description": "Company and unidentified leads",
                "value": "company;unidentified"
              },
              "All lead types": {
                "description": "All lead types",
                "value": "company;person;unidentified"
              },
              "Company leads only": {
                "description": "Company leads only",
                "value": "company"
              },
              "Unidentified leads": {
                "description": "Unidentified leads",
                "value": "unidentified"
              }
            }
          },
          {
            "name": "timeField",
            "in": "query",
            "description": "Time field used for filtering.\n\nAllowed values:\n- eventEsTimestamp : Last Seen\n- first_session_unix_timestamp : First Seen",
            "required": true,
            "schema": {
              "type": "string",
              "default": "eventEsTimestamp",
              "enum": [
                "eventEsTimestamp",
                "first_session_unix_timestamp"
              ]
            }
          },
          {
            "name": "usePresetExclusionList",
            "in": "query",
            "description": "Use a preset exclusion list of criteria to exclude from result.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "use_id",
                "last_most_likely_company",
                "organizationName",
                "organizationDomain"
              ]
            },
            "examples": {
              "Exclude by use_id": {
                "description": "Exclude by use_id",
                "value": "use_id"
              },
              "Exclude by multiple types": {
                "description": "Exclude by multiple types",
                "value": "use_id,last_most_likely_company,organizationName,organizationDomain"
              }
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "timeZone",
            "in": "query",
            "description": "Time zone used when parsing timestamps and evaluating time-based filters. \nIf not provided, the default time zone is Europe/Amsterdam.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "Europe/Amsterdam"
            },
            "example": "Europe/Amsterdam"
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Sort results by a specific field and direction.\n\nFormat:\nfield|direction\n\nAllowed fields:\n- lastEvent\n- _score\n\nAllowed directions:\n- asc\n- desc",
            "required": false,
            "schema": {
              "type": "string"
            },
            "examples": {
              "Sort by time field (desc)": {
                "description": "Sort by time field (desc)",
                "value": "lastEvent|desc"
              },
              "Sort by score field (desc)": {
                "description": "Sort by score field (desc)",
                "value": "_score|desc"
              },
              "Sort by time field (asc)": {
                "description": "Sort by time field (asc)",
                "value": "lastEvent|asc"
              },
              "Sort by score field (asc)": {
                "description": "Sort by score field (asc)",
                "value": "_score|asc"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAllResponse"
                },
                "example": {
                  "data": [
                    {
                      "organizationDomain": "example-domain.test",
                      "esScore": "88",
                      "lastEvent": "9999999999999",
                      "last_country_name": "Fakeland",
                      "last_region_name": "SampleRegion",
                      "last_city": "DemoCity"
                    }
                  ],
                  "metaData": {
                    "nextToken": "placeholder_next_token_123",
                    "rows": 1,
                    "totalRows": 999,
                    "queryTime": {
                      "timeZone": "UTC",
                      "queryTime": 1111111111,
                      "periodFromTime": 1100000000,
                      "periodToTime": 1199999999
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request: The request is invalid or malformed (missing/incorrect parameters).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1BadRequestResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: The client has exceeded credit limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1InternalServerError"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden: The authenticated user does not have permission to access this resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1PermissionDenied"
                }
              }
            }
          },
          "404": {
            "description": "Not Found: The requested resource does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1NotFoundResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict: The request could not be completed due to a resource state conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ConflictResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Interval Server Error: An unexpected error occurred on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1InternalServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RateLimitErrorResponse": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "example": 1765611454230
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "example": 429
          },
          "error": {
            "type": "string",
            "example": "Too Many Requests"
          },
          "message": {
            "type": "string",
            "example": "Rate limit exceeded. Please try again later."
          },
          "retryAfter": {
            "type": "integer",
            "format": "int32",
            "example": 58
          },
          "limit": {
            "type": "integer",
            "format": "int32",
            "example": 2
          },
          "remaining": {
            "type": "integer",
            "format": "int32",
            "example": 0
          }
        },
        "description": "Rate limit exceeded error response"
      },
      "V1BadRequestResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference that identifies the problem type",
            "example": "https://developers.leadboxer.com/docs/validation-error"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type",
            "example": "The request is malformed or contains invalid data"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence of the problem",
            "example": "email must be a well-formed email address"
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem",
            "example": "/v1/users/{userId}/name?email=johndoe.com"
          },
          "errors": {
            "type": "array",
            "description": "Array of field-level validation errors",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "The name of the field that failed validation",
            "example": "email"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message for this specific field",
            "example": "must be a well-formed email address"
          }
        },
        "description": "Array of field-level validation errors"
      },
      "V1PermissionDenied": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference that identifies the problem type"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32",
            "example": 403
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence of the problem"
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem"
          }
        }
      },
      "V1ConflictResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference that identifies the problem type"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type",
            "example": "Resource already exist"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32",
            "example": 409
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence of the problem",
            "example": "User with email: john.doe@examplecompany.com already exist"
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem",
            "example": "/v1/users/?email=john.doe@examplecompany.com"
          }
        }
      },
      "V1NotFoundResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference that identifies the problem type"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32",
            "example": 404
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence of the problem"
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem"
          }
        }
      },
      "V1InternalServerError": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference that identifies the problem type"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type",
            "example": "Internal Server Error"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code",
            "format": "int32",
            "example": 500
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence of the problem",
            "example": "An unexpected error occurred. Please contact support."
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem"
          }
        }
      },
      "GetAllResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "metaData": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "description": "Provide your LeadBoxer API Key",
        "name": "x-api-key",
        "in": "header"
      }
    }
  }
}
```