Company Lookup API Example: curl Requests and Response Handling

A company lookup API call is one authenticated HTTPS request with a domain, and it returns a JSON envelope with a found flag and a company object. With BusinessMCP’s documented API, that is a GET to /api/hub/v1/companies/{domain} with a bearer key. Handle found: false as a normal result and retry only errors the API marks retryable.

All details below come from BusinessMCP’s public Data API reference. Check it for the current version before you build, since fields and limits can change.

Authentication

Every call carries your key as a bearer token:

export BUSINESSMCP_API_KEY="mcph_your_key_here"

A missing, revoked or expired key, or one without Data API access, returns 401. Keep keys out of source control and give each integration its own key so you can revoke one without breaking the rest.

A single lookup

curl https://businessmcp.com/api/hub/v1/companies/stripe.com \
  -H "Authorization: Bearer $BUSINESSMCP_API_KEY"

The reference gives the price as $0.02 per call, charged only when a company is found, with a 12-second deadline. Input is a domain of up to 253 characters, and the reference says a URL or work email also works.

The response is an envelope of the form { ok: true, data, meta }. Inside data you get found and company. The documented company fields are:

Field	Meaning
domain, name	Identity of the company
industry, category	Classification labels
employee_range, employee_count	Size information
founded_year	Year of founding
country, region, city	Location
phone, linkedin_url	Contact pointers
description, tech_stack	Descriptive fields
brand_only	Whether only a name-level record exists
website_status	Live, offline, redirecting and similar
source	Where the record came from

Not every field is filled for every company, so code defensively and treat any field as optional. One practical point: the reference notes that brand platforms such as google.com come back name-only, which is what brand_only is for.

A bulk lookup

curl -X POST https://businessmcp.com/api/hub/v1/companies/bulk \
  -H "Authorization: Bearer $BUSINESSMCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["stripe.com","notarealcompany-xyz.com"]}'

Per the reference, the body takes a domains array of 1 to 100 items. The response data has results and a found count, and each result has domain, found and company. Results come back in input order, and unknown domains show found: false with company: null. Price is $0.02 per item found, with misses refunded, and the deadline is 20 seconds. More on the batch process in bulk company lookup by domain.

Email pattern

curl https://businessmcp.com/api/hub/v1/companies/acme.com/email-pattern \
  -H "Authorization: Bearer $BUSINESSMCP_API_KEY"

The response includes pattern, confidence, validated, example, accepts_mail, catch_all and mail_checked_at, at $0.01 per call when a pattern is known. Read how to find a company’s email format for how to interpret those fields.

Key takeaway: found: false is a successful response with no record. Branch on it; do not treat it as an exception.

Handling errors

The reference lists failures as { ok: false, error: { code, message, hint?, retryable, ... } }.

HTTP	Code	Retry?
400	invalid_input	No, fix the input; never charged
401	none listed	No, fix the key
402	quota_exceeded	No, add balance or raise the key cap
403	not_permitted	No, access suspended
404	not_found	No, wrong route
429	quota_exceeded (rate limited)	Yes, after the retry-after delay (60 seconds in the example)
503	upstream_failed or backend_unavailable	Yes; charged calls are refunded
500	unavailable	Yes

A simple rule: retry on the retryable flag, back off between attempts, cap the number of retries, and log the rest.

Rate limits

The reference states 600 calls per minute per key and 3,000 per minute per account across keys. Heavier tools, including bulk company lookup, are limited to 60 calls per minute per key. At 100 domains per bulk call that is a ceiling of up to 6,000 domains a minute, though real throughput depends on deadlines and your own concurrency. Add a small delay between calls, and keep concurrency low until you have measured it.

A minimal shell loop

while read -r d; do
  curl -s "https://businessmcp.com/api/hub/v1/companies/$d" \
    -H "Authorization: Bearer $BUSINESSMCP_API_KEY" >> results.jsonl
  echo >> results.jsonl
  sleep 0.2
done < domains.txt

That is fine for a few hundred domains. For more, use the bulk endpoint, parse JSON properly in your language of choice, and write results to a table keyed by domain.

Testing safely

The hosted BusinessMCP company lookup is a handy way to eyeball a domain before you script it.

1. Start with the free tier: new accounts get $5 for 7 days per BusinessMCP’s pages.
2. Try one known domain, one tiny domain and one fake one.
3. Check your balance before and after to confirm how misses are billed.
4. Store the raw JSON of your test calls so you can compare later.

For the no-code version of the same lookup, the free tool shows industry, size, location, founding year and LinkedIn, limited to 15 lookups an hour. Costs at scale are covered in company lookup API pricing.

Production habits

• Cache results for each domain with a timestamp, and re-query on a schedule rather than every request.
• Set a per-key spend cap if available and alert on low balance.
• Log request IDs or timestamps for support questions.
• Keep the vendor-specific mapping in one module so a change of provider touches one file.
• Treat the company description and tech stack as unverified text, and escape it before showing it in a UI.

Parsing the response

If you have jq installed, pulling a few fields from a single lookup is a one-liner:

curl -s https://businessmcp.com/api/hub/v1/companies/stripe.com \
  -H "Authorization: Bearer $BUSINESSMCP_API_KEY" \
  | jq '.data | {found, name: .company.name, industry: .company.industry, size: .company.employee_range}'

The shape follows the envelope described in the reference. For the bulk endpoint, iterate over .data.results[] and branch on .found. In any language, the pattern is the same: check ok, then data.found, and only then read data.company. Anything missing should become a null in your table, not a default string such as “unknown”, because a null is easy to filter.

Mapping the output into a table

A flat table is the easiest target. One row per domain, with columns for the fields you chose, a looked_up_at timestamp, a found boolean and the raw JSON in a text column. When a field you rely on changes name or disappears, the raw column lets you re-parse without paying for another call.

Column	Source	Notes
domain	Your input, cleaned	Primary key
found	data.found	Boolean
name	company.name	Nullable
industry	company.industry	Map to your own taxonomy
employee_range	company.employee_range	Keep as text, not a number
website_status	company.website_status	Useful for filtering dead sites
looked_up_at	Your clock	For refresh rules
raw	Full response	For re-parsing

Calling it from an AI agent instead

The same lookups are exposed as MCP tools, named company_lookup, company_bulk_lookup and email_pattern on BusinessMCP’s page, which means an agent can call them without custom glue code. That is covered in company lookup for AI agents via MCP.