Skip to main content
API quickstart

Elvesora Enrichment API Docs

Send a business domain through the REST API or authenticated remote MCP tool and receive company-level fields for CRM cleanup, segmentation, routing, and reporting.

Company-level profile

POST https://enrichment.elvesora.com/api/v1/enrichment/company Input: a business domain, optionally protected with an Idempotency-Key.
result_type: ENRICHED Map company_name, industry, headquarters, size, and website fields into the destination system.
Boundary: company data only No individual profiles, private contact records, or person-level attributes. Optional public company contact channels may be returned.

First request

Create a team token in Enrichment, then set ELVESORA_API_KEY in your shell. Replace the reserved example domain acme.example with a real business domain before sending this request. Send an Idempotency-Key header when retrying a request that should replay the cached result without another credit during the 24-hour cache window.

To verify a team API bearer token first, send GET https://enrichment.elvesora.com/api/v1/account with the same Authorization header. An active credential returns data.credential_status: active, data.product: company_enrichment, and data.api_version: v1. This credential check consumes no enrichment credit and returns X-Credits-Consumed: 0; it does not test company-data availability.

curl --request POST https://enrichment.elvesora.com/api/v1/enrichment/company \
  --header "Authorization: Bearer $ELVESORA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: enrich-acme-001' \
  --data '{"domain":"acme.example"}'

Success response

Illustrative response for a fictional company. The reserved acme.example domain and all values below are placeholders that show the field shape. Read result_type first and map only the fields actually returned for your domain.

{
  "success": true,
  "result_type": "ENRICHED",
  "message": "Company enrichment completed successfully",
  "data": {
    "company_name": "Acme Example",
    "legal_name": "Acme Example",
    "domain": "acme.example",
    "website_url": "https://acme.example",
    "industry": "Manufacturing",
    "sub_industry": "Industrial Equipment",
    "sector": "Industrials",
    "hq_city": "Chicago",
    "hq_region": "Illinois",
    "hq_country": "United States",
    "employee_count": 1200,
    "contacts": {
      "emails": ["info@acme.example"],
      "phones": []
    },
    "tech_stacks": [],
    "competitors": []
  },
  "credits": {
    "limit": 100,
    "used": 5,
    "remaining": 95,
    "consumed_by_request": 1,
    "period_started_at": "2026-06-01",
    "period_ends_at": "2026-07-01"
  },
  "remaining": 95,
  "limit": 100
}

Supported input formats

The API expects a domain. Bulk workflows can start from domains or business emails and normalize them before enrichment.

API request

Send domain as a string in the domain field, optionally with an Idempotency-Key header for replay protection during the 24-hour cache window.

MCP tool

Call enrich_company with a required domain and optional idempotency_key, after Elvesora sign-in or with a team API bearer token. Repeating the same domain through the same connection within 24 hours replays the stored result without another credit.

Signed-in dashboard

Enter one business domain or company email address. The dashboard extracts and normalizes the domain, then uses the team's active token and normal enrichment credit rules.

Bulk upload

Upload CSV, XLS, or XLSX files up to 10 MB with domains or business emails in the first column or a mapped domain_email, domain, or email header.

Business email

Bulk workflows can extract the domain portion from a business email before enrichment.

Result types

Use result_type as the durable routing value for enrichment jobs, exports, and retries.

result_type Meaning
ENRICHED Company data was returned for the submitted domain.
NOT_FOUND The domain was valid, but company data was not available.
PENDING Company enrichment is still pending. The REST API returns HTTP 400 with success=false and consumes no credit. When present, retry_after_seconds suggests how long to wait before another attempt; it does not guarantee completion. A PENDING answer is not stored for idempotent replay, so retry later with the same Idempotency-Key.
FREE_EMAIL_PROVIDER The input used a consumer email provider that does not identify a business domain.
DISPOSABLE The input domain matched a temporary or disposable domain pattern.
INVALID_EMAIL The submitted email format could not be parsed into a usable domain.
INVALID_DOMAIN The submitted domain format was invalid or unsupported.
LIMIT_EXCEEDED The plan allowance was exhausted before enrichment could run.
UNAUTHORIZED The bearer token was missing, invalid, or revoked.
VALIDATION_ERROR The request payload failed validation before enrichment could run.
IDEMPOTENCY_KEY_CONFLICT The same Idempotency-Key was previously used with a different domain.
UPSTREAM_ERROR The internal enrichment service returned an error response. Retry according to your workflow policy.
SERVICE_UNAVAILABLE The enrichment service could not be reached. Retry according to your workflow policy.

