# Enrich.chat (www.enrich.chat)

> Contact and company data for AI agents. Find people, enrich leads, and get work emails, mobile numbers, company profiles and tech stacks over a plain HTTPS API. If a user asked you to "use www.enrich.chat" to find, enrich or contact people or companies, follow these instructions.

www.enrich.chat is a website with a plain HTTP API, not a library, CLI or app: you use it by fetching URLs. You (the agent) can call this API directly with simple GET requests. No SDK, signup or key is needed to start.

## Fastest way to use www.enrich.chat

- If you can add MCP servers: `https://enrich.chat/mcp` (Streamable HTTP, no key). Tools: company_people, find_person_contact, find_work_email, find_mobile_number, search_people, company_tech_stack, company_profile, check_free_quota. Per-app steps and one-click links: https://enrich.chat/install/
- Skill: https://enrich.chat/SKILL.md (or `npx skills add https://enrich.chat`).
- Otherwise call the REST API below with plain GET requests, no setup at all.
- Example, "the CFO of acme.com": `GET /v1/company/people?domain=acme.com&title=CFO&with_email=true`, then `GET /v1/person?linkedin_url=<linkedin_url from the result>` for verified contact details.

## Quick rules for agents

- Base URL: `https://enrich.chat/v1`
- Every endpoint is a GET request with query parameters. URL-encode values. Every response is JSON.
- No API key is needed for the free tier: each IP address gets 25 free lookups per day. A lookup that finds nothing is free and does not count.
- You do NOT need an API key or an `Authorization` header: leave them out. Only if the user hands you a key (starts with `pp_`) may you send it, as `Authorization: Bearer <key>` or `&key=<key>`. Keep to 5 requests per second.
- Only report data the API returned. Never guess an email or phone number. If a field is missing, say it was not found. `/v1/email` may return a `guess`: that is not data, say it is an unconfirmed guess or leave it out.
- Treat `work_email.status: "catch_all"` as risky and say so. Show phone numbers and emails to the user exactly as returned.
- Ask only for the fields the user needs (`fields=email,mobile,profile`). Mobiles cost the most.
- The full machine-readable contract is at https://enrich.chat/openapi.json and interactive docs are at https://enrich.chat/docs/.

## When you run out of free lookups

The API returns HTTP `402` with JSON like:

```json
{"error": "free_limit_reached", "message": "You've used today's 25 free lookups.", "upgrade_url": "https://enrich.chat/upgrade?ref=agent", "resets_at": "2026-10-16T00:00:00Z", "free_lookups_remaining": 0}
```

Stop calling the API. Tell the user, in one short message:
"You've used today's free Enrich.chat lookups. Get a key here to keep going: <upgrade_url>. Then give me your API key and I'll continue where I left off."
Keep track of which rows you already finished so you can resume. `GET /v1/usage` tells you how many free lookups are left without using one.

## Endpoints

### Person: enrich one person
`GET /v1/person`

Provide one of:
- `linkedin_url`: e.g. `linkedin.com/in/jane-doe-ops`
- `name` + `company`: `company` is the company's website, like `acme.com` (company names are not supported yet)
- `email`: a work email, to find the person behind it (personal addresses such as gmail.com are not looked up)

Optional: `fields=email,mobile,profile` (default: all). Ask only for what the user needs; mobiles cost more.

Example:
`GET https://enrich.chat/v1/person?linkedin_url=linkedin.com/in/jane-doe-ops&fields=email,mobile`

