---
title: "Get Leads"
method: GET
path: "/crm/leads"
tags: ["CRM Service Calls"]
---

# Get Leads

`GET /crm/leads`

Retrieve leads with optional filtering, sorting, pagination, and date range.

Returns a list of leads matching your criteria. Without any filters, returns the most
recent leads sorted by creation date (newest first).

**Time-based filtering (start_date / end_date):**

Use `start_date` and `end_date` query parameters to filter leads by creation date.
Both accept **ISO 8601 UTC** strings. When provided, only leads created within
that range are returned.

- Format: `YYYY-MM-DDTHH:MM:SSZ` (full) or `YYYY-MM-DD` (date only, treated as midnight UTC)
- Both are optional — you can provide just `start_date` (everything after), just `end_date`
  (everything before), or both for a specific window.
- **Do NOT pass date/timestamp fields inside `match_filter_dict`** — use these dedicated
  query parameters instead.

**Example requests:**

- All leads (no date filter):
  `GET /leads`
- Leads created in the last 7 days:
  `GET /leads?start_date=2026-03-22T00:00:00Z&end_date=2026-03-29T23:59:59Z`
- Leads created since March 1st:
  `GET /leads?start_date=2026-03-01`
- Leads created before a specific date:
  `GET /leads?end_date=2026-03-15T23:59:59Z`
- Leads from Google created in the last 7 days:
  `GET /leads?start_date=2026-03-22&end_date=2026-03-29&match_filter_dict={"lead_source": "Google"}`

**Other Query Parameters:**

- **match_filter_dict** *(optional)*: JSON-encoded MongoDB query to filter leads by
  non-date fields. Filterable fields: `lead_status`, `lead_source`, `name`, `email_list`,
  `phone_list`, `tags`, `employer_name`, `profession`, `title`.
  Examples:
    - `{"lead_status": "contacted"}` — only contacted leads
    - `{"lead_source": "Google"}` — leads from Google
    - `{"tags": {"$in": ["vip"]}}` — leads tagged "vip"
    - `{"_id": {"$in": ["ObjectId('64a856b9c9ac463f751ba187')"]}}` — lookup by ID (requires eval_object_id=true)
- **eval_object_id** *(default: false)*: Set to true when your filter uses `ObjectId('...')` syntax.
- **sort_dict** *(default: {"_id": -1})*: JSON-encoded sort criteria.
  Example: `{"created_ts": 1}` for oldest first.
- **page_size** *(default: 50, max: 500)*: Number of records per page.
- **page_num** *(default: 1)*: Page number (1-indexed).

**Response:** Paginated object with `leads` array, `page_size`, and `page_num`.

## Query parameters

- `match_filter_dict` string
- `eval_object_id` boolean
- `sort_dict` string
- `page_size` integer
- `page_num` integer
- `start_date` string, nullable — Start of date range in ISO 8601 format (e.g. 2026-03-22T00:00:00Z or 2026-03-22). UTC.
- `end_date` string, nullable — End of date range in ISO 8601 format (e.g. 2026-03-29T23:59:59Z or 2026-03-29). UTC.

## Response `200`

Successful Response

- LeadResponseList — Paginated list of leads.
  - `leads` LeadResponse[], required
    - `id` string, required
    - `phone_list` unknown[], nullable, required
      - unknown
    - `email_list` unknown[], nullable, required
      - unknown
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `name` string, required
    - `status` string, required
    - `marketing_source` string, nullable
    - `created_date` string, nullable, required
    - `updated_date` string, nullable, required
    - `status_updated_date` string, nullable, required
    - `tags` string[], nullable
    - `social_dict_list` object[], nullable
    - `is_converted` boolean — Whether lead has been converted to contact
    - `contact_id` string, nullable — Contact ID if converted
    - `has_deal` boolean — Whether a deal/opportunity exists
    - `deal_stage` string, nullable — Current deal stage if exists
    - `deal_id` string, nullable — Deal/Opportunity ID if exists
    - `value_of_sale` number, nullable — Value of sale for the deal if exists
    - `close_date` string, nullable — Close date of the deal in ISO 8601 format
  - `page_size` integer, required
  - `page_num` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/ambivo/apis/ambivo-api.md) · [All operations](https://skmtc.net/ambivo/apis/ambivo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ambivo/ambivo-api/versions/165a6d16a9a0/schema)