List Leads

Retrieve a paginated list of leads for your organization with optional filtering.

🔹 Endpoint Details

GET /api/v1/leads

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Query Parameters

Parameter	Type	Required	Description	Default
page	number	No	Page number for pagination	1
limit	number	No	Number of items per page	10
origin	string	No	Filter by origin name	-
status	string	No	Filter by lead status	-
subStatus	string	No	Filter by lead sub-status	-
startDate	date (ISO 8601)	No	Filter leads created on or after this date (requires endDate)	-
endDate	date (ISO 8601)	No	Filter leads created on or before this date (requires startDate)	-
timezone	string	No	IANA timezone used to interpret the date filters	-
excludeTest	boolean string	No	When true, leads flagged as test records are excluded	-
labels	array of strings	No	Filter by one or more labels (no special characters)	-
extraFields	object	No	Filter by custom field values (exact-match on the JSON bag)	-

🧩 Request Examples

Basic list

curl -X GET "https://openapi.onlive.site/api/v1/leads?page=1&limit=10" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filter by status, origin, and labels

curl -X GET "https://openapi.onlive.site/api/v1/leads?status=created&origin=Website%20contact%20form&labels=hotlead&labels=enterprise" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Filter by date range and timezone

curl -X GET "https://openapi.onlive.site/api/v1/leads?startDate=2026-01-01T00:00:00Z&endDate=2026-12-31T23:59:59Z&timezone=Europe/Paris" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Exclude test records

curl -X GET "https://openapi.onlive.site/api/v1/leads?excludeTest=true" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

Field	Type	Description
items	array	Array of Lead objects
meta.totalItems	number	Total number of items matching the query
meta.itemCount	number	Number of items in the current page
meta.itemsPerPage	number	Items per page
meta.totalPages	number	Total number of pages
meta.currentPage	number	Current page number

Response Example

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "123e4567-e89b-12d3-a456-426614174001",
      "organizationName": "Acme Inc.",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+33612345678",
      "status": "created",
      "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
      "userGroup": "Sales Team",
      "labels": ["hotlead"],
      "extraFields": { "source": "landing-page" },
      "qualification": 0.75,
      "sentToIntegration": false,
      "locations": [],
      "devices": [],
      "origins": [],
      "interactions": [],
      "historics": [],
      "createdAt": "2025-05-13T15:00:00Z",
      "updatedAt": "2025-05-13T15:00:00Z"
    }
  ],
  "total": 1,
  "count": 1,
  "totalPages": 1,
  "currentPage": 1
}

❌ Error Responses

This endpoint follows the standard error format.

📘 Notes

• Default pagination is page=1, limit=10
• startDate requires endDate (and vice versa) — the pair is validated together
• timezone is used to interpret the date filters; defaults to server timezone if omitted
• excludeTest accepts a string boolean ("true" / "false")
• labels cannot contain special characters
• extraFields matches on the full JSON bag
• Results are scoped to the caller's organization

💡 Best Practices

1. Pagination
   • Use page and limit for large result sets
2. Filtering
   • Combine status + labels to build agent inbox views
   • Use origin to scope by capture surface
   • Use startDate / endDate + timezone for time-windowed queries (e.g. daily digests)
   • Pass excludeTest=true to skip test records
3. Performance
   • Apply the most selective filter first
   • Avoid fetching all pages when a status + labels filter suffices

✅ Common Use Cases

• 🗂️ Agent Inbox: List status=created leads for a user group
• 📊 Dashboards: Aggregate counts by status or origin
• 📅 Time-Windowed Reports: Pull leads created in a given date range
• 🔁 CRM Sync: Iterate pages to reconcile with downstream systems