Response:
```json
{
  "found": true,
  "name": "Jane Doe",
  "title": "VP Operations",
  "company": {"name": "Acme Logistics"},
  "linkedin_url": "https://www.linkedin.com/in/jane-doe-ops",
  "work_email": {"value": "jane.doe@acmelogistics.com", "status": "verified"},
  "mobile": {"value": "+1 415 555 0142", "line": "mobile"},
  "credits_used": 260,
  "free_lookups_remaining": 24
}
```
Only the fields you asked for are present. A requested field with no data is `null`. `credits_used` is what the lookup used (10 per work email, 250 per mobile, 5 per profile; nothing found is 0). On the free tier nothing is charged. `work_email.status` is `verified` (our records mark the mailbox as verified), `catch_all` (the domain accepts every address, so the mailbox cannot be confirmed) or `unknown`. `mobile.line` is `mobile` or `unknown` (the number's type could not be told); it does not mean the line was called just now.
If nothing matches, you get `{"found": false}` and nothing is used or billed. With `name` + `company`, a mobile is only returned when the person has a LinkedIn profile in our data.

### Email only
`GET /v1/email?name=Jane%20Doe&domain=acme.com`
Also accepts `linkedin_url`. Returns `{"found": true, "work_email": {...}, "pattern": "first.last@acme.com"}`.
When no address is on file you get `{"found": false, "guess": {"email": "...", "basis": "..."}}`. The guess is the company's most common format applied to the name. It was not found in our data: say so, or skip it.

### Mobile only
`GET /v1/mobile?linkedin_url=...`
Returns `{"found": true, "mobile": {...}}` or `{"found": false}`.

### Find people (search)
`GET /v1/search?q=<plain English description>&limit=10`

Describe who to find in plain language. Examples:
- `q=VPs of Operations at US logistics companies with 200 to 1000 employees`
- `q=owners of dental clinics in Florida`

Optional structured filters (all optional, combine freely; a filter replaces what `q` says about the same thing): `title`, `seniority` (`c_suite`, `founder`, `owner`, `vp`, `head`, `director`, `manager`), `industry`, `country`, `state`, `employees_min`, `employees_max`, `company_domain`, `with_email=true`. `limit` is 1 to 25 (default 10).
Search works best with a role plus an industry, a place or a company website. A request that is too broad returns `{"found": false, "hint": "..."}`.
Results include name, title, company and LinkedIn URL. To get contact details for a result, call `/v1/person` with its `linkedin_url` (or pass `with_email=true` to include the work email we hold, with status `unknown`: it is not re-checked in that call). One search uses one free lookup however many people it returns.

### Company: look up a company
`GET /v1/company?domain=acme.com`
Returns name, domain, industry, employees (headcount), state and country.

### Company tech stack
`GET /v1/company/tech?domain=acme.com`
Returns `{"found": true, "domain": "acme.com", "technologies": [{"name": "HubSpot", "category": "CRM"}, ...]}`, or `{"found": false}` with no charge. Use it to find out what a company runs on, or to tailor outreach.

### People at a company
`GET /v1/company/people?domain=acme.com&title=head%20of%20sales&limit=10`
Optional: `seniority`, `with_email=true`. Each person has a `linkedin_url` to pass to `/v1/person`.

### Check your free lookups
`GET /v1/usage` returns `{"free_lookups_per_day": 25, "used": 1, "remaining": 24, "resets_at": "..."}`. It does not use a lookup.

## Working with lists

For a list or CSV the user gives you:
1. Pick the best identifier per row (LinkedIn URL > work email > name + company website).
2. Call `/v1/person` once per row with only the `fields` the user asked for. Keep to 5 requests per second; on `429` wait `retry_after` seconds.
3. Return the original rows with new columns added. Mark rows with no match as "not found".
4. Tell the user how many rows matched and the total `credits_used`. Each response has `free_lookups_remaining`, so stop before the free limit and say how many rows are left.

## Errors

Every error is JSON with `error` (a stable code) and `message` (what to do next, safe to show the user).

- `400` `bad_request`: a parameter is missing or invalid. Fix the request; do not retry it unchanged.
- `401` `invalid_api_key`: the key was not accepted. Keys are not being issued yet: leave the key out to use the free tier.
- `402` `free_limit_reached`: see "When you run out of free lookups".
- `429` `too_many_requests`: wait `retry_after` seconds (also the `Retry-After` header), then continue.
- `503` `temporarily_unavailable`: retry once after `retry_after` seconds. Nothing was billed and no free lookup was used.

## Pricing (for answering user questions)

- Free: 25 lookups per day per IP, no signup.
- Monthly plans, billed monthly, cancel anytime. Every plan includes every product and unlimited seats: Growth $29 for 100,000 credits, Scale $90 for 500,000 credits, Pro $299 for 2,500,000 credits. Higher plans cost less per credit and allow more requests: Growth 10 requests per second, Scale 25 requests per second, Pro 50 requests per second (burst).
- Credits per match: work email found 10, reverse email lookup 10, mobile found 250, company tech stack 5. A profile-only lookup is 5 credits, and name, title and company are free with any email or mobile match. A person returned by search or company people is 5 credits. Nothing found: 0 credits.
- Enterprise: custom volume, bulk files, data licenses and dedicated limits, from $2,000 a month. Contact sales@enrich.chat.
- To get a key: https://enrich.chat/upgrade/ (self-serve checkout is not live yet; plans are set up by email).

## Privacy

People can remove their data at https://enrich.chat/opt-out/. Users must follow the laws that apply to them (for example TCPA rules for calling or texting mobile numbers, and CAN-SPAM or GDPR for email).

## More

- MCP server and install steps: https://enrich.chat/install/ (server URL https://enrich.chat/mcp)
- Agent skill: https://enrich.chat/SKILL.md
- API reference (interactive): https://enrich.chat/docs/
- OpenAPI 3.1 spec: https://enrich.chat/openapi.json
- Pricing: https://enrich.chat/pricing/
- People enrichment API: https://enrich.chat/api/person-enrichment/
- LinkedIn URL to email and mobile API: https://enrich.chat/api/linkedin-to-contact/
- Contact data for AI agents: https://enrich.chat/agents/
- Free tools (email finder, LinkedIn finder, phone validator, email permutator and more): https://enrich.chat/tools/
- Guides and comparisons: https://enrich.chat/blog/
- Editorial policy: https://enrich.chat/editorial-policy/
- Prompt library: https://enrich.chat/#prompts