Skip to main content
API quickstart

Company Domain Lookup API Docs

Send a company name to the lookup API and receive a likely official website domain with confidence, match reasons, and usage fields for customer data workflows.

Lookup contract

POST /api/prospecting/company Input: company_name plus optional disambiguating context.
https://prospecting.elvesora.com/api Public API base URL. Use a bearer token for the lookup and authenticated health check.
domain + confidence + reasons[] Output fields are designed for automation, review queues, and CRM mapping.
found: false · confidence: 0 Completed no-match outcomes keep the domain blank. Errors include no confidence score.

First request

Create a team token in Domain Lookup, then set ELVESORA_API_KEY in your shell. Replace the fictional company below with the name you want to look up. Send requests from your backend and keep the token out of browser and mobile client code.

curl --request POST https://prospecting.elvesora.com/api/prospecting/company \
  --header "Authorization: Bearer $ELVESORA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'X-Request-Id: crm-import-2026-07-12' \
  --data '{"company_name":"North Mill Equipment","additional_context":"Industrial equipment manufacturer"}'

Success response

Illustrative response for a fictional company. Read found and confidence before saving the suggested domain. Supporting reasons depend on the actual match.

{
  "success": true,
  "message": "Company lookup completed",
  "company_name": "North Mill Equipment",
  "normalized_company_name": "north mill equipment",
  "domain": "northmill.example",
  "linkedin_url": null,
  "industry": "Industrial Machinery",
  "sub_industry": "Industrial Equipment",
  "sector": "Industrials",
  "confidence": 92,
  "confidence_band": "high",
  "review_recommended": false,
  "is_live": null,
  "reasons": ["Company name matches website brand"],
  "lower_reasons": [],
  "cached": false,
  "found": true,
  "remaining": 1249,
  "limit": 1250
}

REST request and response fields

The endpoint is designed for company identity resolution. It does not check domain ownership records or whether a domain can be purchased.

Request field Description
company_name Required: Yes Company, brand, or organization name to resolve to a likely official website domain. Required string, maximum 255 characters.
additional_context Required: No Short context that can help disambiguate similar company names, such as country, industry, or known product line. Optional string, maximum 2,000 characters. It is stored in request logs and sent to the lookup provider. Send company facts only, without secrets or personal data.
Response field Description
success True for completed found or no-match outcomes. Service and upstream error envelopes set it to false; authentication and validation errors may omit it. Error responses do not include a confidence score.
found Boolean indicating whether a domain was returned.
company_name Company name used in the returned match.
normalized_company_name Normalized version of the company name when available.
domain Likely official website domain, or null when no confident match is found.
linkedin_url Nullable company LinkedIn URL when the lookup provider returns one.
industry Nullable primary industry classification when available.
sub_industry Nullable more-specific industry classification when available.
sector Nullable broad company sector classification when available.
confidence Required ordinal routing score for completed lookups: 1-100 when found is true and 0 when found is false. It is not a calibrated probability. Error responses do not include confidence.
confidence_band Derived routing band for completed outcomes: high at 85-100, review at 60-84, low at 1-59, or no_match at 0. Error responses omit this field.
review_recommended Boolean routing guidance for completed outcomes. False only for the high band; true for review, low, and no_match. Error responses omit this field.
is_live Nullable boolean indicating whether the returned domain appeared reachable when evaluated.
reasons[] Positive match reasons that support the returned domain.
lower_reasons[] Signals that lowered confidence or require review.
cached Boolean indicating whether the lookup reused a cached upstream result. Check this before treating is_live reachability as fresh.
remaining / limit Usage fields showing remaining lookup allowance and plan limit after the request.
error_type Typed error identifier. Local plan exhaustion returns usage_limit; provider throttling returns rate_limited; a strict upstream response failure returns lookup_invalid_response; a terminal provider failure returns lookup_provider_unavailable. Error responses omit domain, found, and confidence.
retryable / retry_after Follow retryable before scheduling another attempt. Do not automatically retry when retryable is false, including a 503 lookup_provider_unavailable. Provider rate_limited responses are retryable with retry_after from 1 to 300 seconds. A 502 lookup_invalid_response returns retryable true and retry_after 60.

Remote MCP

Remote MCP server

Ask an AI assistant or coding agent for a company's website. The Domain Lookup MCP server runs the same lookup as the REST API, with the same credits and the same confidence bands, and tells the agent when to ask you before using a domain.

