# Leads - SMB Sales Boost API

Search, filter, and export leads from our database. Supports keyword filtering, location filtering, industry filtering, and pagination.

### How Search Works: Two-Phase Query Model

#### Phase 1 - Include (OR Logic)

All positive keywords and include terms are combined with OR logic. A lead matches if **any** positive keyword matches in **any** of the OR group search columns.

Home Improvement

Business Name, Categories, Profile URL

Other

Registered URL, Crawled URL, Company Name, Categories (AI Enrichment)

#### Phase 2 - Exclude (AND Logic)

Negative keywords are checked against the **same columns** as positive keywords. A lead is excluded if any negative keyword matches in any of those columns.

#### URL Space-to-Wildcard

For URL columns, spaces in search terms are automatically replaced with `%` wildcards. For example, "dental clinic" becomes `%dental%clinic%` to match URLs like `example.com/dental-clinic`.

### AI Category Estimation (Other Database)

Leads in the Other database are progressively enriched by AI with estimated business type categories. Each lead may include an `aiCategoryEstimation` field containing an array of 1-3 category names, or null if not yet classified.

### Endpoints

`GET /api/v1/leads`

Search and filter leads. Requires at least one positive filter (positiveKeywords, nameIncludeTerms, etc.).

`POST /api/v1/leads/export`

Export filtered leads to CSV, JSON, or XLSX. Subject to export rate limits. Supports credit-optimized ordering via maxCredits and maxResults parameters.

`GET /api/v1/leads/other/schema-types`

Returns a sorted list of all distinct website schema types found in the Other leads database. Use these values with the websiteSchemaFilter parameter on GET /api/v1/leads.

### Key Parameters

positiveKeywords (required), negativeKeywords, orColumns, stateInclude, stateExclude, cityInclude, cityExclude, zipInclude, zipExclude, minStars, maxStars, minReviewCount, maxReviewCount, sortBy, sortOrder, page, limit, database, and various column-specific include/exclude terms.

### Credit-Optimized Export Parameters

The export endpoint supports additional parameters for controlling credit usage:

`maxLeads`

Cap total leads exported. Overflow stored in lead reservoir for the next export.

`maxResults`

Cap total results returned (both new and previously-exported leads). New leads are prioritized first, then previously-exported leads fill remaining slots.

`maxCredits`

Cap credits spent on this export. Only new (credit-consuming) leads count toward this cap. Set to 0 to only receive previously-exported leads at no credit cost.

When maxCredits or maxResults is specified, leads are returned in credit-optimized order: new leads (credit-consuming) sorted first, then previously-exported leads, each group sorted by lastUpdated descending (or your custom sort).

---

### API Documentation Sections

[Introduction](/docs/api/introduction) | [Programmatic Purchase](/docs/api/programmatic-purchase) | [Authentication](/docs/api/authentication) | [Rate Limits](/docs/api/rate-limits) | [User Profile](/docs/api/user-profile) | **Leads** | [Filter Presets](/docs/api/filter-presets) | [Keyword Lists](/docs/api/keyword-lists) | [Email Schedules](/docs/api/email-schedules) | [Export Formats](/docs/api/export-formats) | [Export History](/docs/api/export-history) | [Account Settings](/docs/api/account-settings) | [AI Features](/docs/api/ai-features) | [Export Blacklist](/docs/api/export-blacklist) | [Error Handling](/docs/api/error-handling) | [Credits & Subscription](/docs/api/credits-subscription) | [MCP Server](/docs/api/mcp-server) | [Integrations](/docs/api/integrations)

[View Full API Documentation](/docs/api)

---

**Ready to Find Your Next Customers?** Get access to newly registered business leads updated every 5 minutes. [Get Started](/?utm%5Fsource=content&utm%5Fmedium=cta)