The API contract

Four surfaces, one contract

Agent setup for the MCP server — endpoint, tools, client configuration — is on the MCP page.

Field catalogue

These are all of them. The list is a closed enum: a request naming anything else is rejected at the edge with a message saying what is valid, rather than returning a row with a silently missing column.

Defaults

A people request that names no fields resolves identity only: linkedin_url, title, seniority, department, location, company, company_domain, email. email is deliberately absent from that list — it is a different and far more expensive kind of work, and a default that quietly bought an address for every row would multiply the cost of a run several times over without the caller asking for anything.

A company request defaults to company, company_domain, location, country, headline. An explicit fields list always replaces the default rather than extending it.

Firmographics on a company row

The company entity carries these at no extra charge, so they come back with any company row and there is nothing to request: industry, employeeCount, employeeRange, foundedYear, logoUrl, revenueAnnualUsd, fundingTotalUsd, latestFundingRound, monthlyVisits.

Controlled vocabularies

Every address discovered by a run is put through a deliverability check and the outcome lands in emailStatus, so you can filter to the addresses that pass before anything reaches a sending tool. An address you supplied yourself is left exactly as given — we do not spend your credits checking data you already had and did not ask about.

Endpoints

Base URL /api/v1. Authenticate with Authorization: Bearer ek_live_… or x-api-key: ek_live_….

curl -s https://www.enrichments.io/api/v1/people/enrich \
  -H 'authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: 2f8c1b90-7f3a-4c21-9a4e-6f0f2b1d5e77' \
  -d '{
    "people": [
      { "name": "Ada Lovelace", "companyDomain": "example.com" }
    ],
    "fields": ["title", "seniority", "email"]
  }'

• A search accepts count from 1 to 100 and defaults to 25.
• An enrichment accepts up to 100 rows per call and returns one row per input, in input order.
• Small requests answer inline. Larger ones are queued and return a job id with results: null; poll GET /api/v1/jobs/{id} until the job is terminal. Polling is free.
• Send an Idempotency-Key header on any submission. For 24 hours the same key with the same payload replays the original response rather than running and charging again.

The full machine-readable contract — every request and response schema, in OpenAPI 3.1 — is at /api/v1/openapi. It needs no API key and it is generated from the schemas the routes parse with, so it cannot drift from the implementation.

Errors

Every failure is a JSON envelope carrying a type, a human-readable message and a request_id that is also returned as an X-Request-Id response header.

What gets charged

Credits are spent on delivered data only. An enrichment row is charged when at least one of the fields you asked for was resolved by us: a row that cannot be matched is free, a row that matches somebody but adds none of the requested fields is free, and an identifier you supplied that comes back unchanged was never a resolved field. A search is charged per record returned, because there the identity is the delivered unit.

Per-unit prices, plan allowances and the mechanism behind the rule are on pricing.

Boundaries

• Mobile numbers are available as the `phone` field and billed per number found. 15 common aliases — mobile, cell, direct dial, telephone and the rest — resolve to it rather than failing. Unlike an email address a number carries no deliverability verdict, because nothing checks a phone the way a mailbox can be checked.
• A phone number being available is not advice that it is lawful to call. Obligations under TCPA, DNC registries and local consent rules are the caller's.
• The field catalogue is closed. A request for anything outside the 12 people fields is a validation error, not an empty column.
• Email addresses are work addresses found from public sources. Personal contact details are not part of the catalogue.
• Enrichment is live rather than a licensed static database, so the same query can legitimately return different data tomorrow.

Questions

What fields does the Enrichments API return?

People records can carry email, linkedin_url, title, seniority, department, location, country, company, company_domain, headline, phone, company_profile. Company records can carry company, company_domain, linkedin_url, location, country, headline, plus firmographics that ride along with any company row: industry, employeeCount, employeeRange, foundedYear, logoUrl, revenueAnnualUsd, fundingTotalUsd, latestFundingRound, monthlyVisits. Requesting anything outside those lists is a validation error rather than an empty column.

How is the API authenticated?

With an organization-scoped API key, sent as an Authorization: Bearer header or as x-api-key. Keys carry scopes, are shown in full exactly once at creation, and can be revoked or rotated at any time.

Is there an OpenAPI document?

Yes, at https://www.enrichments.io/api/v1/openapi, and no API key is needed to read it. It is OpenAPI 3.1 and is generated from the same schemas the routes validate requests with, so it cannot describe an API that is not served.

How are retries handled?

Send an Idempotency-Key header. The same key with the same payload replays the original response for 24 hours instead of running and charging again; the same key with a different payload is refused with a 422.