> ## 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.

# REST API overview

> Public directory search and billing contracts, costs, pagination and errors.

## Base URL and routes

Use **[https://mcp.enricho.co](https://mcp.enricho.co)**. This reference describes REST, not the MCP transport or dashboard APIs. [Authenticate with an API key](https://docs.enricho.co/api-reference/authentication.md) and send JSON with `Content-Type: application/json`.

| Method | Path | Reference |
| - | - | - |
| POST | /api/directory/people/search | [Search people](https://docs.enricho.co/api-reference/search-people.md) |
| POST | /api/directory/companies/search | [Search companies](https://docs.enricho.co/api-reference/search-companies.md) |
| GET | /api/billing/usage | [Account usage](https://docs.enricho.co/api-reference/usage.md) |
| GET | /api/billing/usage/history | [Usage history](https://docs.enricho.co/api-reference/usage-history.md) |
| GET | /billing/plans | [Public plans](https://docs.enricho.co/api-reference/plans.md) |
| POST | /api/billing/checkout/plan | [Plan checkout](https://docs.enricho.co/api-reference/checkout-plan.md) |
| POST | /api/billing/checkout/credits | [Credit checkout](https://docs.enricho.co/api-reference/checkout-credits.md) |
| GET | /api/billing/portal | [Billing portal](https://docs.enricho.co/api-reference/portal.md) |

The plan list needs no authentication. All example data is synthetic and all credential/ID placeholders must be replaced locally.

## Response envelope

Responses use the actual HTTP status and `{success, result, message}`. Search records are in `result.results`, not a top-level array. Empty results are a successful response, not a 404:

```json theme={null}
{
  "success": true,
  "result": {
    "results": [],
    "next_cursor": "",
    "has_more": false,
    "credits_used": 0
  },
  "message": "No people match these filters."
}
```

## Preview and full search

| Behavior | Preview (preview: true) | Full (false or omitted) |
| - | - | - |
| Credits | 0 | 1 per returned record |
| Records | Up to 10 | Up to 100 per page; default 20 |
| Fields | Identity/professional summary | All available public record fields |
| Pagination | None; limit and cursor ignored | Opaque cursor |
| ID exclusions | Rejected when nonempty | Up to 100 per list |
| Person employer-domain exclusions | Up to 10 | Up to 100 |
| Total match count | Not returned | Not returned |

Each full retrieval costs credits again, including repeats and continuation pages. A 20-record page costs 20 credits; an empty page costs 0. Pages are prepared before an atomic full-page debit and released only after confirmation. Insufficient balance returns 402 with no records and no credits deducted; reduce `limit` or [buy credits](https://docs.enricho.co/api-reference/checkout-credits.md).

Free previews share a per-user daily allowance across person/company searches and keys. Even an empty preview consumes an attempt. Default allowances are Free 100, Pro 1,000, Growth 5,000, Scale 20,000 and Enterprise 20,000 per UTC day; deployment settings can change them. Unknown plans use the Free cap; if the plan cannot be retrieved, previews also use the Free cap. If preview counting is unavailable, previews fail closed with 503 rather than silently becoming unlimited. On a daily-cap 429, wait until midnight UTC or use a paid full search. Plan changes can take up to five minutes to affect the preview allowance.

## Pagination

1. Send filters with `limit` from 1–100 and no cursor. Omitted or 0 uses 20.
2. If `result.has_more` is true, resend the same filters with `cursor` set to `result.next_cursor`.
3. Stop when `has_more` is false. The final `next_cursor` is empty.

Keep filter values and array order unchanged; page size can change. Cursors are scoped to normalized filters, not a fixed dataset snapshot. Treat them as opaque. There is no offset/page-number pagination. Public searches return neither `total_estimate` nor `total_capped`.

Previews always return an empty cursor. For full retrieval, use the preview's IDs or repeat its filters with `preview: false`.

## Errors and retries

Errors contain `success: false`, `result.code` and a human-readable `message`. Branch on status and code, not exact message text. Illustrative error:

```json theme={null}
{
  "success": false,
  "result": { "code": "insufficient_credits" },
  "message": "Insufficient credits for all records. No credits were deducted."
}
```

| HTTP | Code | Action |
| - | - | - |
| 400 | bad\_request | Fix JSON, full-search limit or invalid/filter-mismatched cursor. |
| 401 | unauthorized | Supply an active API key. |
| 402 | insufficient\_credits | Reduce page size or add credits. |
| 404 | not\_found | Check the route; the portal may have no self-serve customer. |
| 409 | validation\_failed | Requested plan is already active. |
| 413 | payload\_too\_large | Reduce the request body. |
| 422 | validation\_failed | Fix unknown fields, types, list sizes, profile URL or preview exclusions. |
| 422 | query\_too\_broad | Narrow the search with a country, company or job title. |
| 429 | rate\_limited | Wait a minute for request limits, or midnight UTC for preview limits. |
| 500 | internal | Unexpected server failure. |
| 502, 503 | upstream\_unavailable | Service, authentication or payment dependency unavailable. |

Do not blindly retry paid search after a timeout, lost response or unconfirmed-charge 503: a debit may already have completed. [Check usage](https://docs.enricho.co/api-reference/usage.md) first. Every public retry is a new retrieval; there is no public idempotency-key contract. No records are released when credit confirmation fails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.