> 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; `/batch`, `/search/cascade`, `/jobs` and `/webhooks` take a JSON body. 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** and **companies** by role, seniority, department, industry, location, company size, revenue, technology, funding and growth; look up a **company**, the **technologies** it runs on and its **email format**. Counts and the filter lists are free. ## 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, and neither does a count or a filter list. After that the API answers HTTP `402` with an `upgrade_url`. The free tier allows about one request a second (up to 120 a minute and 200 an hour per IP). Paid plans allow 10 (Growth), 25 (Scale) or 50 (Pro) requests a second. Past a limit 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, mobile 250, company tech stack 5, nothing found 0. A person profile, a company profile or tech stack, an email format, or a person or company returned in a list is 5 credits. Counts and filter lists cost nothing. Full details: https://enrich.chat/pricing/. ## How searching works Describe who you want in plain English with `q`, pass filters, or both. The answer includes `interpreted_as`: how your request was read, using the exact filter names and values. A filter value we do not know returns `unknown_filter_value` with `did_you_mean` suggestions, and `GET /v1/facets/{name}` lists every value. Each person and company has an opaque `id` (`per_...`, `org_...`) you can pass back to look them up in one fast call. Ask for `/v1/search/count` first when you only need to know how many there are. ## 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` (`/batch`, `/search/cascade`, `/jobs` and `/webhooks` take a JSON body), 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/search/count` | Count matching 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/companies` | Search for companies | | GET | `/v1/companies/count` | Count matching companies | | GET | `/v1/email-pattern` | Find a company's email format | | GET | `/v1/filters` | List every filter | | GET | `/v1/facets` | List the filter lists | | GET | `/v1/facets/{facet}` | List the values of a filter | | POST | `/v1/batch` | Run up to 25 lookups in one call | | POST | `/v1/search/cascade` | Search with match tiers | | POST | `/v1/jobs` | Start a background job | | GET | `/v1/jobs` | List your jobs | | GET | `/v1/jobs/{job_id}` | Check a job | | DELETE | `/v1/jobs/{job_id}` | Delete a job | | GET | `/v1/jobs/{job_id}/results` | Get a job's results | | POST | `/v1/jobs/{job_id}/cancel` | Cancel a job | | POST | `/v1/webhooks` | Add a webhook | | GET | `/v1/webhooks` | List your webhooks | | DELETE | `/v1/webhooks/{webhook_id}` | Delete a webhook | | POST | `/v1/webhooks/{webhook_id}/test` | Send a test delivery | | GET | `/v1/usage` | Check your free lookups | ## GET /v1/person **Find a person.** Enrich one person. Provide **one** of: `linkedin_url`; `person_id` (from a search result); `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, level, department, location), limited to `fields`. To get a mobile from a name and company, we must hold one for that person; 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`. | | `person_id` | string | no | The `id` of a person from a search result (starts with `per_`). The fastest way to look someone up. Example: `per_4Hk2x9QmVb7LrTzE`. | | `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 and the rest of the profile). 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, "id": "per_4Hk2x9QmVb7LrTzE", "name": "Jane Doe", "title": "VP Operations", "company": { "name": "Acme Logistics", "domain": "acme.com", "size": "201-500", "industry": "Transportation, Logistics, Supply Chain and Storage" }, "level": "vp", "function": "Operations", "persona": "Operations", "location": { "city": "Dallas", "state": "Texas", "country": "United States" }, "started_current_role": "2024-03-01", "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": 9 } ``` ## GET /v1/email **Find a work email.** Find the work email for a person from `name` and `domain`, from `linkedin_url`, or from `person_id`. 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`. | | `person_id` | string | no | The `id` of a person from a search result (starts with `per_`). The fastest way to look someone up. Example: `per_4Hk2x9QmVb7LrTzE`. | ```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": 9 } ``` ## GET /v1/mobile **Find a mobile number.** Find the mobile number for a LinkedIn profile, a `person_id` or a work email. 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 | no | A LinkedIn profile URL, with or without https://www. Example: `linkedin.com/in/jane-doe-ops`. | | `person_id` | string | no | The `id` of a person from a search result (starts with `per_`). The fastest way to look someone up. Example: `per_4Hk2x9QmVb7LrTzE`. | | `email` | string | no | A work email address. Example: `jane.doe@acme.com`. | ```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": 9 } ``` ## GET /v1/search **Search for people.** Find people across companies. Describe who in plain English with `q`, use the structured filters, or both (a filter replaces what `q` says about the same thing). Results show who they are and whether we hold an email (`has_email`) or a mobile (`has_mobile`). Pass a result's `id` as `person_id` to `/person` for the contact details, or use `with_email=true` to include the email we hold. Filters combine with AND; several values of one filter combine with OR. Names are matched leniently (`software development`, `Software_Development`) and a wrong value returns suggestions. It works best with a role plus an industry, a location or a company; a request that names nobody in particular returns `search_too_broad`. Results come best first: people with both an email and a mobile, then email only, then the most recently updated. Pages hold up to 25 and a search can be paged 40 times (1,000 results); narrow the filters to go deeper. `total_matches` says how many match in all, when that is quick to work out. 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. To only learn how many people match, use `count_only=true` or `/search/count`: free. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `q` | string | no | Describe who to find in plain English, up to 300 characters. Any filter you also pass replaces what `q` says about the same thing; `interpreted_as` in the answer shows how it was read. Example: `IT directors at US hospitals with 1,000+ employees`. | | `title` | string | no | Job title or function, such as `head of sales` or `recruiter`. Seniority words (`VP`, `director`, `chief`) become a seniority filter and the other words must appear in the title. Example: `head of sales`. | | `seniority` | string | no | Seniority: `c_suite`, `founder`, `owner`, `vp`, `head`, `director` or `manager`. Several values: a comma list or the parameter repeated. Example: `vp`. | | `level` | string | no | Job level, finer than seniority: `c_suite`, `vp`, `director`, `manager`, `staff` or `other`. Several values: a comma list or the parameter repeated. Example: `director`. | | `function` | string | no | Department the person works in, such as `Sales & Business Development` or `Engineering`. See `GET /v1/facets/function`. Several values: a comma list or the parameter repeated. Example: `Sales & Business Development`. | | `persona` | string | no | A role group, such as `CEO / Founder` or `Sales Leadership`. See `GET /v1/facets/persona`. Several values: a comma list or the parameter repeated. Example: `CEO / Founder`. | | `company_domain` | string | no | Only people at these company websites (up to 50, comma list). Example: `acme.com`. | | `exclude_domains` | string | no | Leave out people at these company websites (up to 50, comma list). Example: `competitor.com`. | | `started_role_within_days` | integer 1 to 3650 | no | Only people who started their current role in the last N days: a buying signal. Example: `90`. | | `has_email` | boolean | no | Only people we have a work email for. `with_email` is the same and also returns it. Example: `False`. | | `has_mobile` | boolean | no | Only people we have a mobile number for. Example: `False`. | | `industry` | string | no | Industry, such as `Software Development` or `Hospitals and Health Care`. See `GET /v1/facets/industry`. Several values: a comma list or the parameter repeated. Example: `Software Development`. | | `country` | string | no | Country, such as `United States`. For a people search it is where the person is; for a company search, where the company is based. Several values: a comma list or the parameter repeated. Example: `United States`. | | `state` | string | no | US state, such as `Texas`. Implies the United States. Several values: a comma list or the parameter repeated. Example: `Texas`. | | `company_size` | string | no | Company headcount range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Several values: a comma list or the parameter repeated. Example: `51-200`. | | `employees_min` | integer 0 to 10000000 | no | Minimum company headcount. Matches the size ranges that lie wholly above it. Example: `200`. | | `employees_max` | integer 0 to 10000000 | no | Maximum company headcount. Matches the size ranges that lie wholly below it. Example: `1000`. | | `company_revenue` | string | no | Company revenue range: `<1M`, `1M-10M`, `10M-50M`, `50M-100M`, `100M-1B`, `1B+`. Several values: a comma list or the parameter repeated. Example: `10M-50M`. | | `uses` | string | no | Technologies the company runs, such as `hubspot` or `salesforce` or `aws`. A company must use all of them. See `GET /v1/facets/technology`. Several values: a comma list or the parameter repeated. Example: `hubspot`. | | `funding_stage` | string | no | The company's latest funding stage, such as `Series A`. See `GET /v1/facets/funding_stage`. Several values: a comma list or the parameter repeated. Example: `Series A`. | | `funded_since` | string | no | Only companies funded on or after this date. Example: `2026-01-01`. | | `growth_min` | integer -100 to 10000 | no | Minimum employee growth in percent over the last year, such as `20`. Example: `20`. | | `traffic_min` | integer 0 to | no | Minimum monthly website visits. Example: `10000`. | | `founded_after` | integer 1000 to 2100 | no | Founded in or after this year. Example: `2018`. | | `founded_before` | integer 1000 to 2100 | no | Founded in or before this year. Example: `2024`. | | `company_country` | string | no | Country the company is headquartered in (a people search; in a company search use `country`). Several values: a comma list or the parameter repeated. Example: `Germany`. | | `company_state` | string | no | US state the company is headquartered in (a people search). Several values: a comma list or the parameter repeated. Example: `Texas`. | | `city` | string | no | City the person is in. Several values: a comma list or the parameter repeated. People searches only. Example: `Austin`. | | `continent` | string | no | Continent the person is in. Several values: a comma list or the parameter repeated. One of: North America, Europe, Asia, South America, Africa, Oceania. People searches only. Example: `Europe`. | | `region` | string | no | Sales region the person is in. Several values: a comma list or the parameter repeated. One of: NORAM, EMEA, APAC, LATAM. People searches only. Example: `EMEA`. | | `skills` | string | no | Skill listed on the profile. People searches only. Example: `python`. | | `headline` | string | no | Words in the profile headline. People searches only. Example: `revenue operations`. | | `connections_min` | integer 0 to 65535 | no | At least this many connections. People searches only. Example: `500`. | | `title_any` | string | no | Any of these title phrases. Several values: a comma list or the parameter repeated. People searches only. Example: `cfo,chief financial officer`. | | `title_exact` | string | no | Exact job titles. Several values: a comma list or the parameter repeated. People searches only. Example: `head of growth`. | | `in_role_over_days` | integer 0 to 36500 | no | In the current role for more than this many days. People searches only. Example: `730`. | | `email_verified_within_days` | integer 0 to 3650 | no | Work email last checked within this many days. People searches only. Example: `30`. | | `has_direct_phone` | boolean | no | Has a direct phone number. People searches only. Example: `true`. | | `company_name` | string | no | Words in the company name. Example: `acme`. | | `company_city` | string | no | City the company is headquartered in. Several values: a comma list or the parameter repeated. Example: `Dallas`. | | `company_type` | string | no | Type of organisation. Several values: a comma list or the parameter repeated. One of: Privately Held, Public Company, Educational, Nonprofit, Government Agency, Partnership, Self-Owned, Self-Employed. Example: `Public Company`. | | `legal_type` | string | no | Legal form (corporation, limited, LLC). Example: `limited liability`. | | `naics` | string | no | NAICS industry code. Several values: a comma list or the parameter repeated. Example: `541511`. | | `sic` | string | no | SIC industry code. Several values: a comma list or the parameter repeated. Example: `7372`. | | `specialties` | string | no | A specialty the company lists. Example: `cold chain`. | | `company_description` | string | no | Words in the company description. Example: `freight`. | | `linkedin_employees_min` | integer 0 to 4294967295 | no | At least this many employee profiles. Example: `200`. | | `linkedin_employees_max` | integer 0 to 4294967295 | no | At most this many employee profiles. Example: `1000`. | | `revenue_min` | integer 0 to 4294967295 | no | Revenue band starts at or above (USD). Example: `10000000`. | | `revenue_max` | integer 0 to 4294967295 | no | Revenue band ends at or below (USD). Example: `100000000`. | | `locations_min` | integer 0 to 65535 | no | At least this many locations. Example: `3`. | | `funded_before` | string | no | Last funded on or before. Example: `2025-12-31`. | | `total_funding_min` | integer 0 to 9007199254740991 | no | Total funding at least (USD). Example: `5000000`. | | `total_funding_max` | integer 0 to 9007199254740991 | no | Total funding at most (USD). Example: `50000000`. | | `last_round_min` | integer 0 to 9007199254740991 | no | Last round at least (USD). Example: `2000000`. | | `investor` | string | no | Lead investor name. Example: `sequoia`. | | `traffic_max` | integer 0 to 4294967295 | no | Monthly web visits at most. Example: `100000`. | | `organic_traffic_min` | integer 0 to 4294967295 | no | Monthly organic visits at least. Example: `5000`. | | `paid_traffic_min` | integer 0 to 4294967295 | no | Monthly paid visits at least. Example: `1000`. | | `ad_spend_min` | integer 0 to 4294967295 | no | Monthly Google ad spend at least (USD). Example: `2000`. | | `sales_roles_min` | integer 0 to 4294967295 | no | At least this many people in sales roles at the company (a team-size signal). Example: `10`. | | `marketing_roles_min` | integer 0 to 4294967295 | no | At least this many people in marketing roles at the company (a team-size signal). Example: `10`. | | `engineering_roles_min` | integer 0 to 4294967295 | no | At least this many people in engineering roles at the company (a team-size signal). Example: `10`. | | `operations_roles_min` | integer 0 to 4294967295 | no | At least this many people in operations roles at the company (a team-size signal). Example: `10`. | | `it_roles_min` | integer 0 to 4294967295 | no | At least this many people in IT roles at the company (a team-size signal). Example: `10`. | | `devops_roles_min` | integer 0 to 4294967295 | no | At least this many people in DevOps roles at the company (a team-size signal). Example: `10`. | | `security_roles_min` | integer 0 to 4294967295 | no | At least this many people in security roles at the company (a team-size signal). Example: `10`. | | `customer_success_roles_min` | integer 0 to 4294967295 | no | At least this many people in customer success roles at the company (a team-size signal). Example: `10`. | | `business_development_roles_min` | integer 0 to 4294967295 | no | At least this many people in business development roles at the company (a team-size signal). Example: `10`. | | `grc_roles_min` | integer 0 to 4294967295 | no | At least this many people in governance and compliance roles at the company (a team-size signal). Example: `10`. | | `network_roles_min` | integer 0 to 4294967295 | no | At least this many people in network and infrastructure roles at the company (a team-size signal). Example: `10`. | | `account_executive_roles_min` | integer 0 to 4294967295 | no | At least this many people in account executive roles at the company (a team-size signal). Example: `10`. | | `demand_generation_roles_min` | integer 0 to 4294967295 | no | At least this many people in demand generation roles at the company (a team-size signal). Example: `10`. | | `uses_category` | string | no | Uses any tool in this category. Several values: a comma list or the parameter repeated. One of: crm, cloud, erp, cms, ecommerce, marketing_automation, analytics, sales_automation, abm, conversation_intelligence, development, application_security, cloud_security, email_security, email_hosting. Example: `crm`. | | `martech_category` | string | no | Marketing technology category. Example: `email`. | | `has_cio` | boolean | no | Company has a CIO. Example: `true`. | | `has_ciso` | boolean | no | Company has a CISO. Example: `true`. | | `has_mobile_app` | boolean | no | Company has a mobile app. Example: `true`. | | `has_web_app` | boolean | no | Company has a web app. Example: `true`. | | `app_downloads_min` | integer 0 to 4294967295 | no | Play Store downloads at least. Example: `100000`. | | `app_category` | string | no | Play Store app category. Example: `finance`. | | `exclude_country` | string | no | Not in these countries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/country. People searches only. Example: `India`. | | `exclude_state` | string | no | Not in these US states. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/state. People searches only. Example: `Texas`. | | `exclude_city` | string | no | Not in these cities. Several values: a comma list or the parameter repeated. People searches only. Example: `Austin`. | | `exclude_function` | string | no | Not in these departments. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/function. People searches only. Example: `Sales & Business Development`. | | `exclude_level` | string | no | Not at these levels. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/level. People searches only. Example: `staff`. | | `exclude_persona` | string | no | Not in these role groups. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/persona. People searches only. Example: `Sales Leadership`. | | `exclude_title` | string | no | Titles containing none of these words. Several values: a comma list or the parameter repeated. People searches only. Example: `intern,assistant`. | | `exclude_industry` | string | no | Not in these industries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/industry. Example: `Staffing and Recruiting`. | | `exclude_size` | string | no | Not these company sizes. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/company_size. Example: `1-10`. | | `exclude_company_name` | string | no | Company names containing none of these words. Several values: a comma list or the parameter repeated. Example: `staffing`. | | `limit` | integer 1 to 25 | no | How many to return, 1 to 25. Example: `10`. | | `cursor` | string | no | Pass the `next_cursor` from the last page to get the next page. A cursor works only with the same search; up to 40 pages (1,000 results) per search. Example: `eyJyIjoyMn0`. | | `total` | boolean | no | Wait for `total_matches` (how many match in all) even when it is slow. By default it is included when it is quick. Example: `False`. | | `count_only` | boolean | no | Return only the number of matches. Free: it uses no lookup and no credits. Example: `False`. | | `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": [ { "id": "per_4Hk2x9QmVb7LrTzE", "name": "Dana Whitfield", "title": "Director of IT", "company": "Mercy General", "company_domain": "mercy.org", "level": "director", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": false, "linkedin_url": "https://www.linkedin.com/in/dana-whitfield" }, { "id": "per_9Zt3cWn8KpD2yUaB", "name": "Luis Ortega", "title": "CIO", "company": "St. Anne Health", "company_domain": "stanne.org", "level": "c_suite", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": true, "linkedin_url": "https://www.linkedin.com/in/luis-ortega" } ], "total_matches": 18420, "next_cursor": "eyJyIjoyMn0", "interpreted_as": { "level": [ "director" ], "function": [ "Information Technology" ], "country": [ "United States" ], "company_size": [ "1001-5000" ] }, "credits_used": 10, "free_lookups_remaining": 9 } ``` ## GET /v1/search/count **Count matching people.** How many people match a search. Free: no lookup and no credits, only the rate limit applies. Use it to size a market, or to check that a search is neither empty nor huge before you page through it. Takes the same `q` and filters as `/search`. `interpreted_as` shows how the request was read. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `q` | string | no | Describe who to count in plain English, up to 300 characters. Any filter you also pass replaces what `q` says about the same thing; `interpreted_as` in the answer shows how it was read. Example: `IT directors at US hospitals with 1,000+ employees`. | | `title` | string | no | Job title or function, such as `head of sales` or `recruiter`. Seniority words (`VP`, `director`, `chief`) become a seniority filter and the other words must appear in the title. Example: `head of sales`. | | `seniority` | string | no | Seniority: `c_suite`, `founder`, `owner`, `vp`, `head`, `director` or `manager`. Several values: a comma list or the parameter repeated. Example: `vp`. | | `level` | string | no | Job level, finer than seniority: `c_suite`, `vp`, `director`, `manager`, `staff` or `other`. Several values: a comma list or the parameter repeated. Example: `director`. | | `function` | string | no | Department the person works in, such as `Sales & Business Development` or `Engineering`. See `GET /v1/facets/function`. Several values: a comma list or the parameter repeated. Example: `Sales & Business Development`. | | `persona` | string | no | A role group, such as `CEO / Founder` or `Sales Leadership`. See `GET /v1/facets/persona`. Several values: a comma list or the parameter repeated. Example: `CEO / Founder`. | | `company_domain` | string | no | Only people at these company websites (up to 50, comma list). Example: `acme.com`. | | `exclude_domains` | string | no | Leave out people at these company websites (up to 50, comma list). Example: `competitor.com`. | | `started_role_within_days` | integer 1 to 3650 | no | Only people who started their current role in the last N days: a buying signal. Example: `90`. | | `has_email` | boolean | no | Only people we have a work email for. `with_email` is the same and also returns it. Example: `False`. | | `has_mobile` | boolean | no | Only people we have a mobile number for. Example: `False`. | | `industry` | string | no | Industry, such as `Software Development` or `Hospitals and Health Care`. See `GET /v1/facets/industry`. Several values: a comma list or the parameter repeated. Example: `Software Development`. | | `country` | string | no | Country, such as `United States`. For a people search it is where the person is; for a company search, where the company is based. Several values: a comma list or the parameter repeated. Example: `United States`. | | `state` | string | no | US state, such as `Texas`. Implies the United States. Several values: a comma list or the parameter repeated. Example: `Texas`. | | `company_size` | string | no | Company headcount range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Several values: a comma list or the parameter repeated. Example: `51-200`. | | `employees_min` | integer 0 to 10000000 | no | Minimum company headcount. Matches the size ranges that lie wholly above it. Example: `200`. | | `employees_max` | integer 0 to 10000000 | no | Maximum company headcount. Matches the size ranges that lie wholly below it. Example: `1000`. | | `company_revenue` | string | no | Company revenue range: `<1M`, `1M-10M`, `10M-50M`, `50M-100M`, `100M-1B`, `1B+`. Several values: a comma list or the parameter repeated. Example: `10M-50M`. | | `uses` | string | no | Technologies the company runs, such as `hubspot` or `salesforce` or `aws`. A company must use all of them. See `GET /v1/facets/technology`. Several values: a comma list or the parameter repeated. Example: `hubspot`. | | `funding_stage` | string | no | The company's latest funding stage, such as `Series A`. See `GET /v1/facets/funding_stage`. Several values: a comma list or the parameter repeated. Example: `Series A`. | | `funded_since` | string | no | Only companies funded on or after this date. Example: `2026-01-01`. | | `growth_min` | integer -100 to 10000 | no | Minimum employee growth in percent over the last year, such as `20`. Example: `20`. | | `traffic_min` | integer 0 to | no | Minimum monthly website visits. Example: `10000`. | | `founded_after` | integer 1000 to 2100 | no | Founded in or after this year. Example: `2018`. | | `founded_before` | integer 1000 to 2100 | no | Founded in or before this year. Example: `2024`. | | `company_country` | string | no | Country the company is headquartered in (a people search; in a company search use `country`). Several values: a comma list or the parameter repeated. Example: `Germany`. | | `company_state` | string | no | US state the company is headquartered in (a people search). Several values: a comma list or the parameter repeated. Example: `Texas`. | | `city` | string | no | City the person is in. Several values: a comma list or the parameter repeated. People searches only. Example: `Austin`. | | `continent` | string | no | Continent the person is in. Several values: a comma list or the parameter repeated. One of: North America, Europe, Asia, South America, Africa, Oceania. People searches only. Example: `Europe`. | | `region` | string | no | Sales region the person is in. Several values: a comma list or the parameter repeated. One of: NORAM, EMEA, APAC, LATAM. People searches only. Example: `EMEA`. | | `skills` | string | no | Skill listed on the profile. People searches only. Example: `python`. | | `headline` | string | no | Words in the profile headline. People searches only. Example: `revenue operations`. | | `connections_min` | integer 0 to 65535 | no | At least this many connections. People searches only. Example: `500`. | | `title_any` | string | no | Any of these title phrases. Several values: a comma list or the parameter repeated. People searches only. Example: `cfo,chief financial officer`. | | `title_exact` | string | no | Exact job titles. Several values: a comma list or the parameter repeated. People searches only. Example: `head of growth`. | | `in_role_over_days` | integer 0 to 36500 | no | In the current role for more than this many days. People searches only. Example: `730`. | | `email_verified_within_days` | integer 0 to 3650 | no | Work email last checked within this many days. People searches only. Example: `30`. | | `has_direct_phone` | boolean | no | Has a direct phone number. People searches only. Example: `true`. | | `company_name` | string | no | Words in the company name. Example: `acme`. | | `company_city` | string | no | City the company is headquartered in. Several values: a comma list or the parameter repeated. Example: `Dallas`. | | `company_type` | string | no | Type of organisation. Several values: a comma list or the parameter repeated. One of: Privately Held, Public Company, Educational, Nonprofit, Government Agency, Partnership, Self-Owned, Self-Employed. Example: `Public Company`. | | `legal_type` | string | no | Legal form (corporation, limited, LLC). Example: `limited liability`. | | `naics` | string | no | NAICS industry code. Several values: a comma list or the parameter repeated. Example: `541511`. | | `sic` | string | no | SIC industry code. Several values: a comma list or the parameter repeated. Example: `7372`. | | `specialties` | string | no | A specialty the company lists. Example: `cold chain`. | | `company_description` | string | no | Words in the company description. Example: `freight`. | | `linkedin_employees_min` | integer 0 to 4294967295 | no | At least this many employee profiles. Example: `200`. | | `linkedin_employees_max` | integer 0 to 4294967295 | no | At most this many employee profiles. Example: `1000`. | | `revenue_min` | integer 0 to 4294967295 | no | Revenue band starts at or above (USD). Example: `10000000`. | | `revenue_max` | integer 0 to 4294967295 | no | Revenue band ends at or below (USD). Example: `100000000`. | | `locations_min` | integer 0 to 65535 | no | At least this many locations. Example: `3`. | | `funded_before` | string | no | Last funded on or before. Example: `2025-12-31`. | | `total_funding_min` | integer 0 to 9007199254740991 | no | Total funding at least (USD). Example: `5000000`. | | `total_funding_max` | integer 0 to 9007199254740991 | no | Total funding at most (USD). Example: `50000000`. | | `last_round_min` | integer 0 to 9007199254740991 | no | Last round at least (USD). Example: `2000000`. | | `investor` | string | no | Lead investor name. Example: `sequoia`. | | `traffic_max` | integer 0 to 4294967295 | no | Monthly web visits at most. Example: `100000`. | | `organic_traffic_min` | integer 0 to 4294967295 | no | Monthly organic visits at least. Example: `5000`. | | `paid_traffic_min` | integer 0 to 4294967295 | no | Monthly paid visits at least. Example: `1000`. | | `ad_spend_min` | integer 0 to 4294967295 | no | Monthly Google ad spend at least (USD). Example: `2000`. | | `sales_roles_min` | integer 0 to 4294967295 | no | At least this many people in sales roles at the company (a team-size signal). Example: `10`. | | `marketing_roles_min` | integer 0 to 4294967295 | no | At least this many people in marketing roles at the company (a team-size signal). Example: `10`. | | `engineering_roles_min` | integer 0 to 4294967295 | no | At least this many people in engineering roles at the company (a team-size signal). Example: `10`. | | `operations_roles_min` | integer 0 to 4294967295 | no | At least this many people in operations roles at the company (a team-size signal). Example: `10`. | | `it_roles_min` | integer 0 to 4294967295 | no | At least this many people in IT roles at the company (a team-size signal). Example: `10`. | | `devops_roles_min` | integer 0 to 4294967295 | no | At least this many people in DevOps roles at the company (a team-size signal). Example: `10`. | | `security_roles_min` | integer 0 to 4294967295 | no | At least this many people in security roles at the company (a team-size signal). Example: `10`. | | `customer_success_roles_min` | integer 0 to 4294967295 | no | At least this many people in customer success roles at the company (a team-size signal). Example: `10`. | | `business_development_roles_min` | integer 0 to 4294967295 | no | At least this many people in business development roles at the company (a team-size signal). Example: `10`. | | `grc_roles_min` | integer 0 to 4294967295 | no | At least this many people in governance and compliance roles at the company (a team-size signal). Example: `10`. | | `network_roles_min` | integer 0 to 4294967295 | no | At least this many people in network and infrastructure roles at the company (a team-size signal). Example: `10`. | | `account_executive_roles_min` | integer 0 to 4294967295 | no | At least this many people in account executive roles at the company (a team-size signal). Example: `10`. | | `demand_generation_roles_min` | integer 0 to 4294967295 | no | At least this many people in demand generation roles at the company (a team-size signal). Example: `10`. | | `uses_category` | string | no | Uses any tool in this category. Several values: a comma list or the parameter repeated. One of: crm, cloud, erp, cms, ecommerce, marketing_automation, analytics, sales_automation, abm, conversation_intelligence, development, application_security, cloud_security, email_security, email_hosting. Example: `crm`. | | `martech_category` | string | no | Marketing technology category. Example: `email`. | | `has_cio` | boolean | no | Company has a CIO. Example: `true`. | | `has_ciso` | boolean | no | Company has a CISO. Example: `true`. | | `has_mobile_app` | boolean | no | Company has a mobile app. Example: `true`. | | `has_web_app` | boolean | no | Company has a web app. Example: `true`. | | `app_downloads_min` | integer 0 to 4294967295 | no | Play Store downloads at least. Example: `100000`. | | `app_category` | string | no | Play Store app category. Example: `finance`. | | `exclude_country` | string | no | Not in these countries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/country. People searches only. Example: `India`. | | `exclude_state` | string | no | Not in these US states. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/state. People searches only. Example: `Texas`. | | `exclude_city` | string | no | Not in these cities. Several values: a comma list or the parameter repeated. People searches only. Example: `Austin`. | | `exclude_function` | string | no | Not in these departments. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/function. People searches only. Example: `Sales & Business Development`. | | `exclude_level` | string | no | Not at these levels. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/level. People searches only. Example: `staff`. | | `exclude_persona` | string | no | Not in these role groups. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/persona. People searches only. Example: `Sales Leadership`. | | `exclude_title` | string | no | Titles containing none of these words. Several values: a comma list or the parameter repeated. People searches only. Example: `intern,assistant`. | | `exclude_industry` | string | no | Not in these industries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/industry. Example: `Staffing and Recruiting`. | | `exclude_size` | string | no | Not these company sizes. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/company_size. Example: `1-10`. | | `exclude_company_name` | string | no | Company names containing none of these words. Several values: a comma list or the parameter repeated. Example: `staffing`. | ```bash curl "https://enrich.chat/v1/search/count?title=director&function=Information%20Technology&country=United%20States&company_size=1001-5000" ``` Response: ```json { "count": 18420, "interpreted_as": { "level": [ "director" ], "function": [ "Information Technology" ], "country": [ "United States" ], "company_size": [ "1001-5000" ] }, "credits_used": 0, "free_lookups_remaining": 10 } ``` ## GET /v1/company **Look up a company.** Company profile for a website, a LinkedIn company page or a `company_id`: name, industry, size band, revenue band, founding year, location, followers, funding, growth and traffic. Add `include=technologies` for the tech stack in the same call. Credits: 5 per profile found (technologies included); 0 when nothing is found. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `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 company page, like `linkedin.com/company/acme-logistics`. Example: `linkedin.com/company/acme-logistics`. | | `company_id` | string | no | The `id` of a company from a search result (starts with `org_`). Example: `org_7Qw2eRt5YuI9oPaS`. | | `include` | `technologies` | no | Extra data: `technologies`. Example: `technologies`. | ```bash curl "https://enrich.chat/v1/company?domain=acme.com" ``` Response: ```json { "found": true, "id": "org_7Qw2eRt5YuI9oPaS", "name": "Acme Logistics", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme-logistics", "industry": "Transportation, Logistics, Supply Chain and Storage", "size": "201-500", "employees_on_linkedin": 420, "city": "Dallas", "state": "Texas", "country": "United States", "website": "https://acme.com", "revenue": "10M-50M", "founded": 2009, "followers": 3100, "description": "Freight and warehousing for mid-size shippers.", "funding": { "stage": "Series A", "date": "2023-05-02" }, "employee_growth_pct": 12.5, "monthly_web_traffic": 38000, "credits_used": 5, "free_lookups_remaining": 9 } ``` ## 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), from the company's website. 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": 9 } ``` ## GET /v1/company/people **List people at a company.** Find people at one company by its website, optionally narrowed by `title`, `seniority`, `function` and the other people filters. Each person has an `id`: pass it as `person_id` to `/person` for contact details. Same results, paging and cost as `/search` restricted to the company. 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`. | | `q` | string | no | Describe who to find at the company in plain English, up to 300 characters. Any filter you also pass replaces what `q` says about the same thing; `interpreted_as` in the answer shows how it was read. Example: `head of sales`. | | `title` | string | no | Job title or function, such as `head of sales` or `recruiter`. Seniority words (`VP`, `director`, `chief`) become a seniority filter and the other words must appear in the title. Example: `head of sales`. | | `seniority` | string | no | Seniority: `c_suite`, `founder`, `owner`, `vp`, `head`, `director` or `manager`. Several values: a comma list or the parameter repeated. Example: `vp`. | | `level` | string | no | Job level, finer than seniority: `c_suite`, `vp`, `director`, `manager`, `staff` or `other`. Several values: a comma list or the parameter repeated. Example: `director`. | | `function` | string | no | Department the person works in, such as `Sales & Business Development` or `Engineering`. See `GET /v1/facets/function`. Several values: a comma list or the parameter repeated. Example: `Sales & Business Development`. | | `persona` | string | no | A role group, such as `CEO / Founder` or `Sales Leadership`. See `GET /v1/facets/persona`. Several values: a comma list or the parameter repeated. Example: `CEO / Founder`. | | `limit` | integer 1 to 25 | no | How many to return, 1 to 25. Example: `10`. | | `cursor` | string | no | Pass the `next_cursor` from the last page to get the next page. A cursor works only with the same search; up to 40 pages (1,000 results) per search. Example: `eyJyIjoyMn0`. | | `total` | boolean | no | Wait for `total_matches` (how many match in all) even when it is slow. By default it is included when it is quick. Example: `False`. | | `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": [ { "id": "per_4Hk2x9QmVb7LrTzE", "name": "Dana Whitfield", "title": "Director of IT", "company": "Mercy General", "company_domain": "mercy.org", "level": "director", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": false, "linkedin_url": "https://www.linkedin.com/in/dana-whitfield" }, { "id": "per_9Zt3cWn8KpD2yUaB", "name": "Luis Ortega", "title": "CIO", "company": "St. Anne Health", "company_domain": "stanne.org", "level": "c_suite", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": true, "linkedin_url": "https://www.linkedin.com/in/luis-ortega" } ], "total_matches": 41, "interpreted_as": { "company_domain": [ "mercy.org" ], "level": [ "director" ] }, "credits_used": 10, "free_lookups_remaining": 9 } ``` ## GET /v1/companies **Search for companies.** Find companies by industry, location, size, revenue, technology, funding, growth, traffic and founding year. Describe them in plain English with `q`, use filters, or both. Filters combine with AND; several values of one filter combine with OR. Names are matched leniently (`software development`, `Software_Development`) and a wrong value returns suggestions. Biggest LinkedIn following first. Companies come with the same `size` bands and `industry` values the people search uses, so a company list can feed a people search through `company_domain`. Searches by technology, growth, traffic or funding return one page (up to 25); narrow them to see others. Other searches page with `next_cursor` as `/search` does. One search that returns companies uses one free lookup. Credits: 5 per company returned; 0 when nothing is found. `count_only=true` or `/companies/count` is free. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `q` | string | no | Describe which companies in plain English, up to 300 characters. Any filter you also pass replaces what `q` says about the same thing; `interpreted_as` in the answer shows how it was read. Example: `Series A software companies in Texas using HubSpot`. | | `name` | string | no | Part of the company name. Example: `acme`. | | `industry` | string | no | Industry, such as `Software Development` or `Hospitals and Health Care`. See `GET /v1/facets/industry`. Several values: a comma list or the parameter repeated. Example: `Software Development`. | | `country` | string | no | Country, such as `United States`. For a people search it is where the person is; for a company search, where the company is based. Several values: a comma list or the parameter repeated. Example: `United States`. | | `state` | string | no | US state, such as `Texas`. Implies the United States. Several values: a comma list or the parameter repeated. Example: `Texas`. | | `company_size` | string | no | Company headcount range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Several values: a comma list or the parameter repeated. Example: `51-200`. | | `employees_min` | integer 0 to 10000000 | no | Minimum company headcount. Matches the size ranges that lie wholly above it. Example: `200`. | | `employees_max` | integer 0 to 10000000 | no | Maximum company headcount. Matches the size ranges that lie wholly below it. Example: `1000`. | | `company_revenue` | string | no | Company revenue range: `<1M`, `1M-10M`, `10M-50M`, `50M-100M`, `100M-1B`, `1B+`. Several values: a comma list or the parameter repeated. Example: `10M-50M`. | | `uses` | string | no | Technologies the company runs, such as `hubspot` or `salesforce` or `aws`. A company must use all of them. See `GET /v1/facets/technology`. Several values: a comma list or the parameter repeated. Example: `hubspot`. | | `funding_stage` | string | no | The company's latest funding stage, such as `Series A`. See `GET /v1/facets/funding_stage`. Several values: a comma list or the parameter repeated. Example: `Series A`. | | `funded_since` | string | no | Only companies funded on or after this date. Example: `2026-01-01`. | | `growth_min` | integer -100 to 10000 | no | Minimum employee growth in percent over the last year, such as `20`. Example: `20`. | | `traffic_min` | integer 0 to | no | Minimum monthly website visits. Example: `10000`. | | `founded_after` | integer 1000 to 2100 | no | Founded in or after this year. Example: `2018`. | | `founded_before` | integer 1000 to 2100 | no | Founded in or before this year. Example: `2024`. | | `company_name` | string | no | Words in the company name. Example: `acme`. | | `company_city` | string | no | City the company is headquartered in. Several values: a comma list or the parameter repeated. Example: `Dallas`. | | `company_type` | string | no | Type of organisation. Several values: a comma list or the parameter repeated. One of: Privately Held, Public Company, Educational, Nonprofit, Government Agency, Partnership, Self-Owned, Self-Employed. Example: `Public Company`. | | `legal_type` | string | no | Legal form (corporation, limited, LLC). Example: `limited liability`. | | `naics` | string | no | NAICS industry code. Several values: a comma list or the parameter repeated. Example: `541511`. | | `sic` | string | no | SIC industry code. Several values: a comma list or the parameter repeated. Example: `7372`. | | `specialties` | string | no | A specialty the company lists. Example: `cold chain`. | | `company_description` | string | no | Words in the company description. Example: `freight`. | | `linkedin_employees_min` | integer 0 to 4294967295 | no | At least this many employee profiles. Example: `200`. | | `linkedin_employees_max` | integer 0 to 4294967295 | no | At most this many employee profiles. Example: `1000`. | | `revenue_min` | integer 0 to 4294967295 | no | Revenue band starts at or above (USD). Example: `10000000`. | | `revenue_max` | integer 0 to 4294967295 | no | Revenue band ends at or below (USD). Example: `100000000`. | | `locations_min` | integer 0 to 65535 | no | At least this many locations. Example: `3`. | | `funded_before` | string | no | Last funded on or before. Example: `2025-12-31`. | | `total_funding_min` | integer 0 to 9007199254740991 | no | Total funding at least (USD). Example: `5000000`. | | `total_funding_max` | integer 0 to 9007199254740991 | no | Total funding at most (USD). Example: `50000000`. | | `last_round_min` | integer 0 to 9007199254740991 | no | Last round at least (USD). Example: `2000000`. | | `investor` | string | no | Lead investor name. Example: `sequoia`. | | `traffic_max` | integer 0 to 4294967295 | no | Monthly web visits at most. Example: `100000`. | | `organic_traffic_min` | integer 0 to 4294967295 | no | Monthly organic visits at least. Example: `5000`. | | `paid_traffic_min` | integer 0 to 4294967295 | no | Monthly paid visits at least. Example: `1000`. | | `ad_spend_min` | integer 0 to 4294967295 | no | Monthly Google ad spend at least (USD). Example: `2000`. | | `sales_roles_min` | integer 0 to 4294967295 | no | At least this many people in sales roles at the company (a team-size signal). Example: `10`. | | `marketing_roles_min` | integer 0 to 4294967295 | no | At least this many people in marketing roles at the company (a team-size signal). Example: `10`. | | `engineering_roles_min` | integer 0 to 4294967295 | no | At least this many people in engineering roles at the company (a team-size signal). Example: `10`. | | `operations_roles_min` | integer 0 to 4294967295 | no | At least this many people in operations roles at the company (a team-size signal). Example: `10`. | | `it_roles_min` | integer 0 to 4294967295 | no | At least this many people in IT roles at the company (a team-size signal). Example: `10`. | | `devops_roles_min` | integer 0 to 4294967295 | no | At least this many people in DevOps roles at the company (a team-size signal). Example: `10`. | | `security_roles_min` | integer 0 to 4294967295 | no | At least this many people in security roles at the company (a team-size signal). Example: `10`. | | `customer_success_roles_min` | integer 0 to 4294967295 | no | At least this many people in customer success roles at the company (a team-size signal). Example: `10`. | | `business_development_roles_min` | integer 0 to 4294967295 | no | At least this many people in business development roles at the company (a team-size signal). Example: `10`. | | `grc_roles_min` | integer 0 to 4294967295 | no | At least this many people in governance and compliance roles at the company (a team-size signal). Example: `10`. | | `network_roles_min` | integer 0 to 4294967295 | no | At least this many people in network and infrastructure roles at the company (a team-size signal). Example: `10`. | | `account_executive_roles_min` | integer 0 to 4294967295 | no | At least this many people in account executive roles at the company (a team-size signal). Example: `10`. | | `demand_generation_roles_min` | integer 0 to 4294967295 | no | At least this many people in demand generation roles at the company (a team-size signal). Example: `10`. | | `uses_category` | string | no | Uses any tool in this category. Several values: a comma list or the parameter repeated. One of: crm, cloud, erp, cms, ecommerce, marketing_automation, analytics, sales_automation, abm, conversation_intelligence, development, application_security, cloud_security, email_security, email_hosting. Example: `crm`. | | `martech_category` | string | no | Marketing technology category. Example: `email`. | | `has_cio` | boolean | no | Company has a CIO. Example: `true`. | | `has_ciso` | boolean | no | Company has a CISO. Example: `true`. | | `has_mobile_app` | boolean | no | Company has a mobile app. Example: `true`. | | `has_web_app` | boolean | no | Company has a web app. Example: `true`. | | `app_downloads_min` | integer 0 to 4294967295 | no | Play Store downloads at least. Example: `100000`. | | `app_category` | string | no | Play Store app category. Example: `finance`. | | `exclude_industry` | string | no | Not in these industries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/industry. Example: `Staffing and Recruiting`. | | `exclude_size` | string | no | Not these company sizes. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/company_size. Example: `1-10`. | | `exclude_company_name` | string | no | Company names containing none of these words. Several values: a comma list or the parameter repeated. Example: `staffing`. | | `limit` | integer 1 to 25 | no | How many to return, 1 to 25. Example: `10`. | | `cursor` | string | no | Pass the `next_cursor` from the last page to get the next page. A cursor works only with the same search; up to 40 pages (1,000 results) per search. Example: `eyJyIjoyMn0`. | | `total` | boolean | no | Wait for `total_matches` (how many match in all) even when it is slow. By default it is included when it is quick. Example: `False`. | | `count_only` | boolean | no | Return only the number of matches. Free: it uses no lookup and no credits. Example: `False`. | ```bash curl "https://enrich.chat/v1/companies?industry=Software%20Development&state=Texas&company_size=51-200&limit=5" ``` Response: ```json { "found": true, "count": 1, "companies": [ { "id": "org_7Qw2eRt5YuI9oPaS", "name": "Acme Logistics", "domain": "acme.com", "linkedin_url": "https://www.linkedin.com/company/acme-logistics", "industry": "Transportation, Logistics, Supply Chain and Storage", "size": "201-500", "employees_on_linkedin": 420, "city": "Dallas", "state": "Texas", "country": "United States" } ], "total_matches": 5210, "next_cursor": "eyJmbyI6M30", "interpreted_as": { "industry": [ "Software Development" ], "state": [ "Texas" ], "country": [ "United States" ] }, "credits_used": 5, "free_lookups_remaining": 9 } ``` ## GET /v1/companies/count **Count matching companies.** How many companies match a search. Free: no lookup and no credits. Takes the same `q` and filters as `/companies`. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `q` | string | no | Describe which companies in plain English, up to 300 characters. Any filter you also pass replaces what `q` says about the same thing; `interpreted_as` in the answer shows how it was read. Example: `Series A software companies in Texas`. | | `industry` | string | no | Industry, such as `Software Development` or `Hospitals and Health Care`. See `GET /v1/facets/industry`. Several values: a comma list or the parameter repeated. Example: `Software Development`. | | `country` | string | no | Country, such as `United States`. For a people search it is where the person is; for a company search, where the company is based. Several values: a comma list or the parameter repeated. Example: `United States`. | | `state` | string | no | US state, such as `Texas`. Implies the United States. Several values: a comma list or the parameter repeated. Example: `Texas`. | | `company_size` | string | no | Company headcount range: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Several values: a comma list or the parameter repeated. Example: `51-200`. | | `employees_min` | integer 0 to 10000000 | no | Minimum company headcount. Matches the size ranges that lie wholly above it. Example: `200`. | | `employees_max` | integer 0 to 10000000 | no | Maximum company headcount. Matches the size ranges that lie wholly below it. Example: `1000`. | | `company_revenue` | string | no | Company revenue range: `<1M`, `1M-10M`, `10M-50M`, `50M-100M`, `100M-1B`, `1B+`. Several values: a comma list or the parameter repeated. Example: `10M-50M`. | | `uses` | string | no | Technologies the company runs, such as `hubspot` or `salesforce` or `aws`. A company must use all of them. See `GET /v1/facets/technology`. Several values: a comma list or the parameter repeated. Example: `hubspot`. | | `funding_stage` | string | no | The company's latest funding stage, such as `Series A`. See `GET /v1/facets/funding_stage`. Several values: a comma list or the parameter repeated. Example: `Series A`. | | `funded_since` | string | no | Only companies funded on or after this date. Example: `2026-01-01`. | | `growth_min` | integer -100 to 10000 | no | Minimum employee growth in percent over the last year, such as `20`. Example: `20`. | | `traffic_min` | integer 0 to | no | Minimum monthly website visits. Example: `10000`. | | `founded_after` | integer 1000 to 2100 | no | Founded in or after this year. Example: `2018`. | | `founded_before` | integer 1000 to 2100 | no | Founded in or before this year. Example: `2024`. | | `company_name` | string | no | Words in the company name. Example: `acme`. | | `company_city` | string | no | City the company is headquartered in. Several values: a comma list or the parameter repeated. Example: `Dallas`. | | `company_type` | string | no | Type of organisation. Several values: a comma list or the parameter repeated. One of: Privately Held, Public Company, Educational, Nonprofit, Government Agency, Partnership, Self-Owned, Self-Employed. Example: `Public Company`. | | `legal_type` | string | no | Legal form (corporation, limited, LLC). Example: `limited liability`. | | `naics` | string | no | NAICS industry code. Several values: a comma list or the parameter repeated. Example: `541511`. | | `sic` | string | no | SIC industry code. Several values: a comma list or the parameter repeated. Example: `7372`. | | `specialties` | string | no | A specialty the company lists. Example: `cold chain`. | | `company_description` | string | no | Words in the company description. Example: `freight`. | | `linkedin_employees_min` | integer 0 to 4294967295 | no | At least this many employee profiles. Example: `200`. | | `linkedin_employees_max` | integer 0 to 4294967295 | no | At most this many employee profiles. Example: `1000`. | | `revenue_min` | integer 0 to 4294967295 | no | Revenue band starts at or above (USD). Example: `10000000`. | | `revenue_max` | integer 0 to 4294967295 | no | Revenue band ends at or below (USD). Example: `100000000`. | | `locations_min` | integer 0 to 65535 | no | At least this many locations. Example: `3`. | | `funded_before` | string | no | Last funded on or before. Example: `2025-12-31`. | | `total_funding_min` | integer 0 to 9007199254740991 | no | Total funding at least (USD). Example: `5000000`. | | `total_funding_max` | integer 0 to 9007199254740991 | no | Total funding at most (USD). Example: `50000000`. | | `last_round_min` | integer 0 to 9007199254740991 | no | Last round at least (USD). Example: `2000000`. | | `investor` | string | no | Lead investor name. Example: `sequoia`. | | `traffic_max` | integer 0 to 4294967295 | no | Monthly web visits at most. Example: `100000`. | | `organic_traffic_min` | integer 0 to 4294967295 | no | Monthly organic visits at least. Example: `5000`. | | `paid_traffic_min` | integer 0 to 4294967295 | no | Monthly paid visits at least. Example: `1000`. | | `ad_spend_min` | integer 0 to 4294967295 | no | Monthly Google ad spend at least (USD). Example: `2000`. | | `sales_roles_min` | integer 0 to 4294967295 | no | At least this many people in sales roles at the company (a team-size signal). Example: `10`. | | `marketing_roles_min` | integer 0 to 4294967295 | no | At least this many people in marketing roles at the company (a team-size signal). Example: `10`. | | `engineering_roles_min` | integer 0 to 4294967295 | no | At least this many people in engineering roles at the company (a team-size signal). Example: `10`. | | `operations_roles_min` | integer 0 to 4294967295 | no | At least this many people in operations roles at the company (a team-size signal). Example: `10`. | | `it_roles_min` | integer 0 to 4294967295 | no | At least this many people in IT roles at the company (a team-size signal). Example: `10`. | | `devops_roles_min` | integer 0 to 4294967295 | no | At least this many people in DevOps roles at the company (a team-size signal). Example: `10`. | | `security_roles_min` | integer 0 to 4294967295 | no | At least this many people in security roles at the company (a team-size signal). Example: `10`. | | `customer_success_roles_min` | integer 0 to 4294967295 | no | At least this many people in customer success roles at the company (a team-size signal). Example: `10`. | | `business_development_roles_min` | integer 0 to 4294967295 | no | At least this many people in business development roles at the company (a team-size signal). Example: `10`. | | `grc_roles_min` | integer 0 to 4294967295 | no | At least this many people in governance and compliance roles at the company (a team-size signal). Example: `10`. | | `network_roles_min` | integer 0 to 4294967295 | no | At least this many people in network and infrastructure roles at the company (a team-size signal). Example: `10`. | | `account_executive_roles_min` | integer 0 to 4294967295 | no | At least this many people in account executive roles at the company (a team-size signal). Example: `10`. | | `demand_generation_roles_min` | integer 0 to 4294967295 | no | At least this many people in demand generation roles at the company (a team-size signal). Example: `10`. | | `uses_category` | string | no | Uses any tool in this category. Several values: a comma list or the parameter repeated. One of: crm, cloud, erp, cms, ecommerce, marketing_automation, analytics, sales_automation, abm, conversation_intelligence, development, application_security, cloud_security, email_security, email_hosting. Example: `crm`. | | `martech_category` | string | no | Marketing technology category. Example: `email`. | | `has_cio` | boolean | no | Company has a CIO. Example: `true`. | | `has_ciso` | boolean | no | Company has a CISO. Example: `true`. | | `has_mobile_app` | boolean | no | Company has a mobile app. Example: `true`. | | `has_web_app` | boolean | no | Company has a web app. Example: `true`. | | `app_downloads_min` | integer 0 to 4294967295 | no | Play Store downloads at least. Example: `100000`. | | `app_category` | string | no | Play Store app category. Example: `finance`. | | `exclude_industry` | string | no | Not in these industries. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/industry. Example: `Staffing and Recruiting`. | | `exclude_size` | string | no | Not these company sizes. Several values: a comma list or the parameter repeated. Values: GET /v1/facets/company_size. Example: `1-10`. | | `exclude_company_name` | string | no | Company names containing none of these words. Several values: a comma list or the parameter repeated. Example: `staffing`. | ```bash curl "https://enrich.chat/v1/companies/count?industry=Software%20Development&state=Texas" ``` Response: ```json { "count": 5210, "interpreted_as": { "industry": [ "Software Development" ], "state": [ "Texas" ] }, "credits_used": 0, "free_lookups_remaining": 10 } ``` ## GET /v1/email-pattern **Find a company's email format.** The address formats a company uses (`first.last@`, `flast@` ...), most common first, with how common each is. Use it with a name to build a likely address, and confirm that address before relying on it. Needs at least a handful of known addresses at the company; otherwise `found: false`. Credits: 5 per company 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/email-pattern?domain=acme.com" ``` Response: ```json { "found": true, "domain": "acme.com", "patterns": [ { "pattern": "first.last@acme.com", "share": 0.82 }, { "pattern": "flast@acme.com", "share": 0.11 } ], "example": "jane.doe@acme.com", "sample_size": 46, "credits_used": 5, "free_lookups_remaining": 9 } ``` ## GET /v1/filters **List every filter.** Every filter a search takes, with its type, whether it applies to people searches only (`person`) or to company searches too (`company`), a plain label, an example, and the values it accepts when it has a fixed list. Free: no lookup, no credits. Pass any of them as a query parameter to `/search`, `/search/count`, `/companies` and `/companies/count`. A parameter that is not a filter is refused with `unknown_parameter` and suggestions. ```bash curl "https://enrich.chat/v1/filters" ``` Response: ```json { "count": 89, "filters": [ { "key": "skills", "type": "text", "scope": "person", "group": "Person", "label": "Skill listed on the profile", "example": "python" }, { "key": "revenue_min", "type": "int", "scope": "company", "group": "Company size", "label": "Revenue band starts at or above (USD)", "example": "10000000" } ], "note": "Pass any of these as a query parameter." } ``` ## GET /v1/facets **List the filter lists.** The names of the lists of values you can filter by. Free: no lookup, no credits. ```bash curl "https://enrich.chat/v1/facets" ``` Response: ```json { "facets": [ "industry", "country", "state", "function", "persona", "level", "company_size", "company_revenue", "funding_stage", "technology", "technology_category", "continent", "region", "company_type", "filters" ], "example": "https://enrich.chat/v1/facets/industry?q=software" } ``` ## GET /v1/facets/{facet} **List the values of a filter.** Every value a filter accepts, optionally narrowed by `q`. Use it to pick exact values for `industry`, `function`, `persona`, `country`, `state`, `funding_stage`, `company_size`, `company_revenue`, `level`, and for `uses`: `technology` (vendors, each with a category) and `technology_category`. Free: no lookup, no credits. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `facet` | `industry` or `country` or `state` or `function` or `persona` or `level` or `company_size` or `company_revenue` or `funding_stage` or `technology` or `technology_category` or `continent` or `region` or `company_type` or `filters` | yes | Which list. Example: `industry`. | | `q` | string | no | Only values containing this text. Example: `software`. | | `limit` | integer 1 to 200 | no | How many values, 1 to 200. Example: `50`. | | `offset` | integer 0 to | no | Skip this many values, to page through a long list (the answer gives `next_offset` while there is more). Example: `0`. | ```bash curl "https://enrich.chat/v1/facets/industry?q=software" ``` Response: ```json { "facet": "industry", "total": 3, "returned": 3, "values": [ "Software Development", "IT Services and IT Consulting", "Computer Software" ] } ``` ## POST /v1/batch **Run up to 25 lookups in one call.** Send up to 25 lookups in one `POST`. Each item is an object with `op` (`person`, `email`, `mobile`, `company`, `company_tech` or `email_pattern`), an optional `id` of your own, and the parameters that operation takes. Items run in order and each is billed exactly like its single call: a lookup that finds nothing is free. If the free limit or the rate limit is hit, the remaining items come back unrun with that error. The response status is 200 even when some items fail; read each item's `status`. Use it to enrich a list. Keep to about one call a second. Request body: ```json { "items": [ { "id": "a", "op": "email", "name": "Jane Doe", "domain": "acme.com" }, { "id": "b", "op": "email_pattern", "domain": "acme.com" } ] } ``` ```bash curl -X POST "https://enrich.chat/v1/batch" -H "content-type: application/json" -d '{"items":[{"id":"a","op":"email","name":"Jane Doe","domain":"acme.com"}]}' ``` Response: ```json { "count": 2, "credits_used": 15, "free_lookups_remaining": 8, "results": [ { "id": "a", "status": 200, "result": { "found": true, "work_email": { "value": "jane.doe@acme.com", "status": "verified" }, "credits_used": 10 } }, { "id": "b", "status": 200, "result": { "found": true, "domain": "acme.com", "patterns": [ { "pattern": "first.last@acme.com", "share": 0.82 } ], "credits_used": 5 } } ] } ``` ## POST /v1/search/cascade **Search with match tiers.** Give up to five searches, best fit first. Results come tier by tier, nobody twice, until `limit` (up to 100) is reached. Each person carries `tier`, `tier_name`, a `score` (100 for the first tier, 25 less for each later one, never below 10) and `matched`, the filters that tier used, so you can explain the ranking. A tier is written like a `/search` query: plain English in `q`, or any filter. With `count_only: true` it returns the count of each tier (free). Credits: 5 per person returned, like `/search`; 0 when nothing is found or for counts. Request body: ```json { "limit": 25, "tiers": [ { "name": "Exact", "q": "VPs of Sales at US software companies" }, { "name": "Close", "q": "directors of sales at US software companies" } ] } ``` ```bash curl -X POST "https://enrich.chat/v1/search/cascade" -H "content-type: application/json" -d '{"limit":25,"tiers":[{"q":"VPs of Sales at US software companies"},{"q":"directors of sales at US software companies"}]}' ``` Response: ```json { "found": true, "count": 2, "people": [ { "id": "per_4Hk2x9QmVb7LrTzE", "name": "Dana Whitfield", "title": "Director of IT", "company": "Mercy General", "company_domain": "mercy.org", "level": "director", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": false, "linkedin_url": "https://www.linkedin.com/in/dana-whitfield", "tier": 1, "tier_name": "Exact", "score": 100, "matched": { "level": [ "vp" ], "country": [ "United States" ] } }, { "id": "per_9Zt3cWn8KpD2yUaB", "name": "Luis Ortega", "title": "CIO", "company": "St. Anne Health", "company_domain": "stanne.org", "level": "c_suite", "function": "Information Technology", "persona": "IT", "country": "United States", "has_email": true, "has_mobile": true, "linkedin_url": "https://www.linkedin.com/in/luis-ortega", "tier": 2, "tier_name": "Close", "score": 75, "matched": { "level": [ "director" ], "country": [ "United States" ] } } ], "tiers": [ { "tier": 1, "name": "Exact", "returned": 1 }, { "tier": 2, "name": "Close", "returned": 1 } ], "credits_used": 10, "free_lookups_remaining": 9 } ``` ## POST /v1/jobs **Start a background job.** Run up to 5,000 lookups of one kind on the server. They carry on after you disconnect, and each row is billed exactly like its single call (a row that finds nothing is free). The response is `202` with a job `id`: poll `GET /jobs/{id}`, or add a webhook to be told when it finishes. Needs an API key, an OAuth token or a dashboard login, because a job belongs to an account. Up to three jobs run at once. Rows and results are kept for 30 days. `op` is `person`, `email`, `mobile`, `company`, `company_tech` or `email_pattern`; each item holds that operation's parameters plus an optional `id` that comes back with its result. `options` are parameters every row shares (for example `fields` or `include`). If the credits or free lookups run out the job stops with status `stopped` and the rest of the rows are `skipped`. Request body: ```json { "op": "email", "label": "Q4 list", "items": [ { "id": "a", "name": "Jane Doe", "domain": "acme.com" }, { "id": "b", "name": "Luis Ortega", "domain": "stanne.org" } ] } ``` ```bash curl -X POST "https://enrich.chat/v1/jobs" -H "Authorization: Bearer $ENRICH_KEY" -H "content-type: application/json" -d '{"op":"email","items":[{"id":"a","name":"Jane Doe","domain":"acme.com"}]}' ``` Response: ```json { "id": "job_2xYb9QwErTy8UiOp", "status": "queued", "total": 2, "status_url": "https://enrich.chat/v1/jobs/job_2xYb9QwErTy8UiOp" } ``` ## GET /v1/jobs **List your jobs.** Your last 50 jobs, newest first. ```bash curl "https://enrich.chat/v1/jobs" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "jobs": [ { "id": "job_2xYb9QwErTy8UiOp", "op": "email", "status": "done", "total": 2, "done": 2, "found": 1, "not_found": 1, "errors": 0, "credits_used": 10 } ] } ``` ## GET /v1/jobs/{job_id} **Check a job.** Status and counts: `queued`, `running`, `done`, `stopped` or `cancelled`, how many rows are done, found, not found or failed, and the credits used. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | yes | The job id. Example: `job_2xYb9QwErTy8UiOp`. | ```bash curl "https://enrich.chat/v1/jobs/job_2xYb9QwErTy8UiOp" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "id": "job_2xYb9QwErTy8UiOp", "op": "email", "status": "running", "total": 2000, "done": 840, "found": 611, "not_found": 229, "errors": 0, "credits_used": 6110 } ``` ## DELETE /v1/jobs/{job_id} **Delete a job.** Cancels the job if it is still running and deletes it with its results. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | yes | The job id. Example: `job_2xYb9QwErTy8UiOp`. | ```bash curl -X DELETE "https://enrich.chat/v1/jobs/job_2xYb9QwErTy8UiOp" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "ok": true } ``` ## GET /v1/jobs/{job_id}/results **Get a job's results.** JSON, 100 rows at a time (`offset`, `limit` up to 500), or `format=csv` for one file: your original columns when the job carried them, then `enrich_*` columns. Rows on your do-not-contact list have their contact columns left blank and are marked in `enrich_do_not_contact`. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | yes | The job id. Example: `job_2xYb9QwErTy8UiOp`. | | `format` | `json` or `csv` | no | `json` (default) or `csv`. Example: `csv`. | | `offset` | integer 0 to | no | Row to start from. Example: `0`. | | `limit` | integer 1 to 500 | no | Rows to return, 1 to 500. Example: `100`. | ```bash curl "https://enrich.chat/v1/jobs/job_2xYb9QwErTy8UiOp/results?format=csv" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "job": { "id": "job_2xYb9QwErTy8UiOp", "status": "done", "total": 2 }, "count": 2, "results": [ { "id": "a", "index": 0, "status": "done", "result": { "found": true, "work_email": { "value": "jane.doe@acme.com", "status": "verified" }, "credits_used": 10 } }, { "id": "b", "index": 1, "status": "done", "result": { "found": false, "credits_used": 0 } } ] } ``` ## POST /v1/jobs/{job_id}/cancel **Cancel a job.** Stops a queued or running job. Rows already done keep their results and their charge. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `job_id` | string | yes | The job id. Example: `job_2xYb9QwErTy8UiOp`. | ```bash curl -X POST "https://enrich.chat/v1/jobs/job_2xYb9QwErTy8UiOp/cancel" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "ok": true, "status": "cancelled" } ``` ## POST /v1/webhooks **Add a webhook.** A webhook is an https address that is told when a job finishes (`job.completed`) or stops early (`job.stopped`). The answer shows the signing secret once. Every delivery is a `POST` with the JSON event and these headers: `Enrich-Event`, `Enrich-Delivery`, and `Enrich-Signature: t=,v1=." using the secret>`. Check the signature and reject a `t` that is more than five minutes old. A delivery that does not get a `2xx` is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours; a webhook that fails ten deliveries in a row is switched off (turn it back on with `POST /webhooks/{id}/enable`). The address must be https on a public host name. Request body: ```json { "url": "https://example.com/hooks/enrich" } ``` ```bash curl -X POST "https://enrich.chat/v1/webhooks" -H "Authorization: Bearer $ENRICH_KEY" -H "content-type: application/json" -d '{"url":"https://example.com/hooks/enrich"}' ``` Response: ```json { "id": "whk_Q3wErTyUiOp9AsDf", "url": "https://example.com/hooks/enrich", "events": [ "job.completed", "job.stopped" ], "secret": "whsec_ExampleSecretShownOnlyOnce0123456" } ``` ## GET /v1/webhooks **List your webhooks.** Your webhooks, with the last delivery status. Secrets are never shown again. ```bash curl "https://enrich.chat/v1/webhooks" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "webhooks": [ { "id": "whk_Q3wErTyUiOp9AsDf", "url": "https://example.com/hooks/enrich", "events": [ "job.completed" ], "active": true, "last_status": 200, "consecutive_failures": 0 } ], "events": [ "job.completed", "job.stopped" ] } ``` ## DELETE /v1/webhooks/{webhook_id} **Delete a webhook.** Deletes the webhook and its delivery history. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `webhook_id` | string | yes | The webhook id. Example: `whk_Q3wErTyUiOp9AsDf`. | ```bash curl -X DELETE "https://enrich.chat/v1/webhooks/whk_Q3wErTyUiOp9AsDf" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "ok": true } ``` ## POST /v1/webhooks/{webhook_id}/test **Send a test delivery.** Sends a signed `webhook.test` event now and says whether your address answered `2xx`. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `webhook_id` | string | yes | The webhook id. Example: `whk_Q3wErTyUiOp9AsDf`. | ```bash curl -X POST "https://enrich.chat/v1/webhooks/whk_Q3wErTyUiOp9AsDf/test" -H "Authorization: Bearer $ENRICH_KEY" ``` Response: ```json { "delivered": true, "status": 200 } ``` ## 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`, `bad_input` | A parameter is missing or invalid. Fix it (the message, `fix` and `example` say how); do not retry unchanged. | | 400 | `unknown_filter_value` | A filter value we do not know. `did_you_mean` lists the closest ones; `GET /v1/facets/{name}` lists them all. | | 400 | `search_too_broad` | The request names nobody in particular. Add a role, an industry, a location or a company. | | 400 | `bad_cursor`, `result_limit` | The cursor does not belong to this search, or the search has been paged 40 times (1,000 results). Narrow the filters. | | 400 | `bad_id` | The `person_id` or `company_id` is not one we issued. Use an `id` from a search result. | | 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. |