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,
"confidence_band": "high",
"review_recommended": false,
"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. Required string, maximum 255 characters. |
| additional_context | No | Short context that can help disambiguate similar company names, such as country, industry, or known product line. Optional string, maximum 2,000 characters. |
| 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. Error responses omit domain, found, and confidence. |
| retryable / retry_after | Retry guidance on transient errors. 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. |
Developer resources
Inspect the machine-readable response variants, run the saved requests, or install the official PHP package without translating the API contract from prose.
API contract
Machine-readable contract for GET /api/prospecting/ping and POST /api/prospecting/company.
View YAML →Request collection
Runnable token check, lookup request, routing-band assertions, and saved success and error examples.
Open collection →Official package
Official Composer package elvesora/domain-lookup-php, published as v1.0.0 on Packagist.
View package →Official package
Official Laravel 12 and 13 package with auto-discovery, dependency injection, a facade, typed results, and typed exceptions.
View package →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. This token check does not consume a lookup credit.
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 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. |
| 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: company-name to official-website matching. Not a people, inbox, or owner-record product.
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.
Tokens belong to a team account. Store them in server-side configuration and rotate them when access should change.