Use cases // Build lists

Build a list of companies

Q: How do I build a company list by industry and employee count?

Send industry and employeeCountRange to Company search count to count matches for free. Use the same filters with POST /v2/search/organizations to retrieve full company profiles at 1 credit per company delivered.

Q: Why does company search return no results for my employee range?

The employeeCountRange filter must contain whole size brackets. A range such as 51 to 200 matches that bracket. A range that contains no complete bracket returns no companies.

Q: How do I cap company search credits?

For filtered Company search, use an SDK iterator with maxResults / max_results or request no more companies than the remaining budget. Agentic Company Search adds 1 credit per page, so budget those fees separately or use an API key credit limit.

Q: Can I search for companies with a plain-language prompt?

Yes. Agentic Company Search accepts a prompt and returns the interpreted filters and warnings. Each page costs 1 credit plus 1 per company delivered. You cannot add explicit filter fields alongside the prompt.

Q: How do I get the next page of company search results?

Send data.metadata.nextCursor as cursor. Keep the same filters for Company search, or the same prompt for Agentic Company Search. Continue until the cursor is null or your budget is spent. An empty page alone does not mean the search has ended.

New

Last verified November 4, 2026

Build a company list with the search API. Count matches for free, filter by industry, headcount and location, use prompts, and cap credit spending.

You have

Industry · size · locationcompany search filters

A search promptfor Agentic Company Search

The API

Company search count
POST /v2/search/organizations/count
sync response
Company search
POST /v2/search/organizations
sync response
Agentic Company Search
POST /v2/search/organizations/prompt
sync response

You get

Acme CorpMatching company profiles

credit per company delivered by Search: 1
credit per Agentic Company Search page: 1
additional credit per Agentic company delivered: 1
credits to count matches: 0

Find companies by industry, headcount and headquarters location, or describe the companies you want in a sentence. You can count a filtered search for free before retrieving profiles. Search returns full company profiles synchronously from the index, within your credit budget.

Build it with an AI coding agent

Paste this prompt into Claude Code, Codex or Cursor.

Implement this in my project with the Reverse Contact API: build a list of companies.

Read these pages first and follow them over what you remember about the API:
- The guide for this use case: https://docs.reversecontact.com/use-cases/build-a-list-of-companies.md
- Company search: https://docs.reversecontact.com/endpoints/search-companies.md
- Company search count: https://docs.reversecontact.com/endpoints/search-companies-count.md
- Agentic Company Search: https://docs.reversecontact.com/endpoints/search-companies-prompt.md
- Errors and retries: https://docs.reversecontact.com/guides/errors-retries.md
The index of the whole documentation is https://docs.reversecontact.com/llms.txt.

Requirements:
- Use the official SDK if this project is in TypeScript, JavaScript or Python (https://docs.reversecontact.com/sdk/javascript.md, https://docs.reversecontact.com/sdk/python.md). Otherwise call the REST API.
- Read the API key from the RC_API_KEY environment variable. Keep it server-side. Never hard-code or log it.
- Credits:
  - Company search: 1 credit per company delivered. A page with no company is free.
  - Company search count: Free.
  - Agentic Company Search: 1 credit per page for the search, plus 1 credit per company delivered.
- Write tests that mock the API with the example responses of the reference pages. Tests must not spend credits.

When you are done, list the endpoints the code calls, what each call costs, and how to run it.

Which endpoint

Input you have	Endpoint	Cost	Mode
Filters to count matches before buying profiles	Company search count	Free	Synchronous
Explicit company filters	Company search	1 credit per company delivered. An empty page is free	Synchronous
A description of the companies to find	Agentic Company Search	1 credit per page plus 1 per company delivered	Synchronous

The API routes use /v2/search/organizations. The reference pages linked above keep their existing company-search addresses.

How it works

Set RC_API_KEY to your API key. Install the TypeScript SDK, Python SDK or CLI for your chosen example. Shell examples use jq. Prompt search is an alternative to filtered search, with its own charges.

Count the companies that match

Count software companies headquartered in France, in the 51 to 200 employee bracket, founded in 2015 or later. Read data.count and reuse the same filters for the paid search. Leave cursor and perPage out of the count request.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/search/organizations/count \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"industry": "Software Development", "employeeCountRange": {"min": 51, "max": 200}, "foundedYear": {"min": 2015}, "location": {"countryCode": "FR"}}'

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const count = await client.search.countOrganizations({
  industry: "Software Development",
  employeeCountRange: { min: 51, max: 200 },
  foundedYear: { min: 2015 },
  location: { countryCode: "FR" }
});
console.log("Matching companies:", count.data.count);

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    count = client.search.count_organizations(
        industry="Software Development",
        employee_count_range={"min": 51, "max": 200},
        founded_year={"min": 2015},
        location={"countryCode": "FR"},
    )
    print("Matching companies:", count.data.count if count.data else None)

