Organization search

Introduction

The Organization Search endpoint returns full organization profiles matching a combination of filters. Filters are combined with AND logic. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.

Every result is a complete profile, the same shape the Company profile endpoint returns, so you do not need a second call to get the full data of a hit. Use the free Organization search count endpoint to check how many organizations match before you spend credits.

Coming from POST /v2/search/companies? See Migrating company search to organizations.

Authorization

Request body

Every filter is optional, but a request needs at least one, and filters are combined with AND logic. Scalar filters live in the table below; the nested-object filters (employeeCountRange, foundedYear, followersCount, location) are documented as expandable field items right after, and pagination (cursor, perPage) closes the section.

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. Each list filter accepts at most 20 values. See Search filter validation.

At least one filter: a body with only cursor and perPage returns HTTP 422 with NO_FILTER_PROVIDED. maxDataAgeDate narrows a search but selects nothing on its own, so a request whose only filter is maxDataAgeDate returns NO_FILTER_PROVIDED too. followersCount sent as the only filter needs both min and max, otherwise the request returns INCOMPLETE_RANGE_FILTER. None of these requests costs credits.

Note: industry is matched exactly against the industry list. Case, surrounding spaces, accents and & versus and are normalized for you, and any other unlisted value returns HTTP 422 with INVALID_FILTER_VALUE and up to three suggested values, never an empty page.

Ranges: bounds are whole numbers, min must not be greater than max, and a bound outside the accepted interval (for example a foundedYear.max of 2200) returns HTTP 422 with INVALID_RANGE and the accepted maximum in error.details. The request costs 0 credits.

Specialities

specialities matches the specialities an organization lists on its profile, such as "SaaS" or "Machine Learning". Matching is word-based, not exact: case and accents are ignored, and every word of a value must appear among the organization's specialities, so "SaaS" also matches an organization that lists "B2B SaaS". A list is OR-matched: an organization matches when it lists at least one of the requested specialities.

curl -X POST https://api.reversecontact.com/v2/search/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specialities": ["SaaS", "Machine Learning"],
    "foundedYear": { "min": 2015 },
    "location": { "countryCode": "DE", "city": "München" },
    "perPage": 25
  }'

Tip: a very broad query, such as one common industry on its own, has to rank a very large set of organizations and can be slow or time out with HTTP 504, which costs 0 credits. Pair it with an employee count range, a founding year or a precise location to keep the search fast.

Pagination and credits

Organization search uses cursor pagination. Each response returns up to perPage organizations (1 to 100, default 25) and a metadata.nextCursor value. Pass that value back as cursor in the next request, with the same filters, to get the following page; nextCursor is null on the last page. The cursor is opaque: send it back unchanged, without parsing or altering it. perPage may change from one page to the next.

There is no page parameter. A request that sends page returns HTTP 422 with error.code UNKNOWN_FIELD, and the error names cursor as its replacement.

The cursor does not expire, and a long pause between two pages is fine: the next page picks up where the previous one stopped. If organizations were refreshed in the meantime, one of them can occasionally repeat or be skipped at the page boundary. When the last page is exactly full, its nextCursor is not null yet, and the request it leads to returns an empty page, which costs 0 credits.

An invalid cursor returns HTTP 400 with the message Invalid or expired cursor. This happens when a filter is changed between two pages (keep the filters identical and only add the cursor), or when the cursor is malformed (truncated or altered).

perPage above 100 returns HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED, and the error.details object identifies the field and maximum, for example { "field": "perPage", "max": 100 }. A perPage that is not a whole number returns HTTP 422 with error.code INVALID_PAGINATION.

Organization search costs 1 credit per organization delivered. Organizations removed for compliance reasons before the response are not billed. A page that returns 25 organizations costs 25 credits, and a page that returns no organization costs 0 credits. Before it runs, a request needs as many credits available as its perPage: with fewer, it returns HTTP 402 with INSUFFICIENT_CREDITS and costs nothing. Check the size of a query first with the free Organization search count endpoint, and lower perPage to control how many credits a single request can spend.

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.

Code examples

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

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

  return response.json();
};

const firstPage = await searchPage();
const organizations = firstPage.data.data;
const { count, nextCursor } = firstPage.data.metadata;
console.log(`Got ${count} organizations, credits used: ${firstPage.quotas.creditsConsumed}`);

if (nextCursor) {
  const secondPage = await searchPage(nextCursor);
  organizations.push(...secondPage.data.data);
}

import requests

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

payload = response.json()
organizations = payload["data"]["data"]
metadata = payload["data"]["metadata"]
print(f"Got {metadata['count']} organizations, next cursor: {metadata['nextCursor']}")

Example response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "com_01jbd5vewyenebxgaz869ffe5t",
        "companyName": "Acme Corp",
        "linkedinId": "12345678",
        "publicId": "acme",
        "linkedinUrl": "https://www.social.com/company/acme",
        "employeesCount": 452,
        "followersCount": 28512,
        "employeeCountRange": {
          "start": 201,
          "end": 500
        },
        "websiteUrl": "https://www.acmecorp.com",
        "tagline": "Building the future of work",
        "description": "Acme Corp builds collaboration software for enterprise teams. Founded in 2016, it serves over 10,000 customers worldwide.",
        "industry": "Software Development",
        "phone": "+1 (415) 555-0123",
        "specialities": ["SaaS", "Enterprise Software", "Collaboration", "API Integration"],
        "headquarter": {
          "street1": "1 Market Street",
          "street2": "Suite 400",
          "postalCode": "94105",
          "city": "San Francisco",
          "geographicArea": "California",
          "country": "US"
        },
        "logoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
        "foundedOn": {
          "year": 2016
        },
        "locations": [
          {
            "street1": "1 Market Street",
            "street2": "Suite 400",
            "postalCode": "94105",
            "city": "San Francisco",
            "state": "California",
            "country": "US"
          },
          {
            "street1": "500 Congress Avenue",
            "street2": null,
            "postalCode": "78701",
            "city": "Austin",
            "state": "Texas",
            "country": "US"
          }
        ],
        "backgroundUrl": "https://media.licdn.com/dms/image/v2/D5616AQ.../background.jpg"
      }
    ],
    "metadata": {
      "perPage": 25,
      "count": 1,
      "nextCursor": null
    }
  },
  "error": null,
  "metadata": {
    "requestId": "req_o1r2g3s4e5a6",
    "executionTimeMs": 320
  },
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4522,
        "left": 5478
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-10-16T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-10-16T14:16:00.000Z"
      }
    }
  }
}