How to Enrich a Company (From Domain to Firmographics With the LeadOcean API)

TL;DR

• Company enrichment takes an identifier, usually a domain, and returns a company record: name, headcount, industry, HQ, funding and detected website technologies.
• It takes about 10 minutes and spends about 4 LeadOcean records. A hit costs 1 record. A 404, a count and an empty page cost nothing.
• Count the list before you enrich it. POST /v1/companies/count is free and returns an exact total.

Company enrichment is the step that turns a bare domain in your CRM into something you can filter on. You send acme.com. You get back how big Acme is, what it sells, where it sits and what it runs on.

Prerequisites

• A LeadOcean account on the Free plan: sign up. No card.
• An API key from app.leadocean.io, exported as $LEADOCEAN_API_KEY.
• curl and jq. Any HTTP client works the same way.
• A domain to test. We use the placeholder acme.com.

export LEADOCEAN_API_KEY="paste-your-key-here"

Step 1: Pick the identifier

Enrichment is a lookup, not a search. You hand over one key and get one record. Company enrich accepts a domain or a linkedin_url.

A domain is the better key. It is unique, it sits in most CRM exports and it needs no cleaning beyond lowercasing and stripping https://www.. There is no lookup by company name. If you only have a name, search first and enrich the domain that comes back (Step 4).

Step 2: Enrich one company

Send the domain to POST /v1/companies/enrich.

curl -s -X POST "https://api.leadocean.io/v1/companies/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"acme.com"}' | jq .

GET works too, with domain or linkedin_url as query parameters. A hit costs 1 record. A 404 means we hold nothing for that company and costs nothing. Treat it as a miss, not an error.

Step 3: Size the list before you enrich it

Before you loop over thousands of domains, or before you search for a segment, count it. The count call is free and returns an exact total plus breakdowns.

curl -s -X POST "https://api.leadocean.io/v1/companies/count" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hqCountry":["US"],"employeeRange":["51-200"],"industry":["Software Development"]}' \
  | jq '.data | {total, totalIsExact}'

Filters are arrays of exact strings. If a value is rejected, list the allowed ones with GET /v1/enums or the leadocean_list_enum_values MCP tool. An agent can run the same count through leadocean_count_companies.

Step 4: Find companies when you only have a segment

Search returns companies that match filters, 1 record per company returned. Use it when you have a profile of the company you want and no domain list yet.

curl -s -X POST "https://api.leadocean.io/v1/companies/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hqCountry":["US"],"employeeRange":["51-200"],"industry":["Software Development"],"limit":3}' \
  | jq '.meta'

The body is flat JSON and limit runs 1 to 100. Page with the cursor value from the previous response. One search pages to 10,000 rows. Past that, meta.depthCapped is true and there is no nextCursor, so narrow the filters instead.

Step 5: Loop a batch and respect the rate limit

There is no batch endpoint for company enrichment. Loop over your domains and keep under your plan's rate limit: 5 requests a second on Free, 200 on Agency.

mkdir -p out
while read -r d; do
  code=$(curl -s -o "out/$d.json" -w "%{http_code}" \
    -X POST "https://api.leadocean.io/v1/companies/enrich" \
    -H "x-api-key: $LEADOCEAN_API_KEY" \
    -H "content-type: application/json" \
    -d "{\"domain\":\"$d\"}")
  echo "$d $code"
  sleep 0.25
done < domains.txt

Log the status code per domain. On a 429, wait for the Retry-After header and retry. When you want a whole segment rather than a domain list, page POST /v1/companies/search with cursor instead of looping enrich. POST /v1/exports covers people, not companies, and bulk CSV export is not on the Free plan.

What you get

Step 3 returns an exact total. This is the free MCP count for the same filters, run on 21 October 2026:

{
  "total": 9261,
  "totalIsExact": true,
  "unsupportedFilters": []
}

The same call also returns hq_state buckets. California leads with 2,398 of the 9,261 companies.

Step 2 returns the shape below. This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": {
    "company_data": {
      "company_name": "Acme",
      "company_domain": "acme.com",
      "company_employees": { "number_of_employees": 240, "number_of_employees_code": "201-500" },
      "company_primary_address": { "city": "Austin", "country_code": "US" },
      "company_funding": { "last_round_type": "Series B" },
      "company_number_of_detected_technologies": 1
    },
    "company_detected_technologies": [
      { "technology_product": { "name": "Cloudflare" }, "technology_last_detected_date": "2026-08-21" }
    ],
    "company_metrics": { "completion_score": 94, "marketability_score": 81 },
    "meta": { "sources": ["own"], "fetched_at": "2026-10-01", "schema": "leadocean.company.v1" }
  }
}

Unknown values come back as null, never guessed. Funding and revenue are thin for small private companies, so do not build a filter on them alone. Technology data covers about 7.8M crawled sites, so that array is empty for companies outside the set. The dataset is refreshed monthly and each record carries its own fetched_at date.

Troubleshooting

FAQ