Search Companies

Search the company database. One call uses one page of the daily search budget.

POSThttps://api.foxreach.io/api/v1/lead-finder/companies/search

Requires an API key with the read scope.

A company page costs the same as a people page and counts against the same daily search budget. It needs a paid plan. Company filters have their own keys; see companyFilterKeys in Get Filter Options.

Body Parameters#

filtersobjectbodyrequired

Company filters. At least one filter besides countries is required.

pageSizeintegerbodyDefault: 25

Results per page, 1 to 50.

pageTokenstringbody

The nextPageToken from the previous page.

Response#

dataobject

One page of results.

Show data

totalinteger

Matching companies across all pages.

companiesarray

The page.

Show companies

idstring

Company identifier.

namestring

Company name.

domainstring

Domain.

linkedinIdstring

LinkedIn public id.

linkedinUrlstring

LinkedIn company URL.

logoUrlstring

Logo URL.

descriptionstring

Description.

locationstring

Headquarters location.

industrystring

Industry.

typestring

Company type.

employeesinteger

Headcount.

employeeRangestring

Headcount range.

revenueRangestring

Revenue range.

growth12minteger

12-month headcount growth, percent.

specialtiesarray

Listed specialties.

nextPageTokenstring

Pass as pageToken for the next page. null on the last page.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `read`
`400`	`country_not_available` when a requested country is outside the covered list (`{"detail": {"code": "country_not_available", "message": "...", "allowed": [], "blocked": []}}`); `unknown_filter_keys` naming each key that does not exist (`{"detail": {"code": "unknown_filter_keys", "message": "...", "unknownKeys": [], "validKeys": []}}`); or a message asking for at least one filter besides `countries`
`403`	`upgrade_required` on the Free plan: `{"detail": {"code": "upgrade_required", "limit_type": "lead_finder", "message": "..."}}`. A missing scope also returns 403 with a plain `detail` string
`404`	`Lead Finder is not enabled` while Lead Finder is switched off on this environment
`422`	`pageSize` outside 1-50
`429`	`lead_finder_search_cap` when today's search budget is used up: `{"detail": {"code": "lead_finder_search_cap", "message": "...", "used": 20, "allowance": 20, "revealsToday": 0}}`. Revealing emails raises the allowance, or retry tomorrow
`502`	`The data provider is unavailable right now`
`503`	`Lead Finder is not configured` when it is enabled but has no data provider key

Rate Limit#

100 requests per minute, per API key. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch seconds).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Request

curl -X POST "https://api.foxreach.io/api/v1/lead-finder/companies/search" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"industries": ["Computer Software"], "minHeadcount": 50}, "pageSize": 25}'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
page = client.lead_finder.search_companies({"industries": ["Computer Software"], "minHeadcount": 50})

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const page = await client.leadFinder.companiesSearch({
  filters: { industries: ["Computer Software"], minHeadcount: 50 },
});

Response

{
  "data": {
    "total": 4120,
    "companies": [
      {
        "id": "co_abc123",
        "name": "Acme Inc",
        "domain": "acme.com",
        "linkedinId": "acme",
        "linkedinUrl": "https://www.linkedin.com/company/acme",
        "logoUrl": null,
        "description": "Acme makes scheduling software.",
        "location": "Austin, Texas, United States",
        "industry": "Computer Software",
        "type": "Privately Held",
        "employees": 120,
        "employeeRange": "51-200",
        "revenueRange": null,
        "growth12m": 18,
        "specialties": ["Scheduling"]
      }
    ],
    "nextPageToken": "eyJwIjoyfQ"
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026