---
title: "Browse Leads"
method: GET
path: "/api/v1/leads"
tags: ["leads", "leads"]
---

# Browse Leads

`GET /api/v1/leads`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/leads`
- Auth: API key in header `X-API-Key`

Browse leads with dynamic filters and pagination.

Filters are passed as a JSON-encoded query parameter:
?filters=[{"field":"reachability_tier","op":"eq","value":"On Fire"}]

By default, non-operating entities (enrichment_strategy='hold') are
excluded. Set include_non_operating=true to see the full inventory,
or pass an explicit enrichment_strategy filter to audit just the
held cohort.

Commerce free/paid boundary: when ENABLE_COMMERCE=True, contact fields
(email, phone, contact_name) are masked unless the caller presents a
valid X-API-Key. The response includes `access_level` so the frontend
can render an "unlock" affordance.

## Query parameters

- `state` string, nullable
- `filters` string, nullable: JSON-encoded filter array
- `page` integer
- `page_size` integer
- `sort` string: Sort column (legacy, paired with sort_dir) OR a JSON array of sort keys [{"field": "reachability_tier", "dir": "desc"}, {"field": "formation_date", "dir": "desc"}] for multi-key sort. Any field flagged sortable on /schema/attributes; tier fields sort by rank. Unknown field or direction → 422 listing the sortable fields.
- `sort_dir` string: asc or desc (legacy; ignored when sort is a JSON array)
- `include_non_operating` boolean: Include records the Contact Intelligence brain marked enrichment_strategy='hold' (shell LLCs, single-asset holdings, vehicles for real estate or a car). Default False — sellable inventory only.
- `include_existing` boolean: Include existing businesses with a new filing: companies opening a location here, local owners who formed their company in another state, businesses back in business, established businesses under a new entity, moved, or with a new trade name. Default False — Just started only (a brand-new business), matching every file sold as new businesses. Naming a filing_kind in `filters` implies it.
- `include_registrations` boolean: Deprecated alias of include_existing (kept one release so saved links resolve).
- `include_channels` boolean: Attach ranked alternate contact channels to each row: phone_2..phone_5 (+ per-phone line type), email_2..email_3 (+ per-email deliverability status), and the primary email's activity recency. Ordered by the same ranking the primary-selection brains use. Default False — the Browse grid doesn't pay for the extra query.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)