How to Tell the Four Types of Lead Generation API Apart (and Call Each One)

A lead generation API does one of four jobs: it discovers people, enriches a record you already hold, verifies a contact, or moves rows into another system. Most vendor pages blur these. This guide separates them and shows one real request for each against LeadOcean.

TL;DR

• The four types are discovery (search), enrichment (fill in a known person), verification (is this email safe to send) and sync (bulk export into your stack).
• It takes about 15 minutes with a free key.
• The run below spends 5 LeadOcean records: 3 from a search page, 1 from an enrichment and 1 from a status-filtered search. Counts cost nothing.

Prerequisites

• A LeadOcean account on the free plan (1,000 records for life, no card): https://app.leadocean.io/register
• An API key in your shell: export LEADOCEAN_API_KEY=...
• curl and jq. All requests go to https://api.leadocean.io with the header x-api-key.

Step 1: Know which type you need

Pick the type by what you already hold, not by vendor category.

Crustdata's guide uses the same four-way split (discovery, enrichment, verification, management), checked October 2026: https://crustdata.com/blog/lead-generation-api. The tooling differs far more than the taxonomy.

Step 2: Discovery. Size the list before you pull it

Discovery returns people you have not met, filtered by title, geography and company traits. Size it first. Send count=true as a query parameter with limit 1 in the body: it is free and returns meta.total, capped at 100,000.

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 '{"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["CA"],"limit":1}'

The body is flat JSON and every filter is an array. Enum values are exact strings, so check them first with GET /v1/enums or the free leadocean_list_enum_values MCP tool.

Then pull a small page. This spends 3 records:

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":3}'

limit runs 1 to 100. Page with the cursor value from meta. One search pages to 10,000 rows, so narrow the filters instead of walking the index.

Step 3: Enrichment. Complete a record you already hold

Enrichment takes exactly one input and returns the full record. Valid inputs: 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}'

reveal_email returns the address and costs no extra record. A person we hold nothing for is a 404 and costs nothing. Since October 2026 the response also carries career history in resume_data: past roles, education, certifications and awards.

Step 4: Verification. Read the status before you send

Verification answers one question: will this address bounce. LeadOcean does not sell it as a separate call. Every email carries an email_status, and the search filter emailStatus takes the values verified, catch_all_valid, catch_all, risky, unknown, untested, invalid, role, disposable, spam_trap, abuse, derived and none.

curl -s -X POST https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":["Head of Sales"],"country":["US"],"emailStatus":["verified"],"limit":1}'

There is no refund for bounced emails, so filter on status instead of trusting a count. To fetch one address for a known person, use GET /v2/people/email/work. It costs one record per call, including a call that finds nothing.

Step 5: Sync. Move the list out

Sync is the boring type and the one that breaks pipelines. For lists past a few hundred rows, skip paging and use POST /v1/exports: up to 50,000 rows a request and 500,000 a day. Bulk CSV export is not on Free. It is included on Solo ($97 a month).

curl -s -X POST https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ca-vp-sales",
    "filters": {"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["CA"]},
    "limit": 5000,
    "preset": "full"
  }'

filters takes the same flat filters as /v1/people/search. limit is the row count, up to 50,000. preset is full (contacts included) or search (search fields only). Every row costs one record. Poll GET /v1/exports/{id} until status is done, then fetch the file from downloadUrl or GET /v1/exports/{id}/download.

Prefer clicks? The Exports page in app.leadocean.io has a filter builder, a column picker and a price preview before you download the CSV. It is not a CRM. Push the file into yours.

What you get

The free count from Step 2, run on 21 October 2026 through the leadocean_count_leads MCP tool:

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

Filters: jobLevel VP, jobFunction Sales & Business Development, country CA. total counts only mailable addresses (verified, catch_all_valid or catch_all). totalAll is the same filters with no email condition. Cost: 0 records.

A search page returns this shape (response shape from the API reference, placeholder values):

{
  "success": true,
  "data": [
    {
      "profile_data": { "profile_full_name": "Jane Doe", "profile_headline": "VP Sales at Acme" },
      "contact_data": { "has_email": true, "email_status": "verified", "email_type": "work" },
      "meta": { "source_ids": { "person_id": "1234567890" } }
    }
  ],
  "meta": { "count": 3, "nextCursor": "(opaque string)" }
}

Troubleshooting

FAQ