# Reverse Contact API

> B2B data enrichment API. Enrich social profiles and company pages with structured professional data. REST API with JSON responses, Bearer token authentication, and credit-based billing.

- Base URL: `https://api.reversecontact.com` (every path starts with `/v2`)
- Authentication: `Authorization: Bearer rc_your_api_key`
- Async jobs: an async endpoint answers with `data.webhookId`. Poll `GET /v2/webhooks/{webhookId}?wait=20` until `status` is `succeeded` or `errored`, with an HTTP timeout above 20 seconds: each poll answers as soon as the job ends, or after at most 20 seconds with the job still running. While it runs, start two polls at least `Retry-After` seconds apart (2 if the header is missing): a held poll already lasts longer, so the next one starts right away; after an early answer, pause for the rest. Without `wait`, that is a pause of `Retry-After` seconds between polls. A `5xx` is retried like any other call (its `Retry-After` if present, otherwise exponential backoff). Polls are free and not rate limited. Guide: [Polling](https://docs.reversecontact.com/guides/polling.md)
- MCP server for the API: `https://api.reversecontact.com/mcp` (Streamable HTTP, OAuth sign-in or Bearer token auth)
- Complete documentation: [llms-full.txt](https://docs.reversecontact.com/llms-full.txt)

## For agents
- [Agent brief](https://docs.reversecontact.com/agents.md): Start here: the brief to paste into an agent, and every entry point. Everything an AI agent needs to call the Reverse Contact API: the entry points, and a brief to paste into its instructions.
- [OpenAPI spec (JSON)](https://docs.reversecontact.com/openapi.json): OpenAPI 3.1.0. Every operation with its parameters and responses, its docs page (`externalDocs`), its credit cost (`x-credits`), its mode (`x-mode`) and its status (`x-availability`).
- [OpenAPI spec (YAML)](https://docs.reversecontact.com/openapi.yaml): The same spec in YAML.
- [API pricing](https://docs.reversecontact.com/pricing.md): What every endpoint costs in credits, when it finds a result and when it does not, with the source of its data.
- [Data coverage and quality](https://docs.reversecontact.com/data-coverage.md): What the database holds, where, how fresh and how complete it is: profiles and companies worldwide, by region and for the largest countries, freshness, email and phone find rates, and what sets quality profiles apart, from the monthly snapshot.
- [Endpoint catalog](https://docs.reversecontact.com/catalog.json): Every endpoint with its method, path, credit cost, mode, status and docs page, the retired endpoints and those under maintenance with their replacement, and every page with its last verified date.
- [API MCP server](https://api.reversecontact.com/mcp): Call the API from an agent. Streamable HTTP, OAuth sign-in or Bearer token auth. Setup: [Connect AI agents](https://docs.reversecontact.com/guides/mcp.md).
- [Documentation MCP server](https://docs.reversecontact.com/mcp): Search and read this documentation from an agent. Streamable HTTP, no authentication.

## Get started
- [Getting started](https://docs.reversecontact.com/getting-started.md): Set up your first Reverse Contact request in less than 5 minutes: get an API key, call the API with a Social URL, read the response, then try live data.
- [Authentication](https://docs.reversecontact.com/authentication.md): Authenticate requests to the Reverse Contact API with a Bearer API key in the Authorization header, and fix 401 errors from a missing or expired key.
- [Your first API call](https://docs.reversecontact.com/guides/first-api-call.md): Send your first enrichment request to the Reverse Contact API, parse the JSON response, and fix the errors a first call most often returns.
- [API reference](https://docs.reversecontact.com/api-reference.md): Common response structure, shared types, and error codes for all endpoints of the Reverse Contact API: success, data, error, quotas and metadata.

## Find a person from an email, a name or a profile URL
- [Enrich profile](https://docs.reversecontact.com/endpoints/enrich-person.md): Get a person's full professional profile from any details you have, such as an email, a name or a company. 2 credits, charged only when a person is found.
- [Person profile](https://docs.reversecontact.com/endpoints/fetch-profile.md): Retrieve a person's professional profile from a Social URL, with work experience, education, skills and certifications.
- [Person profile status](https://docs.reversecontact.com/endpoints/check-person.md): Check if a person profile exists in the database, and when it was last updated, before requesting enrichment. The check costs 0 credits.
- [Which endpoint should I use?](https://docs.reversecontact.com/guides/which-endpoint-should-i-use.md): Pick the right Reverse Contact endpoint for profile lookup, enrichment, search, and live scraping.

## Enrich a CSV file of contacts
- [Enrich a CSV file](https://docs.reversecontact.com/guides/enrich-a-csv-file.md): Upload a CSV of contacts in the app and download it enriched, or loop over its rows with the API.
- [Enrich profile](https://docs.reversecontact.com/endpoints/enrich-person.md): Get a person's full professional profile from any details you have, such as an email, a name or a company. 2 credits, charged only when a person is found.
- [Person profile](https://docs.reversecontact.com/endpoints/fetch-profile.md): Retrieve a person's professional profile from a Social URL, with work experience, education, skills and certifications.
- [Rate limits](https://docs.reversecontact.com/guides/rate-limits.md): The requests per minute of each plan, the daily profile cap of the Go, Plus and Max plans, and how to handle a 429.

## Find a company from a domain or a company page URL
- [Enrich company](https://docs.reversecontact.com/endpoints/enrich-company.md): Get a company's full profile from its domain with POST /v2/enrich/companies. It costs 2 credits, charged only when a company is found.
- [Company profile](https://docs.reversecontact.com/endpoints/fetch-company.md): Retrieve a company profile from a Social company URL, with industry, employee count, headquarters, office locations and specialties.
- [Company profile status](https://docs.reversecontact.com/endpoints/check-company.md): Check if a company profile exists in the database, and when it was last updated, before requesting enrichment. The check costs 0 credits.

## Get a work email or a phone number
- [Find Email](https://docs.reversecontact.com/endpoints/contact-email.md): Find a professional or personal email address from a Social URL, a Reverse Contact person id, or full name and company domain, then receive the result by webhook.
- [Verify Email](https://docs.reversecontact.com/endpoints/contact-email-verify.md): Check whether an email address can receive mail and get a verdict (valid, risky, invalid or unknown) by polling or webhook.
- [Find Phone](https://docs.reversecontact.com/endpoints/contact-phone.md): Find a professional phone number from a Social URL, a Reverse Contact person id, or full name and company domain, then receive the result by webhook.
- [Polling for async results](https://docs.reversecontact.com/guides/polling.md): The recommended way to retrieve async enrichment results: trigger a job, then poll for the result. Polling is free and needs no public HTTPS endpoint.

## Build a list of people
- [People search](https://docs.reversecontact.com/endpoints/search-people.md): Search the database for people with filters and get full profiles back with cursor pagination.
- [People search count](https://docs.reversecontact.com/endpoints/search-people-count.md): Count matching people with the same filters as People search, for free, to size a query before paying 1 credit per profile delivered.
- [People auto-suggestion](https://docs.reversecontact.com/endpoints/search-people-auto-suggestion.md): Complete a skill as someone types, for free, to build a people search box in your own product.
- [Agentic Search](https://docs.reversecontact.com/endpoints/search-people-prompt.md): Describe the people you want in plain language and get full profiles back, with the filters we read from your prompt.
- [People lookalike](https://docs.reversecontact.com/endpoints/search-people-lookalike.md): Find the people who look like one seed profile, given by Social URL or Reverse Contact person id.
- [People search available fields](https://docs.reversecontact.com/endpoints/search-people-available-fields.md): Discover the filters accepted by the People Search endpoint at runtime, with every allowed value of closed lists such as the position taxonomy.
- [Industry values](https://docs.reversecontact.com/reference/industries.md): Complete list of the 490 accepted industry values for the industry filters of Company search and People search, and how each value is matched.
- [Area values](https://docs.reversecontact.com/reference/areas.md): The 62 zone ids accepted by the location.area filter of People search and Company search, the countries each zone covers, and how zones combine with countries, regions and cities.

## Build a list of companies
- [Company search](https://docs.reversecontact.com/endpoints/search-companies.md): Search the database for companies with filters and get full company profiles back with cursor pagination.
- [Company search count](https://docs.reversecontact.com/endpoints/search-companies-count.md): Count matching companies with the same filters as Company search, for free, to size a query before paying 1 credit per company delivered.
- [Agentic Company Search](https://docs.reversecontact.com/endpoints/search-companies-prompt.md): Describe the companies you want in plain language and get full company profiles back, with the filters we read from your prompt.
- [Company search available fields](https://docs.reversecontact.com/endpoints/search-companies-available-fields.md): Discover the filters accepted by the Company Search endpoint at runtime, with every allowed value of closed lists such as industries and country codes.
- [Industry values](https://docs.reversecontact.com/reference/industries.md): Complete list of the 490 accepted industry values for the industry filters of Company search and People search, and how each value is matched.
- [Area values](https://docs.reversecontact.com/reference/areas.md): The 62 zone ids accepted by the location.area filter of People search and Company search, the countries each zone covers, and how zones combine with countries, regions and cities.

## Keep profiles fresh
- [Data freshness](https://docs.reversecontact.com/guides/data-freshness.md): Choose the right endpoint mode, Check, Fetch or Live, for each profile lookup, based on the data freshness you need and the credits you want to spend.
- [Person profile status](https://docs.reversecontact.com/endpoints/check-person.md): Check if a person profile exists in the database, and when it was last updated, before requesting enrichment. The check costs 0 credits.
- [Person profile live](https://docs.reversecontact.com/endpoints/fetch-profile-live.md): Trigger a live fetch of a Social profile and retrieve results via polling or webhook callback.
- [Company profile live](https://docs.reversecontact.com/endpoints/fetch-company-live.md): Trigger a live fetch of a Social company profile and retrieve results via polling or webhook callback.
- [Current position and work history ordering](https://docs.reversecontact.com/guides/current-position-resolution.md): Understand the fixed rules we use to pick a person's current job and to order their work experience and education.

## Receive the result of an async job
- [Polling for async results](https://docs.reversecontact.com/guides/polling.md): The recommended way to retrieve async enrichment results: trigger a job, then poll for the result. Polling is free and needs no public HTTPS endpoint.
- [Webhooks](https://docs.reversecontact.com/guides/webhooks.md): Webhooks POST async enrichment results to your HTTPS URL. Use them when you already run a public HTTPS receiver and prefer push delivery to polling.

## Control credits and rate limits
- [Credits](https://docs.reversecontact.com/guides/credits.md): How the API charges credits, what is always free, how async jobs are refunded, and how to spend less.
- [Rate limits](https://docs.reversecontact.com/guides/rate-limits.md): The requests per minute of each plan, the daily profile cap of the Go, Plus and Max plans, and how to handle a 429.
- [Usage](https://docs.reversecontact.com/endpoints/usage.md): Check your workspace credit balance and rate limit status with GET /v2/usage. The call is free and does not count toward your rate limit.
- [People search count](https://docs.reversecontact.com/endpoints/search-people-count.md): Count matching people with the same filters as People search, for free, to size a query before paying 1 credit per profile delivered.
- [Company search count](https://docs.reversecontact.com/endpoints/search-companies-count.md): Count matching companies with the same filters as Company search, for free, to size a query before paying 1 credit per company delivered.
- [API key management](https://docs.reversecontact.com/guides/api-key-management.md): Create, configure, and secure API keys with permissions, request limits, credit limits, and expiration.

## Handle errors and go to production
- [Error handling & retries](https://docs.reversecontact.com/guides/errors-retries.md): Handle API errors predictably: the error response format, what each HTTP status means, search filter validation, and safe retry strategies.
- [Production checklist](https://docs.reversecontact.com/guides/production-checklist.md): Hardening checklist for auth, retries, quotas, webhook handling, and support readiness, to go through before your integration goes to production.
- [API reference](https://docs.reversecontact.com/api-reference.md): Common response structure, shared types, and error codes for all endpoints of the Reverse Contact API: success, data, error, quotas and metadata.

## Understand the data
- [Data quality](https://docs.reversecontact.com/guides/data-quality.md): How we decide what to return, what each response tells you about its own reliability, and how to trade match rate against certainty.
- [Missing and empty profile fields](https://docs.reversecontact.com/guides/missing-and-empty-fields.md): Tell an unknown value from a real zero, an empty list or data that Reverse Contact does not collect.
- [Current position and work history ordering](https://docs.reversecontact.com/guides/current-position-resolution.md): Understand the fixed rules we use to pick a person's current job and to order their work experience and education.
- [Industry values](https://docs.reversecontact.com/reference/industries.md): Complete list of the 490 accepted industry values for the industry filters of Company search and People search, and how each value is matched.

## Connect an AI agent (MCP, agent brief)
- [Agent brief](https://docs.reversecontact.com/agents.md): Everything an AI agent needs to call the Reverse Contact API: the entry points, and a brief to paste into its instructions.
- [Connect AI agents (MCP)](https://docs.reversecontact.com/guides/mcp.md): Connect Claude, ChatGPT, Cursor, and other AI agents to Reverse Contact using the Model Context Protocol.
- [Agent skills](https://docs.reversecontact.com/guides/agent-skills.md): Install the Reverse Contact skill so coding agents such as Claude Code can enrich, fetch, check and search with the rc CLI, at the lowest credit cost.

## Work from the terminal (CLI and agent skills)
- [Command line interface (CLI)](https://docs.reversecontact.com/guides/cli.md): Install rc, the Reverse Contact command line tool, sign in, and check, fetch, enrich and search from your terminal or a script.
- [Agent skills](https://docs.reversecontact.com/guides/agent-skills.md): Install the Reverse Contact skill so coding agents such as Claude Code can enrich, fetch, check and search with the rc CLI, at the lowest credit cost.

## Call the API from your code (code examples)
- [TypeScript and JavaScript SDK](https://docs.reversecontact.com/sdk/javascript.md): Install @reverse-contact/sdk, the official TypeScript and JavaScript client for the Reverse Contact API, with typed results, safe retries, job waiting and budgeted search pagination.
- [Python SDK](https://docs.reversecontact.com/sdk/python.md): Install reversecontact, the official Python client for the Reverse Contact API, with sync and async clients, typed models, safe retries, job waiting and budgeted search pagination.

## Move off a retired endpoint or one under maintenance
- [Endpoint transition on October 13, 2026](https://docs.reversecontact.com/guides/endpoint-transition-october-2026.md): /v2/search/persons is succeeded by /v2/search/people, and /v2/resolve by /v2/enrich. Both old endpoints were retired on October 13, 2026.
- [Migrating people search from persons to people](https://docs.reversecontact.com/guides/migrating-search-persons-to-people.md): Move people search calls from /v2/search/persons, retired on October 13, 2026, to /v2/search/people: cursor pagination, per-profile pricing and new filters.
- [Migrating company search to the new endpoint](https://docs.reversecontact.com/guides/migrating-search-companies-to-organizations.md): Move company search calls to /v2/search/organizations before /v2/search/companies goes into maintenance on November 9, 2026.

## API reference by endpoint family
- [API reference](https://docs.reversecontact.com/api-reference.md): Common response structure, shared types, and error codes for all endpoints of the Reverse Contact API: success, data, error, quotas and metadata.
- [Industry values](https://docs.reversecontact.com/reference/industries.md): Complete list of the 490 accepted industry values for the industry filters of Company search and People search, and how each value is matched.
- [Area values](https://docs.reversecontact.com/reference/areas.md): The 62 zone ids accepted by the location.area filter of People search and Company search, the countries each zone covers, and how zones combine with countries, regions and cities.
### Enrichment
- [Enrich profile](https://docs.reversecontact.com/endpoints/enrich-person.md): `POST /v2/enrich/persons`. 2 credits when a person is found, full profile included. A 404 is free. Get a person's full professional profile from any details you have, such as an email, a name or a company. 2 credits, charged only when a person is found.
- [Enrich company](https://docs.reversecontact.com/endpoints/enrich-company.md): `POST /v2/enrich/companies`. 2 credits when a company is found, full profile included. A 404 is free. Get a company's full profile from its domain with POST /v2/enrich/companies. It costs 2 credits, charged only when a company is found.
### Search
- [People search](https://docs.reversecontact.com/endpoints/search-people.md): `POST /v2/search/people`. 1 credit per profile delivered. A page with no profile is free. Search the database for people with filters and get full profiles back with cursor pagination.
- [People search count](https://docs.reversecontact.com/endpoints/search-people-count.md): `POST /v2/search/people/count`. Free. Count matching people with the same filters as People search, for free, to size a query before paying 1 credit per profile delivered.
- [Company search](https://docs.reversecontact.com/endpoints/search-companies.md): `POST /v2/search/organizations`. 1 credit per company delivered. A page with no company is free. Search the database for companies with filters and get full company profiles back with cursor pagination.
- [Company search count](https://docs.reversecontact.com/endpoints/search-companies-count.md): `POST /v2/search/organizations/count`. Free. Count matching companies with the same filters as Company search, for free, to size a query before paying 1 credit per company delivered.
- [People lookalike](https://docs.reversecontact.com/endpoints/search-people-lookalike.md): `POST /v2/search/people/lookalike`. 1 credit per profile delivered. A page with no profile is free. Find the people who look like one seed profile, given by Social URL or Reverse Contact person id.
- [Agentic Search](https://docs.reversecontact.com/endpoints/search-people-prompt.md): `POST /v2/search/people/prompt`. 1 credit per page for the search, plus 1 credit per profile delivered. Describe the people you want in plain language and get full profiles back, with the filters we read from your prompt.
- [Agentic Company Search](https://docs.reversecontact.com/endpoints/search-companies-prompt.md): `POST /v2/search/organizations/prompt`. 1 credit per page for the search, plus 1 credit per company delivered. Describe the companies you want in plain language and get full company profiles back, with the filters we read from your prompt.
### Fetch
- [Person profile](https://docs.reversecontact.com/endpoints/fetch-profile.md): `POST /v2/fetch/persons`. 1 credit when the profile is found in the cache. A 404 is free. Retrieve a person's professional profile from a Social URL, with work experience, education, skills and certifications.
- [Person profile live](https://docs.reversecontact.com/endpoints/fetch-profile-live.md): `POST /v2/fetch/persons/live`. 2 credits per request, consumed when the job is created. Trigger a live fetch of a Social profile and retrieve results via polling or webhook callback.
- [Person profile status](https://docs.reversecontact.com/endpoints/check-person.md): `POST /v2/fetch/persons/check`. Free. Needs at least 2 credits in the workspace: below that, 402 NO_CREDITS. Check if a person profile exists in the database, and when it was last updated, before requesting enrichment. The check costs 0 credits.
- [Company profile](https://docs.reversecontact.com/endpoints/fetch-company.md): `POST /v2/fetch/companies`. 1 credit when the company is found in the cache. A 404 is free. Retrieve a company profile from a Social company URL, with industry, employee count, headquarters, office locations and specialties.
- [Company profile live](https://docs.reversecontact.com/endpoints/fetch-company-live.md): `POST /v2/fetch/companies/live`. 2 credits per request, consumed when the job is created. Trigger a live fetch of a Social company profile and retrieve results via polling or webhook callback.
- [Company profile status](https://docs.reversecontact.com/endpoints/check-company.md): `POST /v2/fetch/companies/check`. Free. Needs at least 2 credits in the workspace: below that, 402 NO_CREDITS. Check if a company profile exists in the database, and when it was last updated, before requesting enrichment. The check costs 0 credits.
### Contact
- [Find Email](https://docs.reversecontact.com/endpoints/contact-email.md): `POST /v2/contact/email`. 3 credits when a professional email is found, 5 for a personal one, whatever the emailType: an any lookup costs 3, 5 or 8 (8 when it finds both). A lookup that finds none is free. Find a professional or personal email address from a Social URL, a Reverse Contact person id, or full name and company domain, then receive the result by webhook.
- [Verify Email](https://docs.reversecontact.com/endpoints/contact-email-verify.md): `POST /v2/contact/email/verify`. 1 credit per verdict, whatever it says. A check that fails is refunded. Check whether an email address can receive mail and get a verdict (valid, risky, invalid or unknown) by polling or webhook.
- [Find Phone](https://docs.reversecontact.com/endpoints/contact-phone.md): `POST /v2/contact/phone`. 20 credits when a phone number is found. A lookup that finds none is free. Find a professional phone number from a Social URL, a Reverse Contact person id, or full name and company domain, then receive the result by webhook.
### Utility
- [Usage](https://docs.reversecontact.com/endpoints/usage.md): `GET /v2/usage`. Free. Check your workspace credit balance and rate limit status with GET /v2/usage. The call is free and does not count toward your rate limit.
- [People search available fields](https://docs.reversecontact.com/endpoints/search-people-available-fields.md): `GET /v2/search/people/available-fields`. Free. Discover the filters accepted by the People Search endpoint at runtime, with every allowed value of closed lists such as the position taxonomy.
- [Company search available fields](https://docs.reversecontact.com/endpoints/search-companies-available-fields.md): `GET /v2/search/organizations/available-fields`. Free. Discover the filters accepted by the Company Search endpoint at runtime, with every allowed value of closed lists such as industries and country codes.
- [People auto-suggestion](https://docs.reversecontact.com/endpoints/search-people-auto-suggestion.md): `POST /v2/search/people/auto-suggestion`. Free. Complete a skill as someone types, for free, to build a people search box in your own product.

## Updates
- [What's changing and API changelog](https://docs.reversecontact.com/changes.md): The retirements, breaking changes and maintenance to act on, then every change to the API, release by release.