Company-field dictionary

Fields may be absent when a value is unavailable in an enrichment result. Build exports to handle blank values without failing the whole job.

Field Description
data.company_name Common company name returned for display and CRM account records.
data.legal_name Legal or registered name when available and different from the display name.
data.domain Business domain used for the enrichment result.
data.website_url Company website URL when available.
data.logo_url Company logo URL when available.
data.duns_number Dun & Bradstreet D-U-N-S number when available.
data.industry Primary industry category.
data.sub_industry More specific industry segment when available.
data.sector Broader sector classification when available.
data.lei_number Legal Entity Identifier when available.
data.employee_count Integer employee count when available.
data.founded_year Company founding year when available.
data.revenue_range Revenue range when available.
data.ipo_status Public-company IPO status when available.
data.stock_symbol Public-market ticker or stock symbol when available.
data.hq_city Headquarters city when available.
data.hq_region Headquarters state, province, or region when available.
data.hq_country Headquarters country when available.
data.sources Sources retained with the company enrichment evidence when available. An empty array means no sources were returned; it does not establish that every field was verified.
data.checked_at Timestamp recorded with the current enrichment evidence when available, or null when that evidence is absent. This is not a verification date for every company field.
data.social_links Public social or business profile links when available.
data.tags Company tags or classification labels when returned.
data.fundings Funding events, newest first, at most 20. Each has the published amount as a decimal string with its currency, a date with the precision of the source, deal_type, status, authority and source_url.
data.contacts Public company-level email addresses and phone numbers when returned; these are not person profiles or private contact records.
data.addresses Company address records, including headquarters address details when available.
data.tech_stacks Grouped company technology signals when returned.
data.competitors Company competitor records when returned.
data.brands Operating brands: primary is the main brand name or null when no single brand stands out; portfolio lists other top-level brands. The whole brands value is null until background research finishes. An object with primary null and an empty portfolio means no brands were found.
data.headcount_history Dated employee numbers in up to 8 series, each with its latest points (at most 10), and current, the dated observation behind employee_count. null until background research finishes; an empty series list means no published figures were found.
data.funding_trends Known rounds of new money and the amounts disclosed per calendar year and currency. Amounts are never summed across currencies, and the label states coverage, not a total raised. null while no round is stored and the research has not answered.
data.reported_revenue Revenue of the latest reported fiscal year in its own currency, as a decimal string with no FX conversion. null when no period is reported. revenue_range keeps its meaning in US dollars.
data.revenue_history Revenue by fiscal year in up to 8 series, each with its latest fiscal years (at most 10). A point can carry change with the amount and percent against the previous fiscal year. null until background research finishes; an empty series list means no published revenue was found.
data.hiring_signals Job postings on the company's official job board (Greenhouse, Lever or Ashby) at the last check: status, board, checked_at, observed_at, completeness, advertised_postings_count, up to 50 postings and changes since the previous complete reading. The count is postings on that board, not open positions or hires. null until the background check finishes.

Bulk upload and export workflow

Bulk enrichment works best when each row has one domain or business email, a predictable header, and a destination mapping before export.

Submitted pasted values or CSV, XLS, and XLSX rows are lowercased, normalized, deduplicated, and classified as valid or invalid while the list is created. Invalid rows remain visible as validation outcomes and do not consume enrichment credits; valid rows begin processing immediately.