Server URL

https://prospecting.elvesora.com/api/mcp/domain-lookup

Streamable HTTP. Sign in with your Elvesora account (OAuth) or send a Domain Lookup team API token as a bearer header.

Tool

resolve_company_domain

company_name is required, up to 255 characters. additional_context is optional, up to 2,000 characters. Other arguments are refused.

Result

domain + confidence + review_recommended

Also success, result_type (found, no_match or error), message, company_name, confidence_band, reasons, lower_reasons, is_live, linkedin_url, industry, sub_industry, sector, credits (remaining, limit), error_type, retryable and retry_after_seconds.

Guide

file://elvesora/domain-lookup/mcp-guide.md

A Markdown guide that clients can read from the server. Reading it, connecting and listing tools use no credits.

Connect your client

Use Elvesora sign-in in Claude and Codex, or a team API token in Claude Code. Each Elvesora product has its own MCP server and its own connection.

Elvesora sign-in

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 the Domain Lookup team you choose on the approval screen.
https://prospecting.elvesora.com/api/mcp/domain-lookup

Elvesora sign-in

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-domain-lookup]
url = "https://prospecting.elvesora.com/api/mcp/domain-lookup"
codex mcp login elvesora-domain-lookup

Team API token

Claude Code

Create a team API token in Domain Lookup 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-domain-lookup \
https://prospecting.elvesora.com/api/mcp/domain-lookup \
--header "Authorization: Bearer $ELVESORA_LOOKUP_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 Domain Lookup credits. Signing in again with the same client and team keeps the working connection. Choosing another team replaces the earlier connection.

To remove access, open Domain Lookup, 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-domain-lookup and then codex mcp login elvesora-domain-lookup to sign in again.

Supported clients

Checked with Claude, Claude Code and Codex. 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.

When the agent should ask you

review_recommended follows the REST confidence bands. When it is false (high band, 85-100), the agent can use the domain. When it is true, the agent shows the candidate and its reasons and asks for the country, industry or website before using it, and does not pass it to Enrichment. For no_match, the agent says there is no match and does not guess a domain.

In our Claude Code check, Stripe returned stripe.com with confidence 99 and review_recommended false. Mercury without context returned mercury.com with confidence 45 and review_recommended true, and the agent asked which Mercury was meant.

Credits and timing

Each resolve_company_domain call uses one Domain Lookup credit of the connected team. Lookup has no idempotency: calling again for the same company can use another credit, so an agent should not repeat a call that already returned a result. Invalid arguments, calls blocked by the plan limit and calls over 30 per minute use no credit, and a provider rate limit returns the credit. The result includes credits.remaining.

A call answers within 60 seconds. A slow provider ends in lookup_timeout instead of a hanging call.

MCP errors

Errors come back as tool results with isError set to true and a typed error_type, so the agent can tell you the reason. A lookup error is not a no-match.

MCP error results set success to false and result_type to error. They keep domain, confidence, confidence_band, and review_recommended as null; REST error responses omit those match fields. Check error_type and retryable, and follow retry_after_seconds when present.

error_type Meaning Credit
invalid_arguments company_name is missing or too long, additional_context is too long, or an unknown argument was sent. Not used
too_many_requests More than 30 calls in one minute for the team. Not used
usage_limit The team has no Domain Lookup credits left on its plan. Not used
rate_limited The lookup provider is throttling requests. Wait for retry_after_seconds before another call. Returned
lookup_timeout, lookup_unavailable, lookup_invalid_response and other lookup errors Provider failures, with the same error_type and retryable values as the REST API. Same as the REST API

Token checks and request tracing

Use the authenticated check to verify that a team token can reach the protected API. Every response returns an X-Request-Id header: a valid incoming value is echoed, otherwise the service generates one.

Every API response

X-Request-Id

Send an optional request ID for tracing, or use the generated value returned by the service.

Bearer token required

GET https://prospecting.elvesora.com/api/prospecting/ping

Returns {"status":"ok"} after successful token authentication. This token check does not consume a lookup credit.

Confidence score

Every completed lookup includes confidence: found matches use 1-100 and completed no-match outcomes use 0. Use found-match confidence as a routing signal, and review lower scores with the returned reasons. Error responses are excluded and include no confidence score.

Match reasons

Positive reasons explain why a domain matched. Lower reasons explain ambiguity, weak signals, or evidence that should reduce automation confidence. In the signed-in dashboard and list detail view, reasons containing a source URL show a readable evidence link that you can open for review.

