> Enrich.chat gives AI agents verified work emails and mobiles. To use it from an agent, read https://enrich.chat/agents.md . This is the Markdown version of https://enrich.chat/docs/

# Enrich.chat API reference

> Base URL: `https://enrich.chat/v1`. Every endpoint is a `GET` with query parameters and returns JSON. Machine-readable spec: [https://enrich.chat/openapi.json](https://enrich.chat/openapi.json). Interactive docs: [https://enrich.chat/docs/](https://enrich.chat/docs/).

Contact and company data for AI agents and apps. Find a person's **work email** and **mobile number** from a LinkedIn URL, a name and company website, or a work email; **search people** by role, seniority, industry, location and company size; look up a **company** and the **technologies** it runs on.

## No signup, no key
Every IP address gets **10 free lookups a day** with no API key. A lookup that finds nothing is free and does not count. After that the API answers HTTP `402` with an `upgrade_url`. Keep to 5 requests per second (300 a minute); past that the API answers `429` with `retry_after`.

## API keys (optional)
You never need a key or an `Authorization` header to use the free tier: leave them out. A key comes with a paid plan and lifts the daily cap: log in with your email at https://enrich.chat/account/, pick a plan, pay through checkout, and your key (it starts with `pp_`) appears on that page. Send it as `Authorization: Bearer pp_...` or a `key` query parameter. Each lookup then spends credits from your plan's monthly allowance; `credits_exhausted` (402) means they are used up until the plan renews, `plan_inactive` (402) means billing needs attention, and `invalid_api_key` (401) means the key is wrong or revoked.

## Pricing
Monthly plans: Growth $29 for 100,000 credits, Scale $90 for 500,000 credits, Pro $299 for 2,500,000 credits. Credits per match: work email 10, reverse email 10, mobile 250, company tech stack 5, nothing found 0. A person profile, a company profile or tech stack, or a person returned in a list is 5 credits. Full details: https://enrich.chat/pricing/.

## For AI agents
If a person asked you to "use www.enrich.chat", read https://enrich.chat/agents.md. It is written for you and covers this whole API in one page. Every endpoint is a plain `GET`, so no SDK is needed.

## Data and accuracy
`work_email.status` is `verified` when our records mark the mailbox as verified, `catch_all` when the domain accepts every address so the mailbox cannot be confirmed, and `unknown` otherwise. `mobile.line` is `mobile` when the number is a mobile number and `unknown` when its type cannot be told. Treat every contact as a strong lead, not a guarantee. People can remove their data at https://enrich.chat/opt-out/, and callers must follow the laws that apply to them (for example TCPA for calls and texts, CAN-SPAM and GDPR for email).

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| GET | `/v1/person` | Find a person |
| GET | `/v1/email` | Find a work email |
| GET | `/v1/mobile` | Find a mobile number |
| GET | `/v1/search` | Search for people |
| GET | `/v1/company` | Look up a company |
| GET | `/v1/company/tech` | Find a company's tech stack |
| GET | `/v1/company/people` | List people at a company |
| GET | `/v1/usage` | Check your free lookups |

## GET /v1/person

**Find a person.** Enrich one person. Provide **one** of: `linkedin_url`; `name` with `company` (a website); or `email` (a work email, to find who is behind it). The response carries the work email, the mobile and the profile (name, title, company), limited to `fields`.

To get a mobile from a name and company, the person must be in our data with a LinkedIn profile; otherwise `mobile` is `null`. `found` is `false` when none of the requested fields came back. People who opted out are never returned.

Credits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `linkedin_url` | string | no | A LinkedIn profile URL, with or without https://www. Example: `linkedin.com/in/jane-doe-ops`. |
| `name` | string | no | Full name, first and last. Use with `company`. Example: `Jane Doe`. |
| `company` | string | no | A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet. Example: `acme.com`. |
| `email` | string | no | A work email address. Personal mailboxes (gmail.com and similar) are not looked up. Example: `jane.doe@acme.com`. |
| `fields` | string | no | Which fields to return, as a comma list of `email`, `mobile` and `profile` (name, title, company). Default: all three. Ask only for what you need: a mobile costs the most. Example: `email,mobile`. |

```bash
curl "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@acme.com",
    "status": "verified"
  },
  "mobile": {
    "value": "+1 415 555 0142",
    "line": "mobile"
  },
  "credits_used": 260,
  "free_lookups_remaining": 24
}
```

## GET /v1/email

**Find a work email.** Find the work email for a person from `name` and `domain`, or from `linkedin_url`. If we have no address on file, the response is `found: false` with a `guess` built from the company's most common address format. A guess is never data: confirm it before you rely on it, and do not tell the person it was found.

Credits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Full name, first and last. Example: `Jane Doe`. |
| `domain` | string | no | A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet. Example: `acme.com`. |
| `linkedin_url` | string | no | A LinkedIn profile URL, with or without https://www. Example: `linkedin.com/in/jane-doe-ops`. |

```bash
curl "https://enrich.chat/v1/email?name=Jane%20Doe&domain=acme.com"
```

Response:

```json
{
  "found": true,
  "work_email": {
    "value": "jane.doe@acme.com",
    "status": "verified"
  },
  "pattern": "first.last@acme.com",
  "name": "Jane Doe",
  "title": "VP Operations",
  "credits_used": 10,
  "free_lookups_remaining": 24
}
```

## GET /v1/mobile

**Find a mobile number.** Find the mobile number for a LinkedIn profile. Mobiles cost the most, so ask only when you need one. A landline-only profile returns `found: false`.

Credits: a work email found is 10 credits, a mobile found is 250, and a profile alone is 5. Name, title and company come free with an email or a mobile. A lookup that finds nothing costs 0 credits and does not use a free lookup. `credits_used` shows what the call used; on the free tier nothing is charged.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `linkedin_url` | string | yes | A LinkedIn profile URL, with or without https://www. Example: `linkedin.com/in/jane-doe-ops`. |

```bash
curl "https://enrich.chat/v1/mobile?linkedin_url=linkedin.com/in/jane-doe-ops"
```

Response:

```json
{
  "found": true,
  "mobile": {
    "value": "+1 415 555 0142",
    "line": "mobile"
  },
  "credits_used": 250,
  "free_lookups_remaining": 24
}
```

## GET /v1/search

**Search for people.** Describe who to find in plain English with `q`, or use the structured filters, or both (a filter replaces what `q` says about the same thing). Results include name, title, company and LinkedIn URL. Call `/person` with a result's `linkedin_url` for verified contact details, or pass `with_email=true` to include the email we hold.

It works best with a role plus an industry, a location or a company website. A request that is too broad (a role alone) returns `found: false` with a `hint`. Returns up to 25 people per call.

One search that returns people uses one free lookup, however many people it returns. Credits: 5 per person returned (a 25-person result is 125); 0 when nothing is found.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Who to find, in plain English, up to 300 characters. Example: `VPs of Operations at US logistics companies with 200 to 1,000 employees`. |
| `title` | string | no | Job title or function, such as `head of sales` or `recruiter`. Example: `recruiter`. |
| `seniority` | `c_suite` or `founder` or `owner` or `vp` or `head` or `director` or `manager` | no | Seniority level. Example: `vp`. |
| `industry` | string | no | Industry in plain words, such as `hospitals` or `software`. Example: `logistics`. |
| `country` | string | no | Country name, such as `United States`. Example: `United States`. |
| `state` | string | no | US state name. Implies the United States. Example: `Texas`. |
| `employees_min` | integer 0 to 10000000 | no | Minimum company headcount. Example: `200`. |
| `employees_max` | integer 0 to 10000000 | no | Maximum company headcount. Example: `1000`. |
| `company_domain` | string | no | Only people at this company website. Example: `acme.com`. |
| `limit` | integer 1 to 25 | no | How many people to return, 1 to 25. Example: `10`. |
| `with_email` | boolean | no | Only return people we have a work email for, and include it. The email status is `unknown` here because it is not re-checked in this call; use `/person` for the status. Example: `False`. |

```bash
curl "https://enrich.chat/v1/search?q=IT%20directors%20at%20US%20hospitals%20with%201000%2B%20employees&limit=5"
```

Response:

```json
{
  "found": true,
  "count": 2,
  "people": [
    {
      "name": "Dana Whitfield",
      "title": "Director of IT",
      "company": "Mercy General",
      "linkedin_url": "https://www.linkedin.com/in/dana-whitfield"
    },
    {
      "name": "Luis Ortega",
      "title": "CIO",
      "company": "St. Anne Health",
      "linkedin_url": "https://www.linkedin.com/in/luis-ortega"
    }
  ],
  "credits_used": 10,
  "free_lookups_remaining": 24
}
```

## GET /v1/company

**Look up a company.** Company profile for a website: name, industry, headcount and location. Revenue range and founding year are not returned yet.

Credits: 5 per profile found; 0 when nothing is found.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet. Example: `acme.com`. |

```bash
curl "https://enrich.chat/v1/company?domain=acme.com"
```

Response:

```json
{
  "found": true,
  "name": "Acme Logistics",
  "domain": "acme.com",
  "industry": "logistics & supply chain",
  "employees": 420,
  "state": "Texas",
  "country": "United States",
  "credits_used": 5,
  "free_lookups_remaining": 24
}
```

## GET /v1/company/tech

**Find a company's tech stack.** The technologies a company runs on, each with a category (CRM, email, hosting, analytics and so on). Use it to find companies that use a tool or to tailor outreach.

Credits: 5 per company with a tech stack found; 0 when nothing is found.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet. Example: `acme.com`. |

```bash
curl "https://enrich.chat/v1/company/tech?domain=acme.com"
```

Response:

```json
{
  "found": true,
  "domain": "acme.com",
  "company": "Acme Logistics",
  "technologies": [
    {
      "name": "Google Workspace",
      "category": "Email"
    },
    {
      "name": "HubSpot",
      "category": "CRM"
    }
  ],
  "credits_used": 5,
  "free_lookups_remaining": 24
}
```

## GET /v1/company/people

**List people at a company.** Find people at a company by its website, optionally narrowed by `title` and `seniority`. Each person has a `linkedin_url`: pass it to `/person` for verified contact details.

One call that returns people uses one free lookup, however many people it returns. Credits: 5 per person returned; 0 when nothing is found.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | A company website, like `acme.com`. A full URL is accepted and reduced to its domain. Company names are not supported yet. Example: `acme.com`. |
| `title` | string | no | Job title or function, such as `head of sales`. Example: `head of sales`. |
| `seniority` | `c_suite` or `founder` or `owner` or `vp` or `head` or `director` or `manager` | no | Seniority level. Example: `director`. |
| `limit` | integer 1 to 25 | no | How many people to return, 1 to 25. Example: `10`. |
| `with_email` | boolean | no | Only return people we have a work email for, and include it. The email status is `unknown` here because it is not re-checked in this call; use `/person` for the status. Example: `False`. |

```bash
curl "https://enrich.chat/v1/company/people?domain=mercy.org&title=it%20director&limit=5"
```

Response:

```json
{
  "found": true,
  "count": 2,
  "domain": "mercy.org",
  "people": [
    {
      "name": "Dana Whitfield",
      "title": "Director of IT",
      "company": "Mercy General",
      "linkedin_url": "https://www.linkedin.com/in/dana-whitfield"
    },
    {
      "name": "Luis Ortega",
      "title": "CIO",
      "company": "St. Anne Health",
      "linkedin_url": "https://www.linkedin.com/in/luis-ortega"
    }
  ],
  "credits_used": 10,
  "free_lookups_remaining": 24
}
```

## GET /v1/usage

**Check your free lookups.** How many of today's 10 free lookups this IP address has used. With an API key it returns your plan's credits instead. It does not use a lookup itself, so an agent can check before a large job.

```bash
curl "https://enrich.chat/v1/usage"
```

Response:

```json
{
  "free_lookups_per_day": 10,
  "used": 1,
  "remaining": 9,
  "resets_at": "2026-10-16T09:12:44Z"
}
```

## Errors

Every error is JSON with `error` (a stable code) and `message` (what to do next).

| Status | `error` | Meaning |
| --- | --- | --- |
| 400 | `bad_request` | A parameter is missing or invalid. Fix it; do not retry unchanged. |
| 401 | `invalid_api_key` | The key is wrong or revoked. Check https://enrich.chat/account/, or leave it out to use the free tier. |
| 402 | `credits_exhausted` | The plan's credits are used up until it renews. Upgrade at https://enrich.chat/account/. |
| 402 | `plan_inactive` | The plan behind the key is not active. Check billing at https://enrich.chat/account/. |
| 402 | `free_limit_reached` | Today's 10 free lookups are used. Stop, tell the person, show `upgrade_url`. Resume after `resets_at`. |
| 429 | `too_many_requests` | Wait `retry_after` seconds (also in the `Retry-After` header), then continue. |
| 503 | `temporarily_unavailable` | Retry once after `retry_after` seconds. Nothing was billed. |