Search companies
From the Leads API reference. Requests use the base URL https://app.warmerly.com/api/v1 and an API key, see Authentication.
GET /leads/search| Query param | Type | Required | Description |
|---|---|---|---|
q | string (max 200) | No | Full-text search across company name, description, and other indexed fields. |
country | string (exactly 2 letters) | No | ISO country code, e.g. GB. |
category | string (max 400) | No | One or more categories, comma-separated (e.g. Restaurant,CafeOrCoffeeShop). Matches a company's declared business type or industry exactly. |
provider | string (max 100) | No | Email provider segment, e.g. google, microsoft. |
tech | string (max 300) | No | One or more technologies, comma-separated (e.g. shopify,klaviyo), matches companies using any of them. |
channel | "email" \| "form" \| "linkedin" | No | Which contact channel a company must have. Defaults to email: a company with no published contact address is never returned unless you ask for a different channel. form returns companies publishing a contact form, linkedin those with a company page. There is no value that removes the requirement. |
hasPhone | "true" | No | Only companies publishing a telephone number. The flag filters (this one and the next four) accept "true" or "false"; "false" narrows nothing, and any other value returns 400 invalid_filters. |
hasCompanyNumber | "true" | No | Only companies publishing a Companies House registration number, in practice, UK-registered. |
hasVatNumber | "true" | No | Only companies publishing a VAT number. |
hiring | "true" | No | Only companies linking a careers page or stating they are hiring. |
hasContactForm | "true" | No | Only companies publishing a contact form URL. |
city | string (max 120) | No | Town or city, matched through the same text index as q. |
employeeBand | string (max 20) | No | One coarse size band, e.g. 11-50. Exact match, not a range. |
foundedFrom / foundedTo | integer (1200-2100) | No | Inclusive founded-year range. |
cursor | string (UUID) | No | Pass the previous response's nextCursor to fetch the next page. |
limit | integer (1-100) | No | Page size. Default 50. |
Parameters that fail validation return 400 bad_request with the message invalid_filters.
curl "https://app.warmerly.com/api/v1/leads/search?country=GB&category=Restaurant&tech=shopify&limit=25" \
-H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"rows": [
{ "id": "b1e6a2c4-9f3d-4a7e-8c1b-2d5f9a3e7c6b", "domain": "northwindtraders.com", "...": "every other field of the company object" }
],
"nextCursor": "b1e6a2c4-9f3d-4a7e-8c1b-2d5f9a3e7c6b"
}Each row is the full company object. The response holds rows only: the number of matches and how complete the records are come from GET /leads/count. nextCursor is null on the last page; keep paging with it until it is null. With channel=form or channel=linkedin a row's contactEmail can be null.
This endpoint has its own per-user throttle, separate from your API key's per-minute rate limit, see Rate limits below.
Was this page helpful?