Developer hub REST API

API Documentation

Bring SearchLeads into your workflow. Find prospects, build audiences, and export the data you need.

On this page

From API key to your first results in three steps.

1
Create your API key
Enable the search scope in your API key settings.
2
Choose your audience
Set the search type and filters. Explore available filters
3
Send your request
Replace the key placeholder and run this example to request one prospect.

Returned prospects use your export credits.

Your first search · cURL

curl -X POST "https://pro.searchleads.co/functions/v1/people-search" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "textFilters": {
      "contact.keyword": "sales"
    },
    "page": 0,
    "size": 1
  }'

Rate limit

60/min

Daily allowance

10000 requests

People search cost

0.5 credits / prospect

Authentication

API key

People Search API responses return prospect data and therefore use the export-credit bucket per returned prospect. This does not create an export job.

POSThttps://pro.searchleads.co/functions/v1/people-search

This route is named people-search for compatibility, but it is the shared endpoint for both people and company searches. Set searchType to people or company in the JSON body.

Company Search is Admin controlled by hide_company_search. When hidden, company navigation is removed, company requests are rejected, and company filters are omitted from account capabilities. Current enabled search types: people, company.

Company-only: lookalikeDomains works only with searchType: "company". It will be rejected for people searches; use account.domain to target people at known company domains.

Pass your API key in the request header. Sign in to create API keys and generate them from your SearchLeads account settings.

Key scopessearch / export / mcp

Search endpointsearch scope

Hosted MCPmcp scope

HTTP header

x-searchleads-api-key: sl_live_your_full_api_key_here

Replace the placeholder with the full API key. Keys are shown once at creation; the prefix listed later is not usable for API or MCP authentication. Store the full key securely — do not expose it in client-side code or commit it to version control.

All search parameters are passed as JSON body fields:

Field	Type	Description
`searchType`	string	Target search type. Use "people" or "company". Default: "people".
`filters`	object	Structured include filters only. Use this for arrays, enums, ranges, and metric filters. Employee Count accepts one range object or an array of range objects. See the Filter Reference “Send In” column below.
`excludedFilters`	object	Exclusion bucket for any field. Use the same keys you would otherwise send, but pass the values you want removed from results.
`textFilters`	object	Free-text include filters only. Values are plain strings, not arrays (for example contact.keyword or contact.fullName).
`filterRules`	object	Optional per-filter matching rules, such as matchAll, exclude, search mode, keyword sources, or metric rows.
`page`	number	Zero-indexed page number. Default: 0.
`size`	number	Results per page. Default: 25. Max: 100.
`sortBy`	string	Field to sort by (e.g. "contact.fullName").
`sortOrder`	string	"asc" or "desc". Default: "desc".
`search_after`	array	Optional Elasticsearch cursor returned by a prior request. Use this for deep pagination instead of increasing page beyond the 10k from/size window.
`listId`	string	Legacy alias for one included application list. Existing saved searches and API payloads remain supported.
`list_filters`	array	Optional list filters: [{ "listId": "…", "operator": "include" \| "exclude" }]. Included lists are ANDed; excluded lists are removed. Ownership and active lookup versions are validated server-side.
`record_summary`	object	Optional Saved/Net New scope only: { "enabled": true, "savedListIds": ["…"], "matchMode": "any" \| "all" }. It only filters results when savedOnly or netNewOnly is true. Omit it for the account-wide saved set.
`netNewOnly`	boolean	When true, exclude the record_summary scope. For list summaries, any excludes the union and all excludes only records belonging to every selected list.
`savedOnly`	boolean	When true, return only the record_summary scope. Cannot be combined with netNewOnly.

Unknown top-level fields are ignored by the search endpoint. Filter access and allowed values are enforced from the live capabilities contract for the authenticated user/API key.

Option Discovery Then Search

cURL

# Optional: discover current catalog values. This lookup is authenticated but does not run a search or charge search/export credits.
curl -X POST "https://pro.searchleads.co/functions/v1/filter-options" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "field": "account.industry",
    "query": "software",
    "limit": 30
  }'

# Submit the exact readable value (options[].label is accepted), or options[].id for backward compatibility.
curl -X POST "https://pro.searchleads.co/functions/v1/people-search" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "filters": {
      "account.industry": ["Software Development"]
    },
    "page": 0,
    "size": 25
  }'

Advanced Search (ranges, exclusions, text filters)

cURL

