# get_leads (/docs/mcp/tools/get-leads)

{/* Generated by scripts/sync-mcp-tools.mjs from happierleads-api. Do not edit: change src/routes/mcp/toolDocs.json there, or add content/mcp-notes/get_leads.mdx. */}

**List website leads** · Read-only

List the identified visitors (leads) of one website whose last visit falls in a date range, newest first: the exact person (exactPerson: name, email, phone, LinkedIn, position), their company, visitor location, pages viewed, visits, UTM data, tags and lead scores. Use get_lead for one lead's full page history, get_lead_comments for notes, export_leads_csv for a full file. websiteId comes from list_websites. Read-only. 50 leads per page; totalLeads, totalPages and currentPage tell you where you are, and paginationCapped=true means narrow the dates or filters to reach every lead. Hidden leads are never listed. When nothing matches, emptyStateReason says why (not_verified, too_restrictive_filters, no_leads_in_date_range, no_leads_ever). Results may be up to 60 seconds old.

| Connection | Account URL, team member URL or OAuth |
| --- | --- |

## Parameters [#parameters]

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | `string` | Yes | Website id (24 hex characters) from list_websites. |
| `dateFrom` | `string` | Yes | Start of the range, matched on the lead's last visit date (whole day). Accepts YYYY-MM-DD, MM/DD/YYYY, a full ISO 8601 timestamp or epoch milliseconds. |
| `dateTo` | `string` | Yes | End of the range (inclusive, whole day). Same formats as dateFrom. |
| `page` | `number` | No | Page number, 1-based, 50 leads per page. Default 1; pages beyond 100 return page 100. |
| `domain` | `string` | No | Free-text search across company name and domain, person names and emails, e.g. "acme.example" or "Jane Smith". |
| `industries` | `string` | No | One industry to match (case-insensitive, partial match), e.g. "Software". A single value, not a list. |
| `sectors` | `string` | No | One company sector to match (case-insensitive, partial match). |
| `visitorLocation` | `string` | No | Visitor country as a two-letter ISO code, e.g. "US", "GB" (case-insensitive). |
| `visitorLocationState` | `string` | No | Visitor state/region, e.g. "California". When set without visitorLocation, results are limited to US visitors. |
| `tag` | `string` | No | Tag name (not id) to filter by, e.g. "HOT"; tag names are stored in upper case and matched case-insensitively. Names come from list_tags. |
| `visits_lower_bound` | `number` | No | Minimum number of visits (sessions). Default 0. |
| `visits_upper_bound` | `number` | No | Maximum number of visits (sessions). Leave it out to include every lead, however many visits. |
| `employeesMin` | `number` | No | Smallest company headcount to include, e.g. 10. |
| `employeesMax` | `number` | No | Largest company headcount to include, e.g. 200. |
| `tech` | `string` | No | Technology the company uses, case-insensitive partial match, e.g. "HubSpot", or a JSON array string of several: '["HubSpot","Shopify"]'. |
| `exactVisitor` | `boolean` | No | true to list only leads where the exact person was identified (name and contact details), false for all leads. Leave it out for all leads. |
| `utmSource` | `string` | No | JSON array string of [operator, value] pairs, e.g. '[["contains","google"]]'. Operators: contains, not-contains, starts-with, ends-with. A plain string (not JSON) makes the call fail. |
| `utmMedium` | `string` | No | JSON array string of [operator, value] pairs, e.g. '[["contains","cpc"]]'. Same operators as utmSource. |
| `pageVisited` | `string` | No | JSON array string of [operator, value] pairs matched against visited page paths, e.g. '[["contains","pricing"]]' or '[["not-contains","careers"]]'. Operators: contains, not-contains, starts-with (value without the leading slash), ends-with. A plain string makes the call fail. |

## Tool definition [#tool-definition]

What your assistant receives from `tools/list`:

```json
{
  "name": "get_leads",
  "title": "List website leads",
  "annotations": {
    "title": "List website leads",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "websiteId": {
        "type": "string",
        "description": "Website id (24 hex characters) from list_websites."
      },
      "dateFrom": {
        "type": "string",
        "description": "Start of the range, matched on the lead's last visit date (whole day). Accepts YYYY-MM-DD, MM/DD/YYYY, a full ISO 8601 timestamp or epoch milliseconds."
      },
      "dateTo": {
        "type": "string",
        "description": "End of the range (inclusive, whole day). Same formats as dateFrom."
      },
      "page": {
        "type": "number",
        "description": "Page number, 1-based, 50 leads per page. Default 1; pages beyond 100 return page 100."
      },
      "domain": {
        "type": "string",
        "description": "Free-text search across company name and domain, person names and emails, e.g. \"acme.example\" or \"Jane Smith\"."
      },
      "industries": {
        "type": "string",
        "description": "One industry to match (case-insensitive, partial match), e.g. \"Software\". A single value, not a list."
      },
      "sectors": {
        "type": "string",
        "description": "One company sector to match (case-insensitive, partial match)."
      },
      "visitorLocation": {
        "type": "string",
        "description": "Visitor country as a two-letter ISO code, e.g. \"US\", \"GB\" (case-insensitive)."
      },
      "visitorLocationState": {
        "type": "string",
        "description": "Visitor state/region, e.g. \"California\". When set without visitorLocation, results are limited to US visitors."
      },
      "tag": {
        "type": "string",
        "description": "Tag name (not id) to filter by, e.g. \"HOT\"; tag names are stored in upper case and matched case-insensitively. Names come from list_tags."
      },
      "visits_lower_bound": {
        "type": "number",
        "description": "Minimum number of visits (sessions). Default 0."
      },
      "visits_upper_bound": {
        "type": "number",
        "description": "Maximum number of visits (sessions). Leave it out to include every lead, however many visits."
      },
      "employeesMin": {
        "type": "number",
        "description": "Smallest company headcount to include, e.g. 10."
      },
      "employeesMax": {
        "type": "number",
        "description": "Largest company headcount to include, e.g. 200."
      },
      "tech": {
        "type": "string",
        "description": "Technology the company uses, case-insensitive partial match, e.g. \"HubSpot\", or a JSON array string of several: '[\"HubSpot\",\"Shopify\"]'."
      },
      "exactVisitor": {
        "type": "boolean",
        "description": "true to list only leads where the exact person was identified (name and contact details), false for all leads. Leave it out for all leads."
      },
      "utmSource": {
        "type": "string",
        "description": "JSON array string of [operator, value] pairs, e.g. '[[\"contains\",\"google\"]]'. Operators: contains, not-contains, starts-with, ends-with. A plain string (not JSON) makes the call fail."
      },
      "utmMedium": {
        "type": "string",
        "description": "JSON array string of [operator, value] pairs, e.g. '[[\"contains\",\"cpc\"]]'. Same operators as utmSource."
      },
      "pageVisited": {
        "type": "string",
        "description": "JSON array string of [operator, value] pairs matched against visited page paths, e.g. '[[\"contains\",\"pricing\"]]' or '[[\"not-contains\",\"careers\"]]'. Operators: contains, not-contains, starts-with (value without the leading slash), ends-with. A plain string makes the call fail."
      }
    },
    "required": [
      "websiteId",
      "dateFrom",
      "dateTo"
    ]
  }
}
```