How do I count people matching search filters without spending credits?

Send the People search filters to POST /v2/search/people/count, without cursor or perPage. People search count returns data.count and costs 0 credits, but the call counts toward request rate limits.

How do I find people similar to a Social profile?

Send exactly one seed url or person id to People lookalike. The seed must already be indexed and is excluded from the results. Each delivered lookalike costs 1 credit. People lookalike does not accept additional search filters.

Use cases // Build lists

Build a list of people

Q: Does an empty people search page mean there are no more results?

No. A search page can be empty while data.metadata.nextCursor is still set. Continue with that cursor until the cursor is null or your budget is spent.

Q: Can I search for people using a sentence instead of filters?

Yes. Agentic Search accepts a prompt and returns the applied filters and warnings in data.interpretation. Each page costs 1 credit plus 1 credit per profile delivered. You cannot add explicit search filters alongside the prompt.

New

Last verified November 4, 2026

Build a prospect list with the people search API. Count matches for free, filter by title and location, use prompts or lookalikes, and cap credits.

You have

Title · location · companysearch filters

A search promptor a reference profile for Lookalike

The API

People search count
POST /v2/search/people/count
sync response
People search
POST /v2/search/people
sync response
Agentic Search
POST /v2/search/people/prompt
sync response
People lookalike
POST /v2/search/people/lookalike
sync response

You get

Jane Doe · Acme CorpMatching person profiles

credit per profile delivered by Search: 1
credit per profile delivered by Lookalike: 1
credit per Agentic Search page: 1
additional credit per Agentic profile delivered: 1
credits to count matches: 0

Find people by job title, company and location, describe your audience in a prompt, or find people similar to a known profile. You can count a filtered search for free before retrieving profiles. Search returns full profiles synchronously from the index, within a budget you set.

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 people.

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-people.md
- People search: https://docs.reversecontact.com/endpoints/search-people.md
- People search count: https://docs.reversecontact.com/endpoints/search-people-count.md
- Agentic Search: https://docs.reversecontact.com/endpoints/search-people-prompt.md
- People lookalike: https://docs.reversecontact.com/endpoints/search-people-lookalike.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:
  - People search: 1 credit per profile delivered. A page with no profile is free.
  - People search count: Free.
  - Agentic Search: 1 credit per page for the search, plus 1 credit per profile delivered.
  - People lookalike: 1 credit per profile delivered. A page with no profile is free.
- 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	People search count	Free	Synchronous
Explicit filters	People search	1 credit per profile delivered. An empty page is free	Synchronous
A description of the people to find	Agentic Search	1 credit per page plus 1 per profile delivered	Synchronous
One seed profile URL or person id	People lookalike	1 credit per profile delivered. An empty page is free	Synchronous

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 and lookalike searches are alternatives to filtered search, each with its own charges.

Count your target audience for free

Count people whose current title matches CTO and whose location is France. The response contains data.count without any profiles. Leave cursor and perPage out of the count request, then use the same filters for the paid search.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/search/people/count \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currentPositionTitle": "CTO", "location": {"country": "France"}}'

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

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

const count = await client.search.countPeople({
  currentPositionTitle: "CTO",
  location: { country: "France" }
});
console.log("Matching people:", count.data.count);

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    count = client.search.count_people(
        current_position_title="CTO", location={"country": "France"}
    )
    print("Matching people:", count.data.count if count.data else None)

Read profiles within a credit budget

Retrieve at most 100 profiles for at most 100 credits. Request 25 at a time and reduce the final request to the remaining budget. The raw API returns profiles in data.data and the next cursor in data.metadata.nextCursor. SDK iterators handle pagination, and the CLI counts for free before searching.

Remembered on every page

Code Examples

remaining=100
cursor=""
filters='{"currentPositionTitle": "CTO", "location": {"country": "France"}}'
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/people \
    -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 person of client.search.iterPeople(
  { currentPositionTitle: "CTO", location: { country: "France" }, perPage: 25 },
  { maxResults: 100 }
)) {
  console.log(person.firstName, person.lastName);
}

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    for person in client.search.iter_people(
        current_position_title="CTO",
        location={"country": "France"},
        per_page=25,
        max_results=100,
    ):
        if person is not None:
            print(person.first_name, person.last_name)

