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
Call the API from your backend. Keep the bearer token out of browser and mobile client code.
POST https://prospecting.elvesora.com/api/prospecting/company
Authorization: Bearer $ELVESORA_API_KEY
Content-Type: application/json
X-Request-Id: crm-import-2026-07-12
{
"company_name": "Acme Corporation",
"additional_context": "Industrial equipment manufacturer"
}Read found and confidence before writing the domain into another system.
{
"success": true,
"message": "Company lookup completed",
"company_name": "Acme Corporation",
"normalized_company_name": "acme corporation",
"domain": "acme.com",
"linkedin_url": "https://www.linkedin.com/company/acme",
"industry": "Industrial Machinery",
"sub_industry": "Industrial Equipment",
"sector": "Industrials",
"confidence": 92,
"is_live": true,
"reasons": ["Company name matches website brand"],
"lower_reasons": [],
"cached": false,
"found": true,
"remaining": 1249,
"limit": 1250
}The endpoint is designed for company identity resolution. It does not check domain ownership records or whether a domain can be purchased.
| Request field | Required | Description |
|---|---|---|
| company_name | Yes | Company, brand, or organization name to resolve to a likely official website domain. |
| additional_context | No | Short context that can help disambiguate similar company names, such as country, industry, or known product line. |
| Response field | Description |
|---|---|
| success | True for completed found or no-match outcomes; false for errors. 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 numeric outcome for completed lookups: 1-100 when found is true and 0 when found is false. Error responses do not include confidence. |
| 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. A strict upstream response failure returns lookup_invalid_response with HTTP 502 and omits domain, found, and confidence. |
| retryable / retry_after | Retry guidance on transient errors. A 502 lookup_invalid_response returns retryable true and retry_after 60. |
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
Send an optional request ID for tracing, or use the generated value returned by the service.
Bearer token required
Returns {"status":"ok"} after successful token authentication.
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.
Positive reasons explain why a domain matched. Lower reasons explain ambiguity, weak signals, or evidence that should reduce automation confidence.
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.
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.
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 usage limit | Review remaining allowance, pause bulk jobs, or choose a plan with more lookup credits. |
| 503 lookup unavailable | Retry after 60 seconds. retry_after is 60 and error_type is lookup_timeout, lookup_connection_failed, or lookup_unavailable. |
| 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. |
Not a WHOIS API: Company Domain Lookup is not a domain availability checker and not an email-finding API.
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, not-found and cached results, and retryable 502 and 503 responses. A request blocked with 429 does not consume a credit. 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 an upstream 429 blocks the lookup; completed, not-found, and other committed attempts remain counted.
Tokens belong to a team account. Store them in server-side configuration and rotate them when access should change.