No-match

A completed lookup with found set to false returns domain null and confidence 0. Keep the domain blank, add context, or route the company record to review instead of guessing. Error responses do not include confidence.

Dashboard and bulk workflows

After sign-in, enter one company name in the dashboard's Find Domain form for a one-off lookup, or import a list for bulk processing and review. A one-company lookup runs in the background and the page checks for updates automatically. You can leave and return while it is running; processing stops after five minutes, and transient service failures are retried within that window. Bulk lookup works best when the source file has one company per row, a predictable header, and a review path for records that should not be written automatically.

Reviewer decisions create team-scoped domain memory. A previously verified correction can resolve a matching future row without another API lookup or credit. If the same team previously marked the same normalized domain incorrect for the same normalized company name, a future result is forced to Needs Review and receives an explanatory lower-confidence reason.

A team-memory result comes from reviewer history rather than a fresh reachability check. It is marked lookup_source=team_memory with confidence 100; is_live=false must not be interpreted as a fresh unreachable-domain result.

  1. 1 Upload a CSV, XLS, or XLSX file up to 10 MB, paste company names, or call the API with a clean company_name value.
  2. 2 Map company_name plus optional external_id, country, industry, sector, and additional_context columns before import.
  3. 3 Add additional_context only when a name is ambiguous, regional, or shared by multiple businesses.
  4. 4 Use preflight counts to separate unique rows, duplicates, empty rows, and team-memory matches before credits are spent.
  5. 5 Auto-verify 85+ matches, filter by lookup or verification status, and require a Final Domain before a reviewer accepts a result.
  6. 6 Export all rows or verified-only rows as a 17-column XLSX workbook with Company Name, Final Domain, Suggested Domain, Corrected Domain, Confidence Score, Verification Status, Review Notes, Country, Industry, Sector, Is Live, Reason Summary, Reasons, External Id, Lookup Status, Lookup Source, and Processed At. The single Reasons column combines positive reasons and lower-confidence signals; lookup status/source remain separate columns.
  7. 7 Rerun only selected review, incorrect, or failed records by choosing the needs-review, incorrect, or failed mode, or rerun one record. Transient lookup failures are retried automatically.

Troubleshooting and limits

Keep API errors separate from match quality. Auth, billing, and usage errors describe account or request state, while confidence and reasons describe the match.

Issue Recommended action
401 Unauthorized Check that the bearer token is present, active, and stored server-side.
422 validation error Send a non-empty company_name string and keep CSV headers mapped to the expected field.
502 invalid lookup response Retry after 60 seconds. HTTP status is 502, error_type is lookup_invalid_response, retryable is true, and retry_after is 60. The error omits domain, found, and confidence.
429 plan usage limit error_type is usage_limit and retryable is false. Review remaining allowance, pause bulk jobs, or choose a plan with more lookup credits.
429 provider rate limit error_type is rate_limited and retryable is true. Follow retry_after, which is bounded from 1 to 300 seconds; the reserved credit is released.
503 lookup unavailable or upstream failure lookup_timeout, lookup_connection_failed, and lookup_unavailable include retry_after 60. A provider HTTP failure can return upstream_http_error; follow retryable and retry_after when present.
503 terminal provider failure error_type is lookup_provider_unavailable and retryable is false. Stop automatic retries and contact support; a 503 status alone does not mean the failure is transient.
found is false A completed no-match returns domain null and confidence 0. Do not write a domain automatically; add context, retry later, or keep the record in review.
low confidence Inspect reasons and lower_reasons before deciding whether to accept, retry, or leave the domain blank.

Product boundary

Product boundary: company-name to official-website matching. Not a people, inbox, or owner-record product.

Credits

New accounts receive a recurring Free plan with 10 monthly credits. Every authenticated company lookup response consumes one credit after it passes the usage-limit check, including validation errors, completed no-match and cached results, and retryable 502 and 503 responses. A request blocked by the plan limit does not consume a credit, and a provider rate_limited 429 releases its reservation. Verified team-memory reuse in a bulk list skips the API lookup and does not consume a credit. Dashboard Find Domain reserves one credit when a lookup is accepted. The reservation is released if execution never starts or provider throttling remains terminal; completed no-match and other committed attempts remain counted.

Security

Tokens belong to a team account. Store them in server-side configuration and rotate them when access should change.