Retrieve the company profiles within budget

Retrieve at most 100 companies for at most 100 credits. Request pages of up to 25 companies, with a smaller final request when needed. The raw API returns companies in data.data and the cursor in data.metadata.nextCursor. The SDKs handle pagination, and the CLI counts for free before searching.

Remembered on every page

Code Examples

remaining=100
cursor=""
filters='{"industry": "Software Development", "employeeCountRange": {"min": 51, "max": 200}, "foundedYear": {"min": 2015}, "location": {"countryCode": "FR"}}'
while [ "$remaining" -gt 0 ]; do
  size=$((remaining < 25 ? remaining : 25))
  body=$(printf '%s' "$filters" | jq --arg cursor "$cursor" --argjson size "$size" \
    '. + {perPage: $size} + (if $cursor == "" then {} else {cursor: $cursor} end)')
  result=$(curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/search/organizations \
    -H "Authorization: Bearer $RC_API_KEY" \
    -H "Content-Type: application/json" -d "$body") || break
  printf '%s' "$result" | jq -c '.data.data[]'
  delivered=$(printf '%s' "$result" | jq -er '.data.data | length')
  remaining=$((remaining - delivered))
  next_cursor=$(printf '%s' "$result" | jq -r '.data.metadata.nextCursor // empty')
  [ -z "$next_cursor" ] && break
  [ "$next_cursor" = "$cursor" ] && { echo "Repeated cursor" >&2; break; }
  cursor=$next_cursor
done

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

for await (const company of client.search.iterOrganizations(
  {
    industry: "Software Development",
    employeeCountRange: { min: 51, max: 200 },
    foundedYear: { min: 2015 },
    location: { countryCode: "FR" },
    perPage: 25
  },
  { maxResults: 100 }
)) {
  console.log(company.companyName, company.websiteUrl);
}

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    for company in client.search.iter_organizations(
        industry="Software Development",
        employee_count_range={"min": 51, "max": 200},
        founded_year={"min": 2015},
        location={"countryCode": "FR"},
        per_page=25,
        max_results=100,
    ):
        if company is not None:
            print(company.company_name, company.website_url)

remaining=100
cursor=""
while [ "$remaining" -gt 0 ]; do
  size=$((remaining < 25 ? remaining : 25))
  if [ -n "$cursor" ]; then
    result=$(rc search organizations --industry "Software Development" --size 51-200 --founded-year 2015- --country-code FR --limit "$size" --cursor "$cursor" --json) || break
  else
    result=$(rc search organizations --industry "Software Development" --size 51-200 --founded-year 2015- --country-code FR --limit "$size" --json) || break
  fi
  printf '%s' "$result" | jq -c '.data.data[]'
  delivered=$(printf '%s' "$result" | jq -er '.data.data | length')
  remaining=$((remaining - delivered))
  next_cursor=$(printf '%s' "$result" | jq -r '.data.metadata.nextCursor // empty')
  [ -z "$next_cursor" ] && break
  [ "$next_cursor" = "$cursor" ] && { echo "Repeated cursor" >&2; break; }
  cursor=$next_cursor
done

Search from a description

