Endpoints // Search

Company search

Updated

Search the database for company profiles using multiple filters.

POST/v2/search/companies

Introduction

The Company Search endpoint returns paginated company profiles matching a combination of filters. All filters are optional and combined with AND logic. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.

Use this endpoint to discover companies that match criteria like industry, size, or headquarters location, then chain into Profile for the complete data of any hit.

Authorization

Name	Type	Required	Description
`apikey`	string	Yes	Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header.

Request body

All filters are optional and combined with AND logic. Scalar filters live in the table below; the two nested-object filters (employeeCountRange, location) are documented as expandable field items right after.

Name	Type	Required	Description
`companyName`	string	No	Filter by company name
`companyDomain`	string	No	Filter by company website domain. Disposable domains are rejected with `422`
`industry`	string \| string	No	Industry name or array of industries. See Industry values for the full list
`maxDataAgeDate`	string	No	ISO 8601 datetime. Only returns companies refreshed after this date
`page`	number	No	Page number (1 to 50, default `1`)
`perPage`	number	No	Results per page (1 to 100, default `100`)

Filter validation: filters are validated before the query runs. Unknown field names, blank values, values outside a closed list (industry, location.countryCode) and inconsistent ranges return HTTP 422 with the offending field, the reason and suggested values, and cost 0 credits. Unknown fields are rejected rather than ignored, because an ignored filter would return unfiltered results. See Search filter validation.

Pagination limits: page must be between 1 and 50, and perPage must be between 1 and 100, inclusive, so pagination reaches the first 5,000 matching records. Requests above either limit return HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED. The error.details object identifies the field and maximum, for example { "field": "page", "max": 50 } or { "field": "perPage", "max": 100 }. pageNumber and total still describe the whole matching set, so a search can report more than 50 pages while only the first 50 are retrievable. Narrow your filters or request fewer results per page.

employeeCountRangeobject

Filter by employee count range. Both bounds are optional and inclusive. Headcount is stored as fixed size brackets (1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+), not as an exact number, and a range only matches a bracket it fully contains. Send bracket boundaries, otherwise the range contains no bracket, matches nothing and returns an empty data array. The request is still billed, so check your bounds against the list below.

Show child attributes

Field	Type	Description
`min`	number	Lower bound, inclusive. Must be a bracket start: `1`, `2`, `11`, `51`, `201`, `501`, `1001`, `5001`, `10001`
`max`	number	Upper bound, inclusive. Must be a bracket end: `1`, `10`, `50`, `200`, `500`, `1000`, `5000`, `10000`. Omit it to include `10001+`

Examples: { "min": 11, "max": 50 } matches the 11-50 bracket. { "min": 11, "max": 200 } spans 11-50 and 51-200. { "min": 10001 } matches 10001+. { "min": 11, "max": 20 } returns an empty array, because no whole bracket fits between 11 and 20.

locationobject

Multi-field location filter. Each sub-field is optional and accepts a single string or an array of strings (OR matching). Note: there is no area field here (unlike the person location filter).

Show child attributes

Field	Type	Description
`country`	string \| string	Country name (e.g. `"United States"`)
`countryCode`	string \| string	ISO 3166 country code (e.g. `"US"`)
`region`	string \| string	State or region
`city`	string \| string	City

Response structure

Note: This endpoint uses a nested envelope. The top-level V2 data field wraps an inner search payload that contains the actual results array (data.data) and the pagination info (data.metadata). See the example response for the exact shape.

Field	Type	Description
`success`	boolean	`true` if the request was processed successfully
`error`	`null`	Always `null` on success

data.dataobject[]

Array of matching company profiles wrapped under data.data in the envelope. Empty array if no match.

Show child attributes

Field	Type	Description
`id`	string	ReverseContact company id (`com_...`). Use it as the `id` parameter of the Company Profile endpoint
`name`	string	Company name
`publicId`	string	Universal name / slug (the `/company/xxx` part of the URL)
`linkedinId`	string	Social company identifier
`linkedinUrl`	string \| null	Full Social company URL
`websiteUrl`	string \| null	Official company website URL
`industry`	string \| null	Industry (e.g. `"Software Development"`)
`tagline`	string \| null	Tagline / slogan
`employeesCount`	number	Exact number of employees
`followersCount`	number	Number of Social followers
`employeeCountRange`	EmployeeCountRange \| null	Employee count bracket. `null` if unknown
`companyUpdateDate`	string \| null	When ReverseContact last refreshed this record (ISO 8601)

employeeCountRangeobject

Employee count bracket (null if unknown). Note the start / end field names (different from the request RangeFilter which uses min / max). Buckets mirror LinkedIn's native staffCountRange: 1, 2–10, 11–50, 51–200, 201–500, 501–1,000, 1,001–5,000, 5,001–10,000, 10,001+. For the top bucket (10,001+), LinkedIn has no upper bound and returns end: 1 as a sentinel: interpret any range where end < start as start+ (unbounded). Use employeeCount for the exact headcount when available.

Show child attributes

Field	Type	Description
`start`	number	Lower bound of the range
`end`	number	Upper bound of the range. If `end < start`, the bucket is unbounded (`start+`, i.e. `10,001+`)

Example (10,001+ bucket): { "start": 10001, "end": 1 }. Since end (1) < start (10001), this means the company has 10,001 or more employees. No upper bound is available for this bucket.

locationobject

Primary location of the company (always present, fields may be null)

Show child attributes