List export downloads a 19-column XLSX workbook with nested company fields, result status, LinkedIn and social links, plus public company email addresses and phone numbers when returned. Primary Brand and Brand Portfolio columns contain returned operating brands and stay blank when no brand values are available.

Restart Processing retries unfinished rows and transient service or limit errors. It does not rerun successful, invalid, or NOT_FOUND rows; reimport a corrected domain or business email as a new row.

Lists can pause when credits run out. Check the paused_credits or pending_no_credits state before assuming a list failed for data-quality reasons.

Feature-gated Salesforce mapping

When the Salesforce integration flag and credentials are enabled for the deployment, exports support OAuth or client-credentials connections, dry-run planning, fill-only or replace writes, and before/after reconciliation exports for Account updates.

Teams can keep multiple named production or sandbox connections and select the destination connection. Mappings and run history remain separate for each connection.

The Salesforce mapping derives company_size_band from employee_count and routing_region from hq_country. Its data_freshness_date records the mapping date. These are connector values rather than fields in the REST response or a date when the source data was verified.

company_name Account Name or custom display-name field
legal_name Legal name custom field
domain / website_url Website or company-domain fields
industry / sub_industry / sector Industry and segmentation fields
employee_count / company_size_band Employee count or a size band derived from employee_count
hq_city / hq_region / hq_country Billing or headquarters location fields
routing_region Territory derived from hq_country
data_freshness_date Current mapping date

Operational events and developer assets

The app exposes implementation assets and operational signals for one-off calls and customer-scheduled REST workflows.

The signed-in API screen manages the team token, confirms that an active team token is present, downloads the OpenAPI YAML and Postman collection, and configures signed webhooks for list completion and low-credit events. This check does not send an enrichment request.

Copy the webhook signing secret when the endpoint is first created or explicitly rotated; it is displayed only once. If the secret is lost, rotate it from the API screen and update your receiver before the next delivery. Secret rotation immediately invalidates the previous signing secret.

List quality and restart

List detail pages calculate total, processed, pending, enriched, match_rate, result_counts, invalid_breakdown, failure_reasons, field_completeness, and suggested_actions. Restart Processing dispatches unfinished rows plus ERROR, LIMIT_EXCEEDED, RATE_LIMITED, SERVICE_UNAVAILABLE, and UPSTREAM_ERROR rows without rerunning successful or NOT_FOUND rows.

Signed webhooks

Teams can configure one public HTTPS endpoint on port 443 for list.completed and credits.low. X-Elvesora-Signature is sha256=<HMAC-SHA256 of the raw JSON body>. Delivery uses three total attempts: failed deliveries retry after 60 seconds and then after 300 seconds. credits.low fires once per billing period when remaining credits reach 10% or less.

Developer assets

The Enrichment app API screen exposes the OpenAPI YAML and Postman collection for the v1 enrichment API, including idempotency and credit examples.

Remote MCP

Remote MCP server

Ask an AI assistant or coding agent to enrich a domain you already have. The Enrichment MCP server runs the same enrichment as the REST API and returns the company fields and your remaining credits.

Server URL

https://enrichment.elvesora.com/api/mcp/enrichment

Accepts Streamable HTTP MCP requests. Sign in with your Elvesora account (OAuth) or send an Enrichment team API token as a bearer header.

Tool

enrich_company

domain is required, up to 255 characters. idempotency_key is optional. The result has result_type, message, company, credits and idempotency_status.

Company fields

company

Only these fields: company_name, legal_name, domain, website_url, logo_url, duns_number, industry, sub_industry, sector, lei_number, employee_count, founded_year, revenue_range, ipo_status, stock_symbol, hq_city, hq_region, hq_country, competitors, social_links, fundings, tech_stacks, tags, contacts, addresses, brands, headcount_history, funding_trends, reported_revenue, revenue_history and hiring_signals. No raw provider data and no sources.

Guides

file://elvesora/enrichment/mcp-guide.md

