For agents
WhoLayer for AI agents
Everything an agent can use today: two MCP servers, a REST API with an OpenAPI spec, markdown for every page, and limits that keep an agent's spending where you set it.
What WhoLayer is
WhoLayer identifies website visitors and enriches them with verified emails and mobiles, then sends them to Slack, HubSpot, Klaviyo, signed webhooks, or an AI agent. One tag powers Visitor ID (people and companies visiting a B2B site; person-level for US traffic only, company-level free and unlimited) and Shopper ID (anonymous US shoppers sent to Klaviyo). The Data API and MCP server give code and AI agents the same identity and contact data with per-key spend caps, and Identity Cloud licenses identity data to platforms. Every product draws from one credit wallet. Opted-out people are never returned or charged.
Surfaces at a glance
| Surface | URL | Auth |
|---|---|---|
| Data MCP server (13 tools) | https://mcp.wholayer.com/mcp | API key (Bearer) |
| Docs MCP server (5 tools) | https://mcp.wholayer.com/docs | None |
| REST API | https://api.wholayer.com/v1 | API key (Bearer) |
| OpenAPI 3.1 spec | /openapi.json | None |
| Site index for LLMs | /llms.txt and /llms-full.txt | None |
| Markdown version of any public page | Add .md to the URL (home is /index.md), or send Accept: text/markdown | None |
Data MCP server
The same identity and contact data as the REST API. Create a key under Settings, API keys. A wl_test_... key returns sandbox data from every tool and never spends credits, so start there.
claude mcp add --transport http wholayer https://mcp.wholayer.com/mcp \
--header "Authorization: Bearer wl_test_YOUR_KEY"Install snippets for Claude Desktop, Cursor (one click), VS Code, and other clients are on the MCP docs.
| Tool | What it does | Credits | Read-only key |
|---|---|---|---|
enrich_person | Find a person's verified work email, personal email, and/or mobile from a LinkedIn URL, an email, or name + company domain. | 1 credit per work email, 2 per personal email, and 5 per mobile returned, plus 10 for a reverse lookup when you send only an email and we find the person. Nothing if no match. | No |
search_people | Find people by title, seniority, department, company size, industry, and country. Returns profiles without contact details (use enrich_person to reveal). | 1 credit per 10 results returned, rounded up; nothing if none. | No |
verify_emails | Check deliverability for up to 1,000 email addresses, graded A (safe) to F (will bounce). | 0.25 credits per address. | No |
lookup_phone | Find a mobile number with a live carrier and line-type check, by person_id, email, LinkedIn URL, or name + company domain. | 5 credits when a mobile is returned; nothing if not found. | No |
get_company | Company profile from a domain: size, revenue range, industry, HQ. | 1 credit when a profile is returned; nothing if not found. | Allowed |
list_visitors | People and companies identified on your sites, newest first. | Free. | Allowed |
get_balance | Credits remaining, plan, monthly spend cap, and this key's daily cap. | Free. | Allowed |
estimate_cost | Quote the most credits an operation could spend before running it: enrich (with reveal), phones, verify (with rows), company, search (with limit), or bulk (with rows and reveal). We only charge on hits, so the real cost is the same or lower. | Free. | Allowed |
get_compliance_policy | Machine-readable rules WhoLayer enforces: US-only person-level identification, consent outside the US, Global Privacy Control, blocked sensitive-page categories, suppression sources and reason codes, and retention periods. | Free. | Allowed |
report_bad_data | Report a wrong person, a bounced email, or outdated data, by result_id (the per_… id from enrich_person) or identity_id (a visitor's person_id from list_visitors). Credits charged for a reported result are refunded if it was charged in the last 30 days, once per result. Refunds in any rolling 30 days are capped at 10% of the credits the workspace spent in that window; reports above the cap wait for review by our team and nothing is refunded automatically. The result is not delivered again. | Free. | No |
create_job | Queue an enrich or verify job of up to 100,000 rows that runs in the background. Returns a job id right away; poll it with get_job. Each row is billed like a single call, and the whole job never spends more than max_credits (default 250). Optional webhook_url gets a signed job.completed or job.failed event. Results are kept 30 days. | 1 credit per work email, 2 per personal email, and 5 per mobile returned, plus 10 for a reverse lookup when you send only an email and we find the person. Nothing if no match. Verify rows: 0.25 per address. | No |
get_job | Status, progress, and credits used for a job from create_job, plus a page of results (up to 100 rows per call; pass cursor for the next page). Withheld people come back as rows with error.code person_not_available and a reason. | Free. | Allowed |
add_to_suppression | Adds emails or SHA-256 email hashes to this workspace's suppression list. Listed people are never returned, delivered, or charged for in this workspace. Emails are hashed on arrival; only hashes are stored. Removing entries is only possible from the dashboard (Settings, Suppression list), so confirm with the user before calling. | Free. | No |
Every tool returns credits_used and credits_remaining. REST responses carry an X-Credits-Remaining header.
Docs MCP server
Read-only access to WhoLayer's public website, pricing, and help center. No key, no credits, and it never sees customer data.
claude mcp add --transport http wholayer-docs https://mcp.wholayer.com/docs| Tool | What it does |
|---|---|
search_docs | Search every public WhoLayer page and help article. Returns paths, titles, and snippets. |
read_page | Return the markdown of any public wholayer.com page, e.g. /pricing or /help/mcp-setup. |
get_pricing | Plans, monthly prices, included credits, overage rates, and credit costs per action. |
get_products | The four WhoLayer products with what each does, features, integrations, and pricing notes. |
list_help_articles | Every help center article with its category, summary, and markdown URL. |
Spend controls and safe retries
- Per-key daily cap. Give each agent its own key with a maximum number of credits per day. When it's reached, calls return
credits_exhausteduntil the next day. - Monthly spend cap. A workspace-wide hard limit, set on the Usage page.
- Per-call ceiling. One call can't spend more than 250 credits unless you raise it with the
X-Max-Creditsheader (REST) or themax_creditsargument (MCP), up to 10,000. - Read-only keys. Limited to the tools marked “Allowed” above, for agents that should never reveal contact details.
- Idempotency. Send an
Idempotency-Keyheader on REST POST requests; a retry within 30 days returns the stored result without charging again. On the MCP server, repeated identical calls to paid tools within 30 days return the cached result for free. - Rate limits per key. Free 2, Starter 10, Growth 25, Scale 100, Platform 1,000 requests a second. Bulk calls take up to 1,000 rows.
Compliance rules agents can read
The rules WhoLayer enforces are published as JSON at GET /v1/policy (any API key, including read-only) and through the get_compliance_policy MCP tool: US-only person-level identification, consent outside the US, Global Privacy Control, blocked sensitive-page categories, suppression sources, and retention periods.
When a person can't be returned, the API answers HTTP 451 with error.code person_not_available and one of these reasons. You're never charged for them:
| Reason | Meaning |
|---|---|
opted_out | This person has opted out of WhoLayer. No data is returned and you were not charged. |
drop_deleted | This person asked to be deleted through California's Delete Request and Opt-out Platform (DROP). No data is returned and you were not charged. |
customer_suppressed | This person is on your workspace's suppression list. No data is returned and you were not charged. |
non_us | Person-level data is available for US visitors only. No data is returned and you were not charged. |
sensitive | People are never identified on sensitive pages. No data is returned and you were not charged. |
Agents can add people to your workspace's suppression list with add_to_suppression or POST /v1/suppression.
Contacting people is your responsibility. If your agent emails, calls, or texts the people it finds, follow the Acceptable Use Policy, including CAN-SPAM and TCPA consent rules for calls and texts.
Credit costs
| Action | Credits | Note |
|---|---|---|
| Company identified (who's visiting, at the account level) | Free | Unlimited on every plan |
| Person identified on your site (name, title, LinkedIn, work email) | 1 | Only charged when we return a person. Repeat visits by the same person in a month are free. |
| Shopper identified for ecommerce (new to your list: verified personal email, sent to Klaviyo) | 2 | With Klaviyo connected, charged once per new shopper and refunded (within the refund limit) if they bounce or mark you as spam within 30 days; without Klaviyo, once per shopper per month. Opted-out people are never returned. |
| Shopper recognized who is already in your Klaviyo (no duplicate created; triggers a Returning Shopper event) | 1 | Half the price of a new shopper. Return visits we recognize by our own cookie or your site's hashed email are free, and so are holdout shoppers. |
| Work email found and verified | 1 | No charge if we don't find one. |
| Personal email found and verified | 2 | No charge if we don't find one. |
| Reverse email lookup (send an email, get the person: name, title, company, LinkedIn) | 10 | Only when you send an email alone and we find the person. No charge if we don't. |
| Mobile number with carrier and line-type check | 5 | No charge if we don't find one. |
| Email verification only | 0.25 | 4 verifications per credit. |
| People search results (name, title, company; no contact details) | 1 per 10 | Charged per 10 results returned, rounded up. Contact details are charged separately when you enrich a result. |
| Company profile (size, revenue, industry) | 1 | No charge if we don't have one. |
Plans and overage rates are on pricing. Everything on this page is generated from the same constants the code charges and enforces.