REST API overview

Base URL and routes

Use https://mcp.enricho.co. This reference describes REST, not the MCP transport or dashboard APIs. Authenticate with an API key and send JSON with Content-Type: application/json.

Method	Path	Reference
POST	/api/directory/people/search	Search people
POST	/api/directory/companies/search	Search companies
GET	/api/billing/usage	Account usage
GET	/api/billing/usage/history	Usage history
GET	/billing/plans	Public plans
POST	/api/billing/checkout/plan	Plan checkout
POST	/api/billing/checkout/credits	Credit checkout
GET	/api/billing/portal	Billing portal

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:

{
  "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. 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

Send filters with limit from 1–100 and no cursor. Omitted or 0 uses 20.
If result.has_more is true, resend the same filters with cursor set to result.next_cursor.
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:

{
  "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 first. Every public retry is a new retrieval; there is no public idempotency-key contract. No records are released when credit confirmation fails.

Essentials

Directory

Billing and usage

REST API overview

Base URL and routes

Response envelope

Preview and full search

Errors and retries

​Base URL and routes

​Response envelope

​Preview and full search

​Pagination

​Errors and retries

Base URL and routes

Response envelope

Preview and full search

Pagination

Errors and retries