A Markdown guide that clients can read from the server, plus the embedded results resource at ui://elvesora/enrichment/results.

MCP shortens four sections of the REST profile: headcount_history keeps the last 3 points of each series, revenue_history the last 3 periods of each series, funding_trends the last 3 years, and hiring_signals up to 5 postings with title and url. The revenue change is yoy_percent in MCP and change.percent in REST. The latest hiring check time is last_check_at in MCP and checked_at in REST.

Connect your client

Use Elvesora sign-in in Claude and Codex, or a team API token in Claude Code. Enrichment has its own MCP server and its own connection, separate from Domain Lookup.

Elvesora sign-in · not checked yet

Claude

  1. In Claude, open Settings, then Connectors, and add a custom connector.
  2. Paste the server URL below and save.
  3. Connect, sign in with your Elvesora account and approve access for your current Enrichment team.
https://enrichment.elvesora.com/api/mcp/enrichment

Elvesora sign-in · not checked yet

Codex

Add the server to ~/.codex/config.toml, then sign in from the terminal. The browser opens the Elvesora approval screen; approve once and keep the terminal open until Codex confirms the login.

[mcp_servers.elvesora-enrichment]
url = "https://enrichment.elvesora.com/api/mcp/enrichment"
codex mcp login elvesora-enrichment

Team API token

Claude Code

Create a team API token in Enrichment under Integrations, then API. Keep it in an environment variable and send it as a bearer header. A token from another Elvesora product is refused.

claude mcp add --transport http elvesora-enrichment \
https://enrichment.elvesora.com/api/mcp/enrichment \
--header "Authorization: Bearer $ELVESORA_ENRICHMENT_TOKEN"

Team, reconnecting and disconnecting

The team comes only from the sign-in or the token, never from tool arguments, and every call uses that team's Enrichment credits. Signing in again with the same client and team keeps the working connection. Approving again after you move to another team replaces the earlier connection.

To remove access, open Enrichment, go to Integrations, then API, and select Disconnect under Connected applications. This ends that connection and all its tokens at once. For a team API token, select Regenerate API Key on the same screen; the old token stops working. In Codex, run codex mcp logout elvesora-enrichment and then codex mcp login elvesora-enrichment to sign in again.

Supported clients

Checked with Claude Code and a team API token. Elvesora sign-in from Claude and Codex is available but has not been checked against Enrichment yet. Other clients that support Streamable HTTP with OAuth sign-in or a bearer header may work with the same server URL, but they have not been checked by Elvesora yet.

Elvesora is not listed in the ChatGPT or Claude app directories. You add the server URL to your client yourself.

Connected clients may cache the server icon. If an older connector shows a generic icon, remove it and add it again.

Credits and repeated calls

Only an ENRICHED result uses one Enrichment credit. Connecting and listing tools are free. Repeating the same domain through the same connection within 24 hours returns the stored result with idempotency_status replayed and no new credit, even without an idempotency_key. Reusing an explicit idempotency_key for another domain returns idempotency_status conflict.

Find a domain, then enrich it

If you only have a company name, connect the Domain Lookup MCP server as well. In our Claude Code check, asking to find and enrich Stripe ran two steps: resolve_company_domain returned stripe.com with review_recommended false and used one Domain Lookup credit, then enrich_company returned Stripe with 8,500 employees in the United States and used one Enrichment credit.

When the lookup returns review_recommended true, the agent asks you to confirm the company first and does not enrich. Each product is connected and billed separately.

Product boundary

Elvesora Enrichment returns company-level data. It may include public company email addresses or phone numbers when they are included in enrichment data, but it does not return individual profiles, private contact lists, personal email discovery, or person-level attributes.

Credits

Credits are consumed by ENRICHED REST or MCP responses. Monitor credits.remaining, credits.consumed_by_request, and the X-Credits-* headers before starting large imports.

Troubleshooting

Check token status, domain formatting, free-provider inputs, disposable domains, CSV headers, usage limits, and failed jobs before retrying.