AI agents & CLI
Agent brief
NewEverything an AI agent needs to call the Reverse Contact API: the entry points, and a brief to paste into its instructions.
- Last verified
Introduction
This page is for developers who build an AI agent on top of the Reverse Contact API, and for the agents themselves. It lists where an agent finds the API's description, then gives a brief to paste into the agent's instructions: the rules that keep it from spending credits for nothing or misreading an answer.
Its Markdown copy is at https://docs.reversecontact.com/agents.md.
Entry points
| Resource | Address | What it is for |
|---|---|---|
| OpenAPI spec | https://docs.reversecontact.com/openapi.json and /openapi.yaml | Every operation with its parameters and responses, its docs page, its credit cost (x-credits) and its status (x-availability) |
| Endpoint catalog | https://docs.reversecontact.com/catalog.json | Every endpoint with its method, path, credit cost, mode and status, the retired endpoints and their replacement, and every page |
| Documentation index | https://docs.reversecontact.com/llms.txt | Every page of this documentation by task, as Markdown links; llms-full.txt holds them all in one file |
| API MCP server | https://api.reversecontact.com/mcp | Tools that call the API from an agent: see Connect AI agents |
| Documentation MCP server | https://docs.reversecontact.com/mcp | Tools that search and read this documentation, with no authentication |
| CLI and agent skill | rc, and npx skills add visum-run/skills | The API from a terminal or a coding agent: see CLI and Agent skills |
| Base URL | https://api.reversecontact.com | Every endpoint: the paths start with /v2, as in the spec |
| Authentication | Authorization: Bearer rc_your_api_key | Every request: see Authentication |
Brief to paste into your agent
Copy this block into the system prompt or the instructions of your agent, and give it the API key in the RC_API_KEY environment variable.
Agent brief
You can call the Reverse Contact API for B2B people and company data.
Spec (OpenAPI 3.1): https://docs.reversecontact.com/openapi.json
Endpoints with their credit cost and status: https://docs.reversecontact.com/catalog.json
Documentation index: https://docs.reversecontact.com/llms.txt
Base URL: https://api.reversecontact.com (every path below starts with /v2)
Auth: Authorization: Bearer $RC_API_KEY (keys start with rc_)
- Requests and responses are JSON. Every response has success, data and error. Most also carry
quotas and metadata, but a 401, 410 or 429 has no quotas.
- Each operation's x-credits field gives its cost. When a response has quotas,
quotas.creditsConsumed says what the call cost.
- Check the balance first with GET /v2/usage (free).
- With a profile URL: POST /v2/fetch/persons/check (free, but it needs at least 2 credits in the
workspace) says whether the profile exists and when it was last updated. Then
POST /v2/fetch/persons (1 credit) for the cached copy, or POST /v2/fetch/persons/live (2 credits) when it is missing or too old. Live fetches are not
available on the free trial: they return 403 TRIAL_ENDPOINT_RESTRICTED there.
- With an email or a name instead: POST /v2/enrich/persons (2 credits, only when a person is found).
- Size a people search with POST /v2/search/people/count (free) before POST /v2/search/people
(1 credit per profile delivered). GET /v2/search/people/available-fields (free) lists the filters:
an unknown filter returns 422 and costs nothing.
- On enrich, a 404 means no confident match; on the cached fetch, a profile not in the cache. Both
are free, and the API never returns a guess instead. Report "not found"; do not retry.
- null in a field means unknown. It is not zero and not an empty value.
- Live fetches, Find Email and Find Phone answer with data.webhookId. Poll
GET /v2/webhooks/{webhookId} (free, not rate limited) until status is succeeded or errored.
- 429: wait error.details.retryAfter seconds, then retry. 500, 502, 503 or 504: retry
with exponential backoff, a few times at most. Any other error: fix the request, do not retry.
- 451: the person was removed under GDPR or CCPA. Drop the record and never retry it.
- /v2/search/persons is retired (410 Gone): use /v2/search/people.Why these rules
Each line of the brief comes from a page of this documentation:
- Free checks and counts before paid calls: Data freshness, People search count and Rate limits & credits.
- A
404rather than a guess, andnullas unknown: Data quality and Missing and empty fields. - Jobs and polling: Polling.
- What to retry: Error handling & retries.
- The retired endpoints: Endpoint transition on October 13, 2026.
FAQ
How do I give an AI agent access to the Reverse Contact API?
Give the agent an API key in the RC_API_KEY environment variable and paste the brief of this page into its instructions: it points to the OpenAPI spec at https://docs.reversecontact.com/openapi.json and states the credit and retry rules. A conversational agent can instead connect to the Reverse Contact MCP server at https://api.reversecontact.com/mcp.
How does an agent know what a Reverse Contact endpoint costs?
Each operation of the Reverse Contact OpenAPI spec carries an x-credits field with its cost, and https://docs.reversecontact.com/catalog.json lists every endpoint with the same information. After a call, quotas.creditsConsumed says what it cost, in the responses that carry quotas (a 401, 410 or 429 does not).
Is there an MCP server for the Reverse Contact documentation?
Yes. https://docs.reversecontact.com/mcp is an MCP server, over Streamable HTTP and with no authentication, whose tools search and read this documentation. It is separate from the API MCP server at https://api.reversecontact.com/mcp, which calls the API itself.