remaining=100
cursor=""
while [ "$remaining" -gt 0 ]; do
  size=$((remaining < 25 ? remaining : 25))
  if [ -n "$cursor" ]; then
    result=$(rc search people --title CTO --country France --limit "$size" --cursor "$cursor" --json) || break
  else
    result=$(rc search people --title CTO --country France --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

Describe the audience in a prompt

You can use Agentic Search when your input is a sentence. Inspect data.interpretation.filters and warnings before buying more pages. This example requests one page of up to 25 profiles, which costs at most 26 credits. Do not add explicit search filters alongside prompt.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/search/people/prompt \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "CTOs at software companies in France", "perPage": 25}'

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

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

const page = await client.search.peopleByPrompt({
  prompt: "CTOs at software companies in France", 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.people_by_prompt(
        prompt="CTOs at software companies in France", 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)

Find people similar to a seed profile

You can use People lookalike with exactly one indexed seed url or person id and no extra search filters. Results exclude the seed. This example retrieves at most 50 lookalikes for at most 50 credits.

Remembered on every page

Code Examples

remaining=50
cursor=""
filters='{"url": "https://www.social.com/in/janedoe"}'
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/people/lookalike \
    -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 person of client.search.iterPeopleLookalike(
  { url: "https://www.social.com/in/janedoe", perPage: 25 },
  { maxResults: 50 }
)) {
  console.log(person.firstName, person.lastName);
}

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    for person in client.search.iter_people_lookalike(
        url="https://www.social.com/in/janedoe", per_page=25, max_results=50
    ):
        if person is not None:
            print(person.first_name, person.last_name)

What it costs

People search and People lookalike cost 1 credit per profile delivered. An empty page costs nothing, and counting a filtered search is free. Every result is a full profile, so no second fetch is needed to get the profile fields.

Agentic Search costs 1 credit per page for the search, plus 1 credit per profile delivered. The page fee still applies when no profile matches. SDK iterators use maxResults / max_results to cap returned profiles, but this limit does not cover the extra page fees. Budget prompt pages separately or set an API key credit limit.

Good to know

Filters combine with AND. Supported arrays such as currentPositionTitle match any listed value. Title matching is token-based, so CTO can also match Deputy CTO.

Use currentCompanyIndustry values from Industry values, and full location.area ids such as MC:DACH from Area values. The currentFunction filter accepts values such as Marketing, and currentSeniority accepts Director and VP. Check the People search filter reference for all accepted values and exclusions.

For headcount, currentCompanyEmployeeCountRange matches whole size brackets: { "min": 51, "max": 200 } matches the 51 to 200 bracket. Unknown fields and invalid closed-list values return 422 and cost 0 credits. Search count calls still count toward your rate limits.

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

For filtered People search, read successive pages within 10 minutes for a consistent cached result set. The pagination reference describes what happens after that.

For prompt searches, reuse the same prompt on the next page. You can send data.interpretation.filters to People search count for a free total after the first paid prompt page.

A lookalike seed must already be indexed. An unindexed URL returns a free 404. Search uses cached data, so use profile freshness checks when you need a refresh.

The examples print profiles for your application to store. To save people in a persistent Reverse Contact List and buy contact data, use Lists: orchestrate enrichment. For individual profiles, see Get a work email or a phone number.

FAQ

How do I cap the credits spent on a people search?

For filtered People search, request no more profiles than your remaining credit budget, or use an SDK iterator with maxResults / max_results. Each delivered profile costs 1 credit. Agentic Search adds 1 credit per page, so budget those pages separately or set an API key credit limit.

Does an empty people search page mean there are no more results?

No. A search page can be empty while data.metadata.nextCursor is still set. Continue with that cursor until the cursor is null or your budget is spent.

Can I search for people using a sentence instead of filters?

Yes. Agentic Search accepts a prompt and returns the applied filters and warnings in data.interpretation. Each page costs 1 credit plus 1 credit per profile delivered. You cannot add explicit search filters alongside the prompt.