You can use Agentic Company Search with a prompt. Inspect data.interpretation.filters and warnings before continuing. This example requests one page of up to 25 companies for at most 26 credits. Describe every criterion in the prompt instead of adding explicit filter fields.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/search/organizations/prompt \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Software companies headquartered in France with 51 to 200 employees, founded since 2015", "perPage": 25}'

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const page = await client.search.organizationsByPrompt({
  prompt: "Software companies headquartered in France with 51 to 200 employees, founded since 2015",
  perPage: 25
});
console.log("Filters:", page.interpretation?.filters);
console.log("Warnings:", page.interpretation?.warnings);
console.log(page.data, "credits:", page.quotas?.creditsConsumed);

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    page = client.search.organizations_by_prompt(
        prompt="Software companies headquartered in France with 51 to 200 employees, founded since 2015",
        per_page=25,
    )
    if page.interpretation is not None:
        print("Filters:", page.interpretation.filters)
        print("Warnings:", page.interpretation.warnings)
    print(page.data, "next cursor:", page.next_cursor)

What it costs

Company search costs 1 credit per company delivered. An empty page costs nothing, and Company search count is free. The full company profile is included, so you do not need a second fetch to retrieve its fields.

Agentic Company Search costs 1 credit per page for the search, plus 1 credit per company delivered. The 1-credit page fee also applies to empty pages. Before a request runs, your available balance must cover perPage credits for filtered search, or perPage + 1 for a prompt search. Otherwise, the API returns 402 INSUFFICIENT_CREDITS without charging.

SDK iterators use maxResults / max_results to cap profiles, but this limit does not cover the extra page fees of Agentic Company Search. Limit prompt requests page by page, or configure an API key credit limit to cap total spending.

Good to know

Company search and Company search count require at least one filter. The maxDataAgeDate filter cannot be used alone. Filters combine with AND.

Use industry values such as Software Development from Industry values, and full location.area ids such as MC:DACH from Area values. Put country codes in location.countryCode (FR) and country names in location.country (France).

The employeeCountRange filter matches whole size brackets. For example, { "min": 51, "max": 200 } matches the 51 to 200 bracket. A range that contains no complete bracket returns no companies. Unknown fields and invalid closed-list values return 422 and cost 0 credits. The Company search request reference lists the filters and their accepted values.

Request 1 to 100 companies per page, 25 by default. Keep filters unchanged and pass data.metadata.nextCursor back as cursor. Stop only when the cursor is null or your budget is spent. A short or empty page can still have a next cursor, and there is no page parameter.

For prompt search, resend the same prompt. After the first paid prompt page, send data.interpretation.filters to Company search count to get a free total.

Search uses cached profiles. See Keep profiles fresh when you need current company data, and check the rate limits when paging at scale. Search count calls still count toward those request limits.

The examples print profiles for your application to store. To save companies in a persistent Reverse Contact List, use Lists: orchestrate enrichment.

FAQ

How do I build a company list by industry and employee count?

Send industry and employeeCountRange to Company search count to count matches for free. Use the same filters with POST /v2/search/organizations to retrieve full company profiles at 1 credit per company delivered.

Why does company search return no results for my employee range?

The employeeCountRange filter must contain whole size brackets. A range such as 51 to 200 matches that bracket. A range that contains no complete bracket returns no companies.

How do I cap company search credits?

For filtered Company search, use an SDK iterator with maxResults / max_results or request no more companies than the remaining budget. Agentic Company Search adds 1 credit per page, so budget those fees separately or use an API key credit limit.

Can I search for companies with a plain-language prompt?

Yes. Agentic Company Search accepts a prompt and returns the interpreted filters and warnings. Each page costs 1 credit plus 1 per company delivered. You cannot add explicit filter fields alongside the prompt.

How do I get the next page of company search results?

Send data.metadata.nextCursor as cursor. Keep the same filters for Company search, or the same prompt for Agentic Company Search. Continue until the cursor is null or your budget is spent. An empty page alone does not mean the search has ended.