---
title: "Get Leads"
method: GET
path: "/leads"
tags: ["Leads"]
---

# Get Leads

`GET /leads`

Get a list of leads scoped by the query parameters.

## Query parameters

- `id` string — Lead ID
- `phoneNumber` string — The Lead's phone number. Represented as an E.164 Format (i.e +15554441234 for (555) 444-1234 in the US).
- `organizationId` string — Organization ID.
- `groupId` string — A Group ID. This will return a lead that has this group inside of the activeGroupIds array. To also include inactive groups, use the searchInactiveGroups query parameter.
- `leadStatusInGroup` 'active' | 'inactive' | 'all' — When a groupId is passed, this determines whether we look in the activeGroupIds array, inactiveGroupIds array, or both. Defaults to active.
- `cursor` string — Cursor for start of next set of items. Pass whatever you receive from the response to get the next elements in the array.
- `limit` number — Limit of items per page.

## Response `200`

Returns a list of leads that match the query parameters.

- object
  - `items` Lead[], required — List of leads that match the specified filter.
    - `id` string, required — The ID of the lead.
    - `type` 'lead', required — The type of object the attached ID corresponds to.
    - `phoneNumber` string, required — The phone number of the lead. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
    - `organizationId` string, required — The ID of the organization the lead belongs to. The combination of organizationId and phoneNumber represent a lead. Attempting to insert a new lead with these existing values will overwrite the existing lead.
    - `activeGroupIds` string[], required — The IDs of the groups the lead belongs to where they are still active.
    - `inactiveGroupIds` string[], required — The IDs of the groups the lead belongs to where the lead is inactive. Because deleting a lead from a group is not allowed, the only way to stop a lead from receiving messages meant for a group is to make them inactive.
    - `customFields` object, required — The custom fields and associated values for the lead.
    - `firstName` string — The first name of the lead.
    - `lastName` string — The last name of the lead.
    - `notes` string — Notes about the lead.
    - `followUp` string — Follow up comments for the lead.
    - `email` string — The email of the lead.
    - `postalCode` string — The postal (AKA zip) code of the lead.
    - `phoneNumberType` 'mobile' | 'landline' | 'voip' | 'invalid' | 'blacklisted' — The type of phone number of the lead. Older leads or leads that have not been messaged recently may not have this data available.
    - `tagIds` string[], required — The IDs of the tags that have been applied to the lead.
    - `globalOptedOut` boolean, required — Whether or not the lead has opted out of all messages. If this is true, the lead will not receive any messages.
    - `createdAt` string, required — An ISO-8601 string representing the date the agent was created.
  - `cursor` string, nullable, required — Cursor for start of next set of items. If there were no items to return with the last cursor you passed, this will return null.
  - `hasMore` boolean, required — Whether there are more items to load past this cursor.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

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