Search Leads

Returns a paginated list of leads, with their linked project and booking.

GET/api/integration/lead

Request

cURL

curl -X GET "https://uat.integration.cl.sodtrack-shared.sodtrack.com/api/integration/lead" \
  -H "Authorization: Bearer $SODTRACK_TOKEN"

Base URL: https://uat.integration.cl.sodtrack-shared.sodtrack.com · other environments

Responses

Search Leads

{
  "data": [
    {
      "id": 4521,
      "reference": "LEAD-EXT-1001",
      "status": "sold",
      "paymentStatus": "paid",
      "approvalStatus": "approved",
      "cancelReason": null,
      "project": {
        "id": 88,
        "reference": "PROJ-EXT-100"
      },
      "booking": {
        "id": 10452,
        "reference": "ORD-2025-001"
      },
      "createdDate": "2025-03-10T14:22:00.000Z"
    },
    {
      "id": 4498,
      "reference": "LEAD-EXT-0987",
      "status": "created",
      "paymentStatus": "active",
      "approvalStatus": null,
      "cancelReason": null,
      "project": null,
      "booking": null,
      "createdDate": "2025-03-02T09:05:00.000Z"
    }
  ],
  "metadata": {
    "count": 2,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

Error responses for this endpoint follow the shared error reference.

Purpose

Returns a paginated list of leads, with their linked project and booking.

Use it to find leads by their Sodtrack id, by their external reference or by their customer. To get the customer, the assigned provider, the qualifying questions, the dynamic forms and the status history of a single lead, use Get Lead.

Field Definitions

🔐 Authentication

Field	Type	Required	Description
`x-api-key` (header)	`string`	✅	External integration API key provided by Sodtrack.

🔎 Query parameters

Parameter	Type	Required	Description
`id`	`number`	❌	Filter by Sodtrack lead id. Positive integer (minimum `1`).
`reference`	`string`	❌	Filter by lead external reference (the `reference` sent in Create Lead). Exact match.
`customerId`	`number`	❌	Filter by the Sodtrack id of the lead customer. Positive integer (minimum `1`).
`customerReference`	`string`	❌	Filter by the external reference of the lead customer. Exact match.
`pageSize`	`number`	❌	Number of results per page. Min `1`, max `50`. Default `10`.
`pageNumber`	`number`	❌	Page index (1-based). Min `1`. Default `1`.

All filters provided are combined with AND. If no filter is sent, the endpoint returns the paginated list of all leads ordered by id descending.

Example Request

Query string examples:

code

?reference=LEAD-EXT-1001
?id=4521
?customerReference=EXT-CUSTOMER-REF-001
?customerId=2001&pageSize=20&pageNumber=2

Response Example

json

{
  "data": [
    {
      "id": 4521,
      "reference": "LEAD-EXT-1001",
      "status": "sold",
      "paymentStatus": "paid",
      "approvalStatus": "approved",
      "cancelReason": null,
      "project": {
        "id": 88,
        "reference": "PROJ-EXT-100"
      },
      "booking": {
        "id": 10452,
        "reference": "ORD-2025-001"
      },
      "createdDate": "2025-03-10T14:22:00.000Z"
    },
    {
      "id": 4498,
      "reference": "LEAD-EXT-0987",
      "status": "created",
      "paymentStatus": "active",
      "approvalStatus": null,
      "cancelReason": null,
      "project": null,
      "booking": null,
      "createdDate": "2025-03-02T09:05:00.000Z"
    }
  ],
  "metadata": {
    "count": 2,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

Pagination (`metadata`)

Field	Type	Description
`count`	`number`	Total number of leads matching the filters (across all pages).
`pageSize`	`number`	Page size used for this response.
`pageNumber`	`number`	Current page (1-based).
`totalPages`	`number`	Total pages for the current filters and `pageSize`.

Lead item (`data[]`)

Field	Type	Description
`id`	`number`	Sodtrack lead id.
`reference`	`string`	`null`
`status`	`string`	Lead status. One of: `"created"`, `"active"`, `"scheduled"`, `"quoted"`, `"in_execution"`, `"sold"`, `"completed"`, `"done"`, `"cancelled"`.
`paymentStatus`	`string`	`null`
`approvalStatus`	`string`	`null`
`cancelReason`	`string`	`null`
`project`	`object`	`null`
`booking`	`object`	`null`
`createdDate`	`string`	Lead creation timestamp.

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	`id must be an integer number` / `id must not be less than 1`	`id` is not a positive integer.
`400 Bad Request`	`customerId must be an integer number` / `customerId must not be less than 1`	`customerId` is not a positive integer.
`400 Bad Request`	`pageSize must not be greater than 50` / `pageSize must not be less than 1`	`pageSize` out of range.
`400 Bad Request`	`pageNumber must not be less than 1`	`pageNumber` out of range.
`401 Unauthorized`	—	API key missing or invalid, or the request does not come from an authorized network.
`403 Forbidden`	—	The request origin is not allowed.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

When the filters match no lead, data is an empty array and metadata.count is 0.

Business Rules & Constraints

Filters

Filters come in pairs that target the same entity through different fields: id / reference on the lead, customerId / customerReference on its customer.
All filters are combined with AND. Sending both members of a pair returns only the leads matching both values; if they point at different records the result is an empty page, not an error.
reference and customerReference are matched exactly. Leading and trailing spaces are ignored.
Sodtrack does not enforce unique lead references, so a reference can return more than one lead.
With no filters, the endpoint returns all leads (paginated), ordered by id descending (newest first).
Deleted leads are never returned.
Unknown query parameters are ignored.

Pagination

pageNumber is 1-based (first page = 1).
Default pageSize is 10; maximum allowed is 50. Out-of-range values are rejected with 400 Bad Request.
metadata.count is the total of matching leads; use it with pageSize to iterate pages.

Data and format

Timestamps use ISO 8601 (UTC).
Query parameter values are passed as strings in the URL; id, customerId, pageSize and pageNumber are coerced to integers before validation.