Field	Type	Description
`city`	string \| null	City
`country`	string \| null	Country ISO 3166 code (e.g. `"US"`, `"FR"`)

data.metadataobject

Pagination metadata wrapped under data.metadata in the envelope.

Show child attributes

Field	Type	Description
`currentPage`	number	Current page number (1-indexed)
`pageNumber`	number	Total number of pages available
`perPage`	number	Results per page
`total`	number	Total number of matching records across all pages

quotasobject

Credits and rate limit usage after this request

Show child attributes

Field	Type	Description
`creditsConsumed`	number	Credits consumed by this request

workspaceobject

Workspace-level limits

Show child attributes

Field	Type	Description
`id`	string	Your workspace identifier
`hasUnlimitedCredits`	boolean	Whether workspace credits are unlimited
`allowDailyOvercost`	boolean	Whether the workspace may exceed its daily cap

creditsobject

Credit balance

Show child attributes

Field	Type	Description
`total`	number	Total credits in your plan
`used`	number	Credits consumed so far
`left`	number	Remaining credits

dailyLimitobject

Daily request limit (null if not configured)

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per day
`used`	number	Requests made today
`left`	number	Remaining requests today
`nextReset`	string	When the daily window resets (ISO 8601)

minuteRateLimitobject

Per-minute rate limit

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per minute
`used`	number	Requests made in the current minute
`left`	number	Remaining requests in the current minute
`nextReset`	string	When the minute window resets (ISO 8601)

keyobject

API key-level limits (null when request is from dashboard)

Show child attributes

Field	Type	Description
`id`	string	API key identifier

dailyLimitobject

Daily limit for this key (null if not configured)

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per day
`used`	number	Requests made today
`left`	number	Remaining requests today
`nextReset`	string	When the daily window resets (ISO 8601)

minuteRateLimitobject

Minute rate limit for this key

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per minute
`used`	number	Requests made in the current minute
`left`	number	Remaining requests in the current minute
`nextReset`	string	When the minute window resets (ISO 8601)

metadataobject

Request tracking information (not to be confused with data.metadata which is pagination)

Show child attributes

Field	Type	Description
`requestId`	string	Unique identifier for this request
`executionTimeMs`	number	Total execution time in milliseconds

Code examples

Code Examples

curl -X POST https://api.reversecontact.com/v2/search/companies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": ["Software Development", "Technology, Information and Internet"],
    "employeeCountRange": { "min": 50, "max": 500 },
    "location": {
      "country": "United States",
      "city": ["San Francisco", "Austin"]
    },
    "page": 1,
    "perPage": 100
  }'

const response = await fetch("https://api.reversecontact.com/v2/search/companies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    industry: ["Software Development", "Technology, Information and Internet"],
    employeeCountRange: { min: 50, max: 500 },
    location: {
      country: "United States",
      city: ["San Francisco", "Austin"]
    },
    page: 1,
    perPage: 100
  })
});

const payload = await response.json();
const results = payload.data.data;
const pagination = payload.data.metadata;
console.log(`Found ${pagination.total} companies, showing ${results.length} on page ${pagination.currentPage}`);

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/search/companies",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "industry": ["Software Development", "Technology, Information and Internet"],
        "employeeCountRange": {"min": 50, "max": 500},
        "location": {
            "country": "United States",
            "city": ["San Francisco", "Austin"]
        },
        "page": 1,
        "perPage": 100
    }
)

payload = response.json()
results = payload["data"]["data"]
pagination = payload["data"]["metadata"]
print(f"Found {pagination['total']} companies, showing {len(results)} on page {pagination['currentPage']}")

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "com_01jbd5vewyenebxgaz869ffe5t",
        "name": "Acme Corp",
        "publicId": "acme-corp",
        "linkedinId": "12345678",
        "linkedinUrl": "https://www.social.com/company/acme-corp",
        "employeesCount": 452,
        "followersCount": 28512,
        "employeeCountRange": {
          "start": 201,
          "end": 500
        },
        "websiteUrl": "https://www.acmecorp.com",
        "tagline": "Building the future of work",
        "industry": "Software Development",
        "companyUpdateDate": "2026-03-18T09:12:44.000Z",
        "location": {
          "city": "San Francisco",
          "country": "US"
        }
      },
      {
        "id": "com_01k2f8aq3xvznebxgaz869ffe5t",
        "name": "Globex Inc.",
        "publicId": "globex-inc",
        "linkedinId": "98765432",
        "linkedinUrl": "https://www.social.com/company/globex-inc",
        "employeesCount": 187,
        "followersCount": 12340,
        "employeeCountRange": {
          "start": 51,
          "end": 200
        },
        "websiteUrl": "https://www.globex.com",
        "tagline": "Ship faster, ship smarter",
        "industry": "Software Development",
        "companyUpdateDate": "2026-02-27T14:40:05.000Z",
        "location": {
          "city": "Austin",
          "country": "US"
        }
      }
    ],
    "metadata": {
      "currentPage": 1,
      "pageNumber": 2,
      "perPage": 100,
      "total": 184
    }
  },
  "error": null,
  "metadata": {
    "requestId": "req_c1o2m3p4a5n6",
    "executionTimeMs": 280
  },
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4523,
        "left": 5477
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 6,
        "left": 54,
        "nextReset": "2025-01-20T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 6,
        "left": 54,
        "nextReset": "2025-01-20T14:16:00.000Z"
      }
    }
  }
}