How to Segment B2B Accounts With Firmographic Data (API and MCP)

Firmographic data is the company-level equivalent of demographics: industry, headcount, headquarters, funding, revenue and the technology a company runs. You segment by combining these fields into one filter. This guide builds a real segment, sizes it for free, pulls a sample and finds the people inside it.

TL;DR

• Firmographics describe the account, not the person. Pick 3 to 4 fields that separate buyers from non-buyers, then size the list before you pull it.
• The whole recipe takes about 15 minutes and spends about 30 of the 1,000 free records. The count is free.
• Sizing uses GET /v1/companies/count. Pulling uses POST /v1/companies/search. Finding people uses GET /v1/companies/{domain}/people.

What counts as firmographic data

Firmographic fields fall into five groups. Each maps to a LeadOcean company filter.

There are 34 company filters in total. Technology data covers about 7.8M crawled sites, so it is a partial field. Treat it as a bonus filter, not a base one.

Firmographics are not demographics. Job title and seniority belong to the person. Keep them for the last step.

Prerequisites

• A LeadOcean account on the free plan: 1,000 records for life, no card, 5 requests a second. Sign up.
• An API key from app.leadocean.io, exported as $LEADOCEAN_API_KEY.
• curl and jq.
• Optional: the hosted MCP server at https://api.leadocean.io/mcp (OAuth sign-in, no key pasted) if you would rather run the count from a chat.

Step 1: Choose the fields that define the segment

Start with an ideal customer profile you can write in one line. Ours for this example: UK IT services firms with 51 to 200 employees.

Three fields do the work. Add a fourth only if the list is still too large.

industry:      IT Services and IT Consulting
employeeRange: 51-200
hqCountry:     GB

Enum values are exact strings. Resolve them before you guess. Over MCP, leadocean_list_enum_values is free:

leadocean_list_enum_values({ name: "industry", q: "IT services" })

Over REST, GET /v1/enums returns the same lists and costs nothing.

Step 2: Size the segment for free

Count companies before you pull any. The count is exact and spends no records.

curl -s -G "https://api.leadocean.io/v1/companies/count" \
  --data-urlencode "industry=IT Services and IT Consulting" \
  --data-urlencode "employeeRange=51-200" \
  --data-urlencode "hqCountry=GB" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq '{total: .data.total, naics: .data.facets.naics_primary[0:3]}'

The same call runs from MCP:

leadocean_count_companies({
  industry: ["IT Services and IT Consulting"],
  employeeRange: ["51-200"],
  hqCountry: ["GB"]
})

The response also breaks the total down by industry, headcount band, HQ country, HQ state and NAICS. Use the breakdown to spot a skew before you commit. If one NAICS code holds half the list, your segment is really two segments.

Step 3: Tighten or widen until the size fits

A segment should match the capacity of whoever works it. Two reps can work a few hundred accounts. A programmatic campaign can take thousands.

Add hasMailableContacts: true to keep only companies with at least one person whose best email is verified, catch_all_valid or catch_all. This changes what the count means, so label it: it is companies with a mailable contact, not mailable people.

curl -s -G "https://api.leadocean.io/v1/companies/count" \
  --data-urlencode "industry=IT Services and IT Consulting" \
  --data-urlencode "employeeRange=51-200" \
  --data-urlencode "hqCountry=GB" \
  --data-urlencode "hasMailableContacts=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data.total'

Watch the fields you filter on. Numeric filters such as minRevenue or minFunding only match records where we hold the value. A company with no figure on file is never returned, so a revenue floor shrinks the list more than you expect.

Step 4: Pull a 25-company sample

Read a few rows before you export hundreds. Search returns one record per company, so 25 rows spend 25 records.

curl -s -X POST https://api.leadocean.io/v1/companies/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": ["IT Services and IT Consulting"],
    "employeeRange": ["51-200"],
    "hqCountry": ["GB"],
    "limit": 25
  }' | jq '.data[0:3]'

The body is flat JSON and filters are arrays. limit runs from 1 to 100. To page, pass the cursor from the previous response. One search pages to 10,000 rows, then the response sets meta.depthCapped and stops. Narrow the filters instead of walking the index.

Check the sample against your ICP. If you see management consultancies in an IT services segment, add excludeKeywords or filter on naicsPrimary and recount.

Step 5: Find the people inside the accounts

Firmographics pick the account. Now pick the person. For one company, list its people:

curl -s "https://api.leadocean.io/v1/companies/acme.com/people?limit=5" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data'

This spends one record per person returned. For a whole segment, use people search with the same company filters plus a title or seniority filter, and run the free people count first.

For lists of 1,000 rows or more, use POST /v1/exports. Exports take up to 50,000 rows a request and 500,000 a day. Bulk CSV export is not on the free plan: it starts on Solo at $97 a month. See pricing.

What you get

This is a real run of the Step 2 count through leadocean_count_companies, on 2026-10-21, trimmed to the top three NAICS codes. It cost 0 records.

{
  "total": 1628,
  "totalIsExact": true,
  "facets": {
    "naics_primary": [
      { "value": "541611", "count": 738 },
      { "value": "541511", "count": 584 },
      { "value": "541512", "count": 176 }
    ]
  },
  "unsupportedFilters": []
}

So 1,628 UK companies are filed under IT Services and IT Consulting with 51 to 200 employees. The largest NAICS code is 541611 (management consulting), with 738 of them, ahead of 541511 (custom programming) with 584. That split is the skew Step 2 warns about. The Step 3 count with hasMailableContacts: true returned 982 companies on the same day. That is companies with at least one mailable contact, not mailable people.

A company record from the search in Step 4 follows the response shape from the API reference. Values below are placeholders.

{
  "data": [
    {
      "company_data": {
        "company_name": "Acme",
        "company_domain": "acme.com",
        "company_industries": [{ "name2": "IT Services and IT Consulting", "priority": 1 }],
        "company_employees": { "number_of_employees": 85, "number_of_employees_code": "51-200" },
        "company_primary_address": { "city": "Leeds", "country_code": "GB" },
        "naics_primary": "541511"
      },
      "meta": { "fetched_at": "2026-10-01", "schema": "leadocean.company.v1" }
    }
  ],
  "meta": { "nextCursor": "..." }
}

Fields we hold nothing for come back as null, never guessed.

Troubleshooting

FAQ