How to Use a B2B Data API (Size, Search, Enrich, Export)

A B2B data API does four jobs: size a list, search it, enrich a known person, and export in bulk. Learn those four calls and you can use any provider.

This page runs them against LeadOcean, which holds 693M people and 67M companies. Each step has a request you can paste. For the concept first, read what a B2B data API is.

TL;DR

• Four calls cover most work: a free count, a search, an enrichment and a bulk export.
• It takes about 20 minutes on the free plan.
• It spends about 10 of your 1,000 free records. Counts and misses cost nothing.

Prerequisites

• A LeadOcean account. Start free at app.leadocean.io, no card.
• An API key from the app, stored as $LEADOCEAN_API_KEY.
• curl and jq. Or any MCP client (Claude, ChatGPT) for the no-code route.
• Rate limit on Free: 5 requests a second per key. Agency gets 200.

export LEADOCEAN_API_KEY="paste-your-key-here"
curl -s https://api.leadocean.io/v1/account -H "x-api-key: $LEADOCEAN_API_KEY"

GET /v1/account is free. If it returns your account and plan, the key works.

Step 1: Look up the exact filter values

Enum filters are exact strings, and a wrong one returns nothing. Look values up first with GET /v1/enums/{name}, which is free and needs no key.

curl -s "https://api.leadocean.io/v1/enums/job_level" | jq '.data.values'

The same lists are in the MCP tool leadocean_list_enum_values. Job level takes C-Team, VP, Director, Manager, Staff or Other. Seniority is lowercase (c_suite, vp, director). Job function looks like Sales & Business Development. There are 50 people filters and 34 company filters in all.

Step 2: Size the list for free

Add count=true and limit=1 as query parameters, not in the JSON body. The data comes back empty and no record is spent.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true&limit=1" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["CA"]}'

meta.total is capped at 100,000. The body is flat JSON and filters are arrays. Companies have a matching free call: GET /v1/companies/count returns an exact total with breakdowns by industry, headcount band and HQ country.

Step 3: Search and page through results

Drop count=true and the same body returns people. Each person returned is one record. Page with cursor.

curl -s -X POST "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["CA"],"limit":10}' \
  | jq '.meta'

limit runs 1 to 100, default 25. Pass the returned nextCursor as cursor for the next page. One search pages to 10,000 rows, then meta.depthCapped is true and nextCursor disappears. Narrow the filters instead of walking the index.

Step 4: Enrich one known person

Enrichment takes exactly one of linkedin_url, email, phone or person_id. There is no name plus domain lookup. Search by domain first, then enrich by person_id.

curl -s -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"linkedin_url":"https://www.linkedin.com/in/jane-doe-example","reveal_email":true}'

A person we hold nothing for returns 404 and costs nothing. reveal_email costs no extra record. Since 17 October 2026, career history (past roles, education, certifications) comes back as resume_data.

Step 5: Export in bulk

Use the Exports page in the app: pick filters, pick columns, read the record price, then download the CSV. The same job runs over the API with POST /v1/exports.

Ceilings: 50,000 rows a request and 500,000 rows a day. Bulk CSV export is not on Free. Solo ($97 a month) includes it. Numbered columns are named email_1_address, email_2_address, phone_1_number.

Step 6: Skip the code with MCP

LeadOcean runs a hosted MCP server at https://api.leadocean.io/mcp with 13 tools. Sign-in is OAuth, so no key is pasted. Ask your client in plain English:

Count VPs of Sales in Canada, then show me the top 5 breakdowns by industry.

The client calls leadocean_count_leads, which is free.

What you get

A free count run on 2026-10-21 through the MCP tool, for VP, Sales & Business Development, country CA:

{
  "total": 5574,
  "totalIsExact": true,
  "totalAll": 18800,
  "distinctCompanies": 3873,
  "credits": 0
}

total is the mailable count: emails with status verified, catch_all_valid or catch_all. totalAll is the same filters with no email condition. Cost: 0 records.

A search page has this shape (response shape from the API reference, placeholder values, rows trimmed with fields=profile_data.profile_full_name,meta.source_ids):

{
  "success": true,
  "data": [
    {
      "profile_data": { "profile_full_name": "Jane Doe" },
      "meta": { "source_ids": { "person_id": "1234567890" } }
    }
  ],
  "meta": { "count": 10, "limit": 10, "credits": 10, "nextCursor": "<cursor>" }
}

Search rows are a thin projection with no contact points. Send meta.source_ids.person_id to enrich to get the full person. The OpenAPI file at api.leadocean.io/openapi.json is the source of truth.

Troubleshooting

FAQ