---
title: "Retrieve a list of Leads"
method: GET
path: "/v2/leads"
tags: ["Leads"]
---

# Retrieve a list of Leads

`GET /v2/leads`

Retrieves a paginated list of Leads, optionally filtered by date range.

## Query parameters

- `pageSize` number
- `page` number
- `field` 'created' | 'updated' | 'statusUpdated' | 'utcUpdated'
- `order` 'ASC' | 'DESC'
- `isOpen` boolean
- `dateProperty` 'date' | 'endDate' | 'utcUpdated' | 'created'
- `dateOperator` 'prev' | 'next' | 'between'
- `date` string

## Headers

- `Authorization` string, required

## Response `200`

A paginated list of Leads.

- ResponseLeadsV2Dto
  - `pageSize` number — The maximum number of items returned per page.
  - `page` number — The current page number.
  - `totalResults` number — The total number of results.
  - `hasMore` boolean — Whether there are more results.
  - `data` ResponseLeadV2Dto[] — A list of Leads.
    - `id` string — The ID of the lead (prefix `LD-`).
    - `uuid` string — The UUID of the lead.
    - `serialId` number — The serial ID of the lead.
    - `status` string — The status of the lead.
    - `date` string, date-time — The date and time when the lead is scheduled.
    - `endDate` string, date-time — The date and time when the lead is scheduled to end.
    - `isAllDay` boolean — Whether the lead is all day.
    - `isScheduled` boolean — Whether the lead is scheduled.
    - `jobType` ResponseGenericJobTypeV2Dto
      - `id` string — The ID of the job type (prefix `JT-`).
      - `name` string — The name of the job type.
    - `adGroup` ResponseGenericAdGroupV2Dto
      - `id` string — The ID of the ad group (prefix `AG-`).
      - `name` string — The name of the ad group.
    - `description` string — The description of the lead.
    - `leadLost` boolean — Whether the lead was marked as lost.
    - `clientInfo` ResponseJobLeadDetailsV2Dto
      - `clientId` string — The ID of the associated client (prefix `CL-`).
      - `serialId` number — The serial ID of the client.
      - `firstName` string — The first name of the client.
      - `lastName` string — The last name of the client.
      - `companyName` string — The company name of the client.
      - `email` string — The email address of the client.
      - `primaryExt` string — The primary extension of the client.
      - `primaryPhone` string — The primary phone of the client.
      - `secondaryExt` string — The secondary extension of the client.
      - `secondaryPhone` string — The secondary phone of the client.
      - `addressDetails` ResponseJobLeadAddressV2Dto
        - `country` string — The country of the client.
        - `state` string — The state of the client.
        - `city` string — The city of the client.
        - `zipCode` string — The zip code of the client.
        - `address` string — The address of the client.
        - `unit` string — The unit of the client.
        - `latitude` number — The latitude of the client.
        - `longitude` number — The longitude of the client.
        - `locationKey` string — The location key of the client.
      - `serviceArea` ResponseGenericServiceAreaV2Dto
        - `id` string — The ID of the service area (prefix `SA-`).
        - `name` string — The name of the service area.
    - `team` ResponseGenericTechV2Dto[] — A list of lead technicians.
      - `id` string — The ID of the technician (prefix `USR-`).
      - `name` string — The name of the technician.
    - `tags` ResponseGenericTagV2Dto[] — A list of Tags.
      - `id` string — The ID of the tag (prefix `TAG-`).
      - `name` string — The name of the tag.
    - `customFields` ResponseGenericCustomFieldV2Dto[] — A list of Custom Fields.
      - `id` string — The ID of the custom field (prefix `CF-`).
      - `fieldName` string — The name of the custom field.
      - `value` union — The value of the custom field. Can be string, number, boolean, date string, or an array of file objects.
        - string — A string value.
        - number — A number value.
        - boolean — A boolean value.
        - object[]
          - `name` string — The name of the file.
          - `url` string — The URL of the file.
    - `notes` ResponseJobLeadNoteV2Dto[] — A list of Notes.
      - `id` string — The ID of the note (prefix `JNT-`).
      - `techName` string — The name of the technician who created the note.
      - `note` string — The note.
      - `timestamp` string, date-time — The date and time when the note was made.
    - `statusUpdated` string, date-time — The date and time when the lead status was last updated (based on account timezone).
    - `updatedAt` string, date-time — The date and time when the lead was last updated (based on account timezone).
    - `createdAt` string, date-time — The date and time when the lead was created (based on account timezone).

## Other responses

- `400` — Invalid query parameters.
- `401` — Missing or invalid authentication token.

---

[API](https://skmtc.net/workiz/apis/developer-api.md) · [All operations](https://skmtc.net/workiz/apis/developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/workiz/developer-api/revisions/14666f4db0f8/schema)