Skip to content

Migrating company search to the new endpoint

Move company search calls to /v2/search/organizations before /v2/search/companies goes into maintenance on November 9, 2026.

POST /v2/search/companies goes into maintenance on Monday, November 9, 2026, for a few weeks. Move your company searches to POST /v2/search/organizations before that date: it is available now, returns full company profiles instead of search hits, paginates with cursors instead of page numbers, accepts three new filters, and has a free count endpoint.

Until November 8, 2026, /v2/search/companies keeps working as it does today. From November 9, 2026 and during the maintenance, calls to /v2/search/companies and /v2/search/companies/available-fields return 410 with the error code ENDPOINT_GONE, error.details.alternative naming the endpoint to call instead and error.details.docs linking this guide. These calls are not processed and consume no credits.

After the maintenance, /v2/search/companies comes back with a format compatible with /v2/search/organizations, so an integration you move to /v2/search/organizations now will not need a second migration.

Timeline

Date/v2/search/companies/v2/search/organizations
Until November 8, 2026Works as todayAvailable
From November 9, 2026, for a few weeksMaintenance: 410 with ENDPOINT_GONE, 0 creditsAvailable
After the maintenanceBack, in a format compatible with /v2/search/organizationsAvailable

What changes

AreaPOST /v2/search/companiesPOST /v2/search/organizations
Path/v2/search/companies/v2/search/organizations
ResultsSearch hits (name, size, industry, city and country)Full company profiles, the same shape as the Company profile endpoint
Paginationpage and perPage (default 100)cursor and perPage (default 25)
MetadatacurrentPage, pageNumber, perPage, totalperPage, count, nextCursor
Total matchesdata.metadata.total on every responseFree count endpoint
Pricing1 credit per page1 credit per company delivered
FilterscompanyName, companyDomain, industry, employeeCountRange, location, maxDataAgeDateThe same, plus specialities, foundedYear and followersCount
Available fieldsGET /v2/search/companies/available-fieldsGET /v2/search/organizations/available-fields

Paths

BeforeAfter
POST /v2/search/companiesPOST /v2/search/organizations
GET /v2/search/companies/available-fieldsGET /v2/search/organizations/available-fields
(no equivalent)POST /v2/search/organizations/count

The method and the Authorization: Bearer YOUR_API_KEY header stay the same. Only the path changes.

Results are full profiles

The previous endpoint returned a light search hit, and the documented flow was to chain into the Company profile endpoint for the full data of a hit. /v2/search/organizations returns complete profiles directly, so the second call is no longer needed.

Before, a hit looked like this:

JSON
{
  "id": "com_01jbd5vewyenebxgaz869ffe5t",
  "name": "Acme Corp",
  "publicId": "acme",
  "linkedinId": "12345678",
  "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",
  "industry": "Software Development",
  "companyUpdateDate": "2026-03-18T09:12:44.000Z",
  "location": { "city": "San Francisco", "country": "US" }
}

After, each item of data.data is a full company profile. Most fields keep their name (id, publicId, linkedinId, linkedinUrl, employeesCount, followersCount, employeeCountRange, websiteUrl, tagline, industry), three change, and the profile adds description, phone, specialities, logoUrl, backgroundUrl, foundedOn and locations:

Search hitFull profile
namecompanyName
location.city, location.countryheadquarter.city, headquarter.country (still an ISO code), next to the street, postal code and region of the headquarters
companyUpdateDateNot part of the full profile. Filter on freshness with maxDataAgeDate, or read lastUpdate from the free Company profile status endpoint

If you chained Company profile calls after a search, drop them: the data is already in the search response.

Pagination moves from pages to cursors

The previous endpoint used page (1 to 50) and perPage (1 to 100, default 100), and reported currentPage, pageNumber and total in data.metadata. Company search uses cursor pagination:

  • perPage stays, with a new default of 25 (still 1 to 100).
  • page is gone, and sending it returns 422 with UNKNOWN_FIELD. Send the nextCursor value from the previous response as cursor to get the next page, with the same filters.
  • nextCursor is null on the last page.
  • The cursor is opaque: send it back unchanged, without parsing or altering it.
  • The 50-page limit is gone: a cursor reaches every matching company.

Before:

JavaScript
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", page: 2, perPage: 100 })
});

const payload = await response.json();
const hits = payload.data.data;
console.log(`Page ${payload.data.metadata.currentPage} of ${payload.data.metadata.pageNumber}, ${payload.data.metadata.total} total`);

After:

JavaScript
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", perPage: 25, cursor })
  });

  return response.json();
};

