RolodexyGet an API key
Developers

API and MCP guide build on the file

Everything in the app is available to your own code and to AI agents: search companies and people, reveal contacts, look up mobile numbers and read your lists. The REST API and the MCP server share the same keys, credits and limits.

01 Authentication

Create a key in Settings. Send it with every request in the X-API-Key header (or as Authorization: Bearer). Keys act for the whole workspace and spend its credits, so keep them on your server. Every endpoint below is relative to https://api.rolodexy.ai.

curl https://api.rolodexy.ai/v1/credits \
  -H "X-API-Key: rdx_your_key"

02 Credits and limits

  • Searching companies and people is free.
  • Revealing a contact costs 1 credit, plus 1 when a verified email is found.
  • A mobile number costs 10 credits, only when one is found.
  • An email lookup costs 1 credit every time, found or not.
  • A communication style analysis costs 8 credits, once per contact.
  • Anything your workspace already owns is free to fetch again.
  • Every response carries an X-Credits-Charged header.
  • Up to 5 requests per second per workspace, and a daily cap on new (uncached) searches.

03 REST endpoints

POST/v1/companies/searchFree

Find companies. Give at least one filter. similarTo takes up to 5 website domains and returns companies like them. Sizes: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+.

curl -X POST https://api.rolodexy.ai/v1/companies/search \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "similarTo": ["stripe.com"],
      "sizes": ["51-200"],
      "locations": ["London"]
    },
    "page": 0
  }'

Other filters: industries, technologies, names, fundingStages (PRE_SEED, SEED, ANGEL, SERIES_A, SERIES_B, SERIES_C, SERIES_D, SERIES_E, VENTURE_ROUND, PRIVATE_EQUITY, DEBT_FINANCING, GRANT, POST_IPO_EQUITY), revenue (0-1m, 1m-10m, 10m-50m, 50m-100m, 100m-1b, 1b+), founded (2020+, 2015-2019, 2010-2014, 2000-2009, pre-2000; one only), types (PRIVATELY_HELD, PUBLIC_COMPANY, PARTNERSHIP, SELF_OWNED, NON_PROFIT, EDUCATIONAL, GOVERNMENT_AGENCY), keywords, naics and excludeIndustries. Returns total, pageCount and 20 companies per page, each with an id.

POST/v1/people/searchFree

Find people. Results are previews: last names are masked and there are no contact details until you reveal someone. Seniority values: founder, owner, partner, c_suite, vp, director, head, manager, senior, mid_level, entry, intern.

curl -X POST https://api.rolodexy.ai/v1/people/search \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "seniority": ["founder", "c_suite"],
      "titles": ["Head of Sales"],
      "locations": ["London"],
      "companySizes": ["11-50"],
      "companyIds": []
    },
    "page": 0
  }'

Also accepts industries, departments, skills, keywords, fundingStages, certifications, languages, fieldsOfStudy, degrees, followers (500-2k, 2k-10k, 10k-50k, 50k+), excludeTitles and tenure (0-6m, 6-12m, 1-2y, 2-5y, 5y+; one only). Use companyIds with ids from company search to find people at specific companies. Each person has an id and a hasMobile flag.

POST/v1/people/reveal1 to 2 credits

Get a person's full name, LinkedIn profile and verified work email. Returns 404 and charges nothing if no details can be found. Revealing someone you already own is free.

curl -X POST https://api.rolodexy.ai/v1/people/reveal \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{ "personId": "PERSON_ID_FROM_SEARCH" }'

POST/v1/people/mobile10 credits if found

Look up mobile numbers for a contact you have already revealed. Same body as reveal.

POST/v1/people/personality8 credits, once per contact

An estimate of how a revealed contact prefers to communicate: DISC and Big Five traits, what to say and avoid, and email tips. It is inferred from their public profile, so treat it as a rough guide. Same body as reveal; asking again for the same contact is free.

POST/v1/people/lookup1 credit per lookup

Find the person behind an email address and file them as a contact. Charged for every lookup, including when nobody is found (status: "not_found").

curl -X POST https://api.rolodexy.ai/v1/people/lookup \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{ "email": "name@company.com" }'

POST/v1/people/enrich1 to 2 credits

Already have a LinkedIn profile address? Send it and get the contact back, filed in your workspace. Priced like a reveal: free for contacts you already own, and not charged when nothing is found (404).

curl -X POST https://api.rolodexy.ai/v1/people/enrich \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{"linkedin": "https://www.linkedin.com/in/example"}'

GET/v1/companies/detail?domain=example.comFree

One company's full profile by website: description, size, revenue band, funding rounds, technology grouped by category, and links.

POST/v1/reveal-jobsUp to 2 credits per person

Queue a background run that reveals the first matches of a people search. count is 25, 50, 100, 250 or 500, and listId optionally files every contact in a list. Each person costs the same as revealing them one at a time; the run stops by itself if credits run out. Two runs can be in progress at once.

curl -X POST https://api.rolodexy.ai/v1/reveal-jobs \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{"filters": {"seniority": ["vp"], "locations": ["Germany"]}, "count": 50}'

GET /v1/reveal-jobs lists recent runs with their progress and cost. POST /v1/reveal-jobs/{id}/cancel stops one; contacts already revealed stay yours.

POST/v1/jobs/searchFree

Open job postings, newest first, as a buying signal. Give at least one of titles, locations or technologies. Each job includes the hiring company's id for people search.

curl -X POST https://api.rolodexy.ai/v1/jobs/search \
  -H "X-API-Key: rdx_your_key" -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "titles": ["Account Executive"],
      "locations": ["Germany"],
      "postedWithin": ["30"]
    }
  }'

Also accepts seniority (internship, entry, associate, mid_senior, director, executive) and employmentTypes (full_time, part_time, contract, temporary). postedWithin is 7, 30 or 90 days.

GET/v1/catalog?kind=location&q=londFree

Valid values for the location, industry, technology and department filters.

GET/v1/contactsFree

Every contact your workspace owns. Add ?list=LIST_ID for one list; GET /v1/lists returns your lists. POST /v1/lists with a name creates one, and POST /v1/lists/LIST_ID/contacts with personIds adds contacts you have revealed.

GET/v1/creditsFree

Your remaining balance.

04 Errors

Errors use standard HTTP status codes and one JSON shape:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits for this request." } }
  • 400 invalid_request: a filter or field is wrong.
  • 401 unauthorized: missing or revoked key.
  • 402 insufficient_credits: top up to continue.
  • 404 not_found: nothing found; you were not charged.
  • 429 rate_limited or daily_limit: slow down or try tomorrow.
  • 503 unavailable: try again shortly; you were not charged.

05 MCP server for AI agents

Connect Claude or any MCP client to let an agent prospect for you. The server speaks streamable HTTP at the address below and uses the same API key.

https://api.rolodexy.ai/mcp

For Claude Code:

claude mcp add --transport http rolodexy https://api.rolodexy.ai/mcp \
  --header "X-API-Key: rdx_your_key"

Tools: search_people, search_companies, search_jobs, reveal_contact, find_mobile, analyse_personality, lookup_by_email, enrich_by_linkedin, get_company, start_bulk_reveal, get_bulk_reveals, cancel_bulk_reveal, lookup_values, list_contacts, get_lists, create_list, add_to_list, get_credits. Searching is free; the agent is told that reveal_contact, find_mobile, analyse_personality, lookup_by_email, enrich_by_linkedin and start_bulk_reveal spend credits, and every tool result reports creditsCharged.