How to use B2B data for market research (sizing a segment with an API)

You can size a B2B segment in 20 minutes with free count calls, then spend about 25 records on a sample. This recipe sizes German software companies with 51 to 200 staff and pulls a few C-level names for interviews.

TL;DR

• Count companies and people first. Counts cost 0 records, so you can iterate on filters as long as you like.
• Break the total down by state and industry code, then pull a 25-person sample for interviews or a survey.
• Time: about 20 minutes. Records spent: about 25 of the 1,000 on the Free plan, plus 1 per person you enrich.

Prerequisites

• A LeadOcean key from app.leadocean.io/register. Free is $0, no card, 1,000 records for life.
• The key in your shell: export LEADOCEAN_API_KEY=...
• curl and jq. Or the hosted MCP server at https://api.leadocean.io/mcp if you work in Claude.

Step 1: Pin the segment with exact filter values

Enum filters are exact strings, so look them up before you guess. Industry has 534 values and country is an ISO code.

curl -s "https://api.leadocean.io/v1/enums" -H "x-api-key: $LEADOCEAN_API_KEY" | jq 'keys'

In an MCP client, leadocean_list_enum_values does the same with a search term. For this recipe the values are hqCountry: DE, industry: Software Development and employeeRange: 51-200.

Step 2: Count the companies (free)

GET /v1/companies/count returns an exact company total plus breakdowns. It spends no records.

curl -sG "https://api.leadocean.io/v1/companies/count" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "hqCountry=DE" \
  --data-urlencode "industry=Software Development" \
  --data-urlencode "employeeRange=51-200"

The MCP tool leadocean_count_companies takes the same filters. On 21 October 2026 it returned 738 companies, with Bavaria first at 101.

Step 3: Count the people inside those companies (free)

Market research usually needs the buyer, not just the firm. Send count=true as a query parameter with limit 1. The body stays flat JSON and filters are arrays.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "hqCountry": ["DE"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "jobLevel": ["C-Team"],
    "limit": 1
  }'

meta.total is capped at 100,000, which is far above this segment. The people count carries meta.distinctCompanies, so you see how many employers the people span.

Step 4: Read the gap between reachable and total

Do not treat a people count as a mailable audience. The MCP count tool defaults to verified, catch_all_valid and catch_all emails. Pass emailStatus with every value to see everyone.

For the segment above, the default count was 831 people at 258 companies. With no email condition it was 3,165. Say which of the two your report uses.

Step 5: Pull a 25-person sample

Now spend records. Ask for one page of 25 and keep the cursor if you want more. One search pages to 10,000 rows, so narrow the filters instead of walking deep.

curl -s -X POST "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "hqCountry": ["DE"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "jobLevel": ["C-Team"],
    "limit": 25
  }' | jq '(.data | length), (.data[0].meta.source_ids.person_id)'

A page of 25 is 25 records. That is your interview or survey list. For a full segment, use POST /v1/exports (up to 50,000 rows a request, 500,000 a day; not on Free).

Step 6: Add career history for a short list

Person enrich returns past roles, education and certifications when LeadOcean holds them. Past employers carry no company_id yet. Enrich by person_id from Step 5.

curl -s -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"person_id": "<person_id from step 5>"}' | jq '.data.resume_data.experiences'

An enrichment that finds nobody is a 404 and costs nothing.

Step 7: Turn the counts into a market model

A count is not a market size until you attach a value. Multiply company counts by an average contract value you can defend, then show the range, not one number.

jq -n --argjson n 738 --argjson low 6000 --argjson high 24000 \
  '{companies:$n, annual_low:($n*$low), annual_high:($n*$high)}'

The contract values are your assumptions. LeadOcean supplies the company count, the split and the buyer list. It does not supply revenue per customer.

Three habits keep the model honest:

• Date every count. The dataset is refreshed monthly, so a count from October will drift. Store the date beside the number.
• Record the filters. Save the exact request next to the result so anyone can rerun it.
• Cross-check one cut. Compare one state's count against a public register you trust. If they differ by a wide margin, say so in the report.

Re-run Steps 2 and 3 each quarter with the same filters. The trend is often more useful than the level.

Step 8: Use the sample for primary research

Secondary data tells you how big the segment is. Interviews tell you why they buy. The 25-person sample from Step 5 is enough for a first round of outreach or a short survey.

Check email_status before you send anything. A bounced email gets no refund, so keep to verified addresses for a small panel. Cut the sample by state or headcount band so you hear from different parts of the segment, not only Bavaria.

What you get

Real output from the free count tools, 21 October 2026:

leadocean_count_companies
  hqCountry DE, industry Software Development, employeeRange 51-200
  total: 738 (exact)
  hq_state: Bavaria 101, North Rhine-Westphalia 75,
            Baden-Wuerttemberg 64, Berlin 57, Hesse 24

leadocean_count_leads (default mailable emails)
  same company filters + jobLevel C-Team
  total: 831 people, distinctCompanies: 258
  totalAll (no email condition): 3,165

Search record shape, from the API reference, with placeholder values:

{
  "success": true,
  "data": [{
    "profile_data": { "profile_full_name": "Jane Doe", "profile_headline": "CEO at Acme" },
    "contact_data": {
      "has_email": true,
      "email_status": "verified",
      "contact_current_experiences": [
        { "company_name": "Acme", "company_domain": "acme.com", "job_title": "CEO" }
      ]
    },
    "meta": { "source_ids": { "person_id": "1234567890" } }
  }],
  "meta": { "count": 25, "nextCursor": "..." }
}

That block is the response shape from the API reference, not a real record. Search rows carry no contact points: enrich the people you choose for those.

Troubleshooting

FAQ