const page = await searchPage();
console.log(`${page.data.metadata.count} companies in this page`);
if (page.data.metadata.nextCursor) {
  const nextPage = await searchPage(page.data.metadata.nextCursor);
}

Totals move to the count endpoint

The previous data.metadata.total field is gone: data.metadata.count is the number of companies in the current page, not the size of the whole matching set. To size a query, call the free Company search count endpoint with the same filters:

Shell
curl -X POST https://api.reversecontact.com/v2/search/organizations/count \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "industry": "Software Development" }'

The response is data.count, the total number of matching companies across all pages, and it costs 0 credits.

Pricing changes

The previous endpoint charged 1 credit per page, whatever the page contained, including a page with no result. Company search charges 1 credit per company delivered: a page that returns 25 companies costs 25 credits, and a page that returns no company costs 0 credits. Rejected filters still cost 0 credits.

The same volume of results can therefore cost more than before when your pages are full, and less when many of your searches come back empty. To keep your spending under control:

  • Call the free count endpoint first, with the same filters, to know how many companies a search will return before you spend anything.
  • Start with a small perPage, such as 10, and raise it once you know your volumes. perPage caps what a single request can spend.
  • Keep sending searches that may find nothing: a search with no result costs 0 credits, where the previous endpoint billed 1 credit for an empty page.

A request needs as many credits available as its perPage before it runs, otherwise it returns 402 with INSUFFICIENT_CREDITS. Only the companies delivered are then charged.

Filter changes

Existing filters keep their names and their values: companyName, companyDomain, industry (from the same industry list), employeeCountRange (the same headcount brackets), location (country, countryCode, region and city, matched on the headquarters) and maxDataAgeDate. Company search also accepts filters the previous endpoint did not have:

FilterWhat it does
specialitiesMatch the specialities listed on the company profile, one value or a list (OR-matched)
foundedYearKeep companies founded within a year range, from 0 to 2100
followersCountKeep companies within a follower count range

Two rules are stricter. A request needs at least one filter, and maxDataAgeDate cannot be that only filter: both return 422 with NO_FILTER_PROVIDED. The rest of the validation works as before: unknown fields, blank values and values outside a closed list return 422 with suggestions and cost 0 credits. Every filter is documented on the Company search page.

Available fields moves too

If you discover filters dynamically, switch GET /v2/search/companies/available-fields to GET /v2/search/organizations/available-fields. The response keeps its shape, with two differences: data.entity is "organization", and data.fields lists cursor instead of page, next to every accepted filter and the allowedValues of closed vocabularies such as industries.

Migration checklist

  1. Replace the search path with POST /v2/search/organizations and the available-fields path with GET /v2/search/organizations/available-fields.
  2. Replace page with cursor handling: loop while data.metadata.nextCursor is not null.
  3. Review your perPage: the default is now 25, each delivered company costs 1 credit, and the balance must cover perPage before the call.
  4. Replace data.metadata.total reads with a call to POST /v2/search/organizations/count.
  5. Map the renamed fields: name becomes companyName, location becomes headquarter, and companyUpdateDate is gone.
  6. Drop the Company profile calls you used to chain after a search: results are already full profiles.
  7. Make sure every request carries at least one filter other than maxDataAgeDate.

FAQ

Does /v2/search/companies still work?

Yes, until November 8, 2026. POST /v2/search/companies goes into maintenance on Monday, November 9, 2026, for a few weeks: during the maintenance, its calls return 410 with the error code ENDPOINT_GONE, consume no credits and name POST /v2/search/organizations in error.details.alternative. It then comes back with a format compatible with POST /v2/search/organizations, so move to POST /v2/search/organizations now: that integration will not need a second migration.

How do I get the total number of matching companies with /v2/search/organizations?

POST /v2/search/organizations does not return a total: data.metadata.count is only the number of companies in the current page. Call POST /v2/search/organizations/count with the same filters to get data.count, the total number of matching companies across all pages, for 0 credits. See Company search count.

How many credits does a company search cost?

POST /v2/search/organizations charges 1 credit per company delivered: a page that returns 25 companies costs 25 credits, and a page that returns no company costs 0 credits. Rejected filters also cost 0 credits, and lowering perPage caps what a single request can spend.

Which result fields change name in /v2/search/organizations?

In POST /v2/search/organizations results, name becomes companyName and location becomes headquarter, whose country is still an ISO code. companyUpdateDate is not part of the full profile: filter with maxDataAgeDate, or read lastUpdate from the free Company profile status endpoint.

Last verified