> ## Documentation Index > Fetch the complete documentation index at: https://docs.enricho.co/llms.txt > Use this file to discover all available pages before exploring further. # Search companies > Free company previews or full records at one credit per returned company. All filters are optional. Different fields combine with AND; list values combine with OR. List filters accept a string or up to 100 strings, each limited to 200 UTF-8 bytes. An empty object is an unfiltered paid full search. ## Preview ```bash theme={null} curl -X POST 'https://mcp.enricho.co/api/directory/companies/search' \ -H 'Authorization: Bearer enr_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"country_code":"GB","industry":"software","preview":true}' ``` Returns up to 10 summaries for 0 credits: `company_id`, `name`, `domain`, `industry`, `country`, `country_code`, `employee_size_band`. Domain is intentionally included, but contact/address/website/social fields are not. `limit` and `cursor` are ignored. `next_cursor` is empty; `has_more` only indicates additional matches, not a count. Any nonempty `exclude_company_ids` list returns 422 in preview. [Daily preview caps](https://docs.enricho.co/api-reference/overview.md) apply. ## Full search and continuation ```bash theme={null} curl -X POST 'https://mcp.enricho.co/api/directory/companies/search' \ -H 'Authorization: Bearer enr_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"domain":"example.com","preview":false,"limit":5}' ``` Only continue if the previous full page reports `has_more: true`; replace the cursor with its `next_cursor`: ```bash theme={null} curl -X POST 'https://mcp.enricho.co/api/directory/companies/search' \ -H 'Authorization: Bearer enr_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"domain":"example.com","limit":5,"cursor":"NEXT_CURSOR_FROM_PREVIOUS_RESPONSE"}' ``` To retrieve previewed companies directly, pass their IDs in `company_id` with `preview: false`. Full pages default to 20 records (also when limit is 0); explicit sizes are 1–100. Every returned company costs 1 credit, including repeats; empty pages cost 0. A page that cannot be funded in full returns 402 with no records and no debit. See [pagination, errors and retry precautions](https://docs.enricho.co/api-reference/overview.md). ## Matching * `company_id`: exact, case-sensitive IDs. `exclude_company_ids`: exclude up to 100 IDs in full mode. * `name`, `industry`: case-insensitive substrings. * `domain`: exact lowercase domain without URL scheme, path or leading `www.`. * `country_code`: headquarters country, uppercased. * `employee_size_band`: stored labels such as `51-200`, not numeric range comparisons. * `query`: all retained terms must match name, domain, website, industry, headquarters country or address. Up to 10 distinct lowercased terms are retained after splitting on whitespace, commas and semicolons and removing common stop words. Input is limited to 200 UTF-8 bytes; it is not Boolean query syntax. ## Full record fields `company_id`, `name`, `domain`, `website`, `industry`, `country`, `country_code`, `address`, `phone`, `employee_size_band`, `employee_count_min`, `employee_count_max`, `linkedin_url`, `x_url`, `facebook_url`, `extras`, `updated_at`. Empty strings are `""`, unavailable employee counts are `null`, and `extras` is `{}` when absent. Extra attributes are string-valued and record-dependent. The update timestamp does not guarantee contact verification. No public total-count fields are returned. ## OpenAPI ````yaml api-reference/openapi.json POST /api/directory/companies/search openapi: 3.1.0 info: title: Enricho Public REST API version: 1.0.0 description: >- Public directory search and billing APIs. Full search costs 1 credit per returned record; previews and usage calls use no credits. Request and response contracts reflect the current public gateway and service handlers. servers: - url: https://mcp.enricho.co security: - apiKey: [] - headerKey: [] tags: - name: Directory - name: Billing paths: /api/directory/companies/search: post: tags: - Directory summary: Search companies description: >- All filters are optional. Full searches cost 1 credit per returned record, not per page; no matches use 0 credits. Each retrieval, including repeats and continuation pages, is charged again. A page is released only after an atomic full-page debit is confirmed. On an unconfirmed charge (503), no records are returned; check GET /api/billing/usage before retrying. Preview returns at most 10 records for free, ignores limit/cursor and is capped per user per UTC day. Public searches do not return total counts. operationId: searchCompanies requestBody: required: false description: 'Send JSON with Content-Type: application/json.' content: application/json: schema: $ref: '#/components/schemas/SearchCompaniesRequest' examples: preview: summary: Free preview value: country_code: GB industry: software preview: true full: summary: Full paid page value: domain: example.com limit: 5 responses: '200': description: Success envelope. content: application/json: schema: type: object properties: success: type: boolean const: true result: anyOf: - $ref: '#/components/schemas/CompaniesPage' - $ref: '#/components/schemas/CompaniesPreviewPage' message: type: string required: - success - result - message '400': description: >- bad_request: malformed JSON, invalid full-search limit, or cursor invalid / from different filters. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 'unauthorized: missing, invalid or revoked API key.' content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- insufficient_credits: insufficient balance for the entire page. No records returned and no credits deducted; reduce limit or buy credits. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- validation_failed: unknown field, wrong type, excessive list/value length or disallowed preview exclusions. query_too_broad: narrow the search and retry. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- rate_limited: key, account or IP request limit exceeded; wait a minute before retrying. Preview daily caps also return this status; wait until midnight UTC or use a paid full search. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: 'internal: unexpected server failure.' content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: 'upstream_unavailable: gateway could not reach the service.' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- upstream_unavailable: authentication, directory, preview counter or billing dependency unavailable. An unconfirmed full-search charge returns no records but may already have debited credits; inspect usage before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SearchCompaniesRequest: type: object additionalProperties: false properties: company_id: description: >- Exact company IDs, case-sensitive. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 name: description: >- Case-insensitive company-name substring matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 domain: description: >- Exact company domains, lowercased; URL schemes, paths and leading www. are removed. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 industry: description: >- Case-insensitive industry substring matches. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 country_code: description: >- Headquarters country codes, uppercased (for example GB or US). Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 employee_size_band: description: >- Stored employee-size band (for example 1-10 or 51-200), not a numeric range comparison. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 exclude_company_ids: description: >- Exclude exact company IDs. Only available in full searches; any nonempty list is rejected in preview. Accepts a single string or up to 100 strings; each value is limited to 200 UTF-8 bytes before normalization. oneOf: - type: string maxLength: 200 - type: array maxItems: 100 items: type: string maxLength: 200 query: type: string maxLength: 200 description: >- Free text, limited to 200 UTF-8 bytes. Up to 10 distinct lowercased terms after splitting on whitespace, commas and semicolons and removing common stop words. Every retained term must match a searchable text field; this is not a Boolean query language. preview: type: boolean default: false description: >- true returns a free first-page preview of up to 10 records. limit and cursor are ignored; previews cannot be paginated. false returns full records at 1 credit each. limit: type: integer minimum: 0 maximum: 100 default: 20 description: >- Full search page size, 1–100. Omitted or 0 uses 20. Negative values or values above 100 return 400. Ignored in preview. cursor: type: string default: '' description: >- Opaque next_cursor from a previous full search with the same filters. Omit or use an empty string for the first page. Ignored in preview. description: >- All fields are optional; {} searches without filters. Different filter fields combine with AND; multiple values in a filter combine with OR. Record-ID exclusions are full-search only. CompaniesPage: type: object properties: results: type: array items: $ref: '#/components/schemas/Company' maxItems: 100 next_cursor: type: string description: Opaque continuation token; empty when no next page is available. has_more: type: boolean description: Whether a continuation page is available. credits_used: type: integer minimum: 0 maximum: 100 description: 1 per returned record; 0 for an empty page. required: - results - next_cursor - has_more - credits_used description: No total_estimate or total_capped fields are returned by public search. CompaniesPreviewPage: type: object properties: results: type: array items: $ref: '#/components/schemas/CompanyPreview' maxItems: 10 next_cursor: type: string description: Always empty; previews cannot be paginated. has_more: type: boolean description: More matches exist beyond the preview; not a total count. credits_used: type: integer minimum: 0 const: 0 description: Always 0. required: - results - next_cursor - has_more - credits_used description: No total_estimate or total_capped fields are returned by public search. Error: type: object properties: success: type: boolean const: false result: type: object properties: code: type: string description: Machine-readable error code. required: - code message: type: string description: Human-readable error; do not parse this as a stable identifier. required: - success - result - message Company: type: object properties: company_id: type: string name: type: string domain: type: string website: type: string industry: type: string country: type: string country_code: type: string address: type: string phone: type: string employee_size_band: type: string employee_count_min: type: - integer - 'null' format: int32 employee_count_max: type: - integer - 'null' format: int32 linkedin_url: type: string x_url: type: string facebook_url: type: string extras: type: object additionalProperties: type: string description: >- Additional record attributes as string key/value pairs. Keys vary by record; do not rely on a fixed set. updated_at: type: string format: date-time required: - company_id - name - domain - website - industry - country - country_code - address - phone - employee_size_band - employee_count_min - employee_count_max - linkedin_url - x_url - facebook_url - extras - updated_at description: >- Full record. Field availability varies: absent text is an empty string, nullable numbers are null, arrays may be empty, and extras is {} when unavailable. updated_at is the record update timestamp, not a verification guarantee. CompanyPreview: type: object properties: company_id: type: string name: type: string domain: type: string industry: type: string country: type: string country_code: type: string employee_size_band: type: string required: - company_id - name - domain - industry - country - country_code - employee_size_band description: >- Company identity, domain, industry, location and employee-size band; no contact or social fields. securitySchemes: apiKey: type: http scheme: bearer description: Enricho API key (enr_...) headerKey: type: apiKey in: header name: X-Api-Key description: >- An Enricho API key (enr_...). Use this or Authorization: Bearer, not both. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.