curl -X POST "https://pro.searchleads.co/functions/v1/people-search" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "filters": {
      "account.industry": ["Software Development"],
      "account.employeeSize": {"min": 50, "max": 500},
      "account.revenue": {"min": 5000000, "max": 100000000},
      "contact.seniority": ["Founder"],
      "account.technology": ["HubSpot"]
    },
    "excludedFilters": {
      "account.location": ["India"]
    },
    "textFilters": {
      "contact.keyword": "outbound sales"
    },
    "page": 0,
    "size": 50
  }'

Successful 200 response structure:

JSON

{
  "results": {
    "totalElements": 18432,
    "recordCounts": {
      "totalRecords": 18432,
      "savedRecords": 213,
      "netNewRecords": 18219,
      "savedRecordScope": "query"
    },
    "content": [
      {
        "id": "abc123",
        "firstName": "Sarah",
        "lastName": "Chen",
        "name": "Sarah Chen",
        "title": "CEO",
        "linkedinUrl": "https://linkedin.com/in/sarahchen",
        "organization": { "name": "Example Company", "industry": "Business Services", "employeeCount": 120 }
      }
    ],
    "results": ["// Deprecated version 1 duplicate of content"]
  },
  "search_id": "9e9013ff-b8af-4f85-b4dc-3e0c995da0c1",
  "search_id_expires_at": "2026-04-22T09:15:00.000Z",
  "rate_limits": {
    "per_minute": { "limit": 60, "remaining": 59 },
    "per_day": { "limit": 10000, "remaining": 9999 }
  },
  "meta": {
    "responseVersion": 1,
    "page": 0,
    "size": 25,
    "searchId": "9e9013ff-b8af-4f85-b4dc-3e0c995da0c1"
  }
}

Results are paginated. Use the page (0-indexed) and size fields to navigate:

cURL

# Page 1: first 25 results
{ "page": 0, "size": 25 }

# Page 2: next 25 results
{ "page": 1, "size": 25 }

# Larger pages (max 100)
{ "page": 0, "size": 100 }

The response includes totalElements — the total number of matching prospects across all pages. To fetch all results, loop until page * size >= totalElements.

Each paginated request counts as 1 API call against your rate limit. People search billing is calculated from returned prospects using the Admin Config per-prospect rate.

Rate Limit Headers

Every response includes these headers so you can implement proper backoff:

X-RateLimit-Limit60Max requests per 60-second window

X-RateLimit-Remaining43Requests remaining in current window

X-RateLimit-Reset1741234567Unix timestamp when window resets

Retry-After17Seconds to wait when rate limited (429 only)

Error Codes

Status	Meaning	Action
400	Bad Request	Missing required fields or invalid filter format. Check the `error` string for details.
401	Unauthorized	API key missing, expired, or invalid. Ensure the x-searchleads-api-key header is correct.
403	Forbidden	Your plan does not have access to this filter or feature.
422	Insufficient Credits	Not enough credits to perform this query. Top up your account.
429	Rate Limited	Exceeded 60 requests/minute. Check the Retry-After header and wait before retrying.
500	Internal Error	Unexpected server error. Retry with exponential backoff.

Backoff Strategy

On 429 responses, read the Retry-After header and wait that many seconds before retrying. For 500 errors, use exponential backoff: 1s → 2s → 4s → 8s.

Use the authenticated capabilities endpoint to discover the exact filters, limits, allowed values, visible search types, export settings, and current rate-limit state for the signed-in user or API key owner.

Endpointhttps://pro.searchleads.co/functions/v1/api-capabilities

Visible search typespeople, company

search_id TTL1440 minutes

This is the same machine-readable contract used by the hosted MCP server and this docs page, so external clients can stay aligned with SearchLeads permissions and admin restrictions.

cURL

curl -X GET "https://pro.searchleads.co/functions/v1/api-capabilities?search_type=all&option_sample_limit=6" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here"

AI-readable filter contract

Each filter includes acceptedValueType, acceptedValueTypeV2, valueShape, acceptsCustomValues, and allowedValueBehavior. AI tools should treat selected_option_labels as a legacy type token. For catalog-backed filters, submit an exact current options[].label directly; the returned options[].id remains supported for existing integrations. Call filter-options when discovery or cursor pagination is needed.

JSON

{
  "endpoint": "https://pro.searchleads.co/functions/v1/people-search",
  "auth_header": "x-searchleads-api-key",
  "request_rules": [
    "Use searchType: people or company.",
    "Use filters for arrays, select options, ranges, metrics, domains, and exclusions.",
    "Use textFilters for free-text include fields only.",
    "For catalog-backed filters, submit the exact readable value chosen in API Docs. Option IDs remain accepted only for backward compatibility.",
    "For free_text_* fields, send short terms, not full prompts or sentences.",
    "For range_min_max fields, send { min, max } only when the prompt supports the constraint. Employee Count also accepts an array of range objects and ORs them; one range object remains supported."
  ],
  "sample_filters": []
}

Catalog-backed filters (for example Industry, Seniority, Technology, Hiring, and Funding Type) accept an exact current readable value. Submit options[].label directly, or keep sending the returned options[].id for backward compatibility. Use this endpoint to discover current values or page through large catalogs; the lookup does not create a search or charge credits.

Endpointhttps://pro.searchleads.co/functions/v1/filter-options

API-key scopesearch

Page maximum100 options

Typed-input fields such as domains, LinkedIn URLs, websites, and phones do not need option discovery. A valid exact value may still return zero records when it is absent from the indexed data.

Complete catalog discovery is cursor-paginated: request up to 100 options per page, then send the previous response's nextCursor as cursor while hasMore is true. Cursors are bound to the field and query, so do not reuse one for another lookup.

Static quick reference

Copy these readable values directly into filters. These compact lists cover the current bounded catalogs; use the picker below to browse all values in larger catalogs.

Seniority:

Department:

Email Status:

Mobile Available:

Last Funding Type:

Catalog values are loaded in pages and can be searched by name. Technologies, skills, locations, NAICS, personas, industries, and lead investors use the same cursor-paginated picker so large or frequently changing catalogs remain responsive.

Choose a filter value

Pick a live catalog value and copy the readable value to use in your request.

cURL

# Optional: discover current catalog values. This lookup is authenticated but does not run a search or charge search/export credits.
curl -X POST "https://pro.searchleads.co/functions/v1/filter-options" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "field": "account.industry",
    "query": "software",
    "limit": 30
  }'

# Submit the exact readable value (options[].label is accepted), or options[].id for backward compatibility.
curl -X POST "https://pro.searchleads.co/functions/v1/people-search" \
  -H "Content-Type: application/json" \
  -H "x-searchleads-api-key: sl_live_your_full_api_key_here" \
  -d '{
    "searchType": "people",
    "filters": {
      "account.industry": ["Software Development"]
    },
    "page": 0,
    "size": 25
  }'

Loading filters…Open a field’s values for rules and a copyable example.

How to format filter values

Use the Send In column for include values. Free-text include fields go in textFilters; structured, select, range, and metric fields go in filters. Use excludedFilters for exclusions of any field. Range filters use { min, max } objects. Exact domain and LinkedIn filters accept up to 10,000 normalized values per request and are chunked into Elasticsearch terms clauses. Other fields use the authenticated capability limit. The Search column shows whether a field works with people search, company search, or both. lookalikeDomains is intentionally listed as company-only.

Loading filter reference...

SearchLeads exposes a hosted Streamable HTTP MCP endpoint so Claude and other MCP-compatible AI tools can call account capabilities, filter discovery, search, export, reusable prompts, and authenticated resources directly with your SearchLeads API key.

TransportStreamable HTTP

Endpointhttps://pro.searchleads.co/functions/v1/searchleads-mcp

Required key scopemcp

Built-in toolsget_account_capabilities

Built-in toolslist_filter_catalog

Built-in toolslookup_filter_options

Built-in toolssearch_prospects

Built-in toolsstart_export / get_export_status

Built-in promptsplan_filters / explain_search_results

Built-in promptsdraft_outreach_copy

Resourcesmcp-overview / account capabilities

Resourcespeople filters / company filters

The hosted server supports tool discovery plus prompts/list, prompts/get, resources/list, and resources/read for better MCP-native discovery.

Catalog-backed filters accept exact readable values. Call lookup_filter_options when an agent needs discovery or pagination; returned option IDs remain backward compatible. Typed-input filters report their mode and accept direct normalized values.

Client config formats vary, but the generic shape is an HTTP MCP server URL plus the SearchLeads API key header:

JSON

{
  "mcpServers": {
    "searchleads": {
      "type": "http",
      "url": "https://pro.searchleads.co/functions/v1/searchleads-mcp",
      "headers": {
        "x-searchleads-api-key": "sl_live_your_full_api_key_here"
      }
    }
  }
}

API Documentation

Make your first request

Endpoint

Authentication

Request Body

Code Examples

Sample Response

Pagination

Rate Limits & Errors

Capabilities Endpoint

Discover Filter Options

Filter Reference

Hosted MCP