How to Customize a B2B Lead List (Filters, Columns and Export Caps)

Customization in lead gen comes down to three controls: how finely you filter, which columns you get back, and how much you can cap per request. The brands differ on all three, and the only fair test is to run a real query. This guide does that against LeadOcean.

TL;DR

• You build one custom list in four calls: look up exact filter values, size the list for free, pull a page, then choose export columns.
• It takes about 20 minutes and spends 25 records on the Free plan. Sizing and lookups spend none.
• Bulk CSV export with custom columns is not on Free. It starts on Solo ($97 a month).

Prerequisites

• A LeadOcean account. The Free plan gives 1,000 records for life, no card, 5 requests a second.
• An API key from app.leadocean.io, stored as $LEADOCEAN_API_KEY.
• curl and jq. Optional: the hosted MCP server at https://api.leadocean.io/mcp if you would rather ask an agent to run the same steps.

For how other vendors compare on this, see B2B lead gen brands with excellent data accuracy and B2B lead gen and sales intelligence brands worth it. The wider tool map is in AI lead gen tools.

Step 1: Look up the exact filter values

Closed-list filters take exact strings, and a wrong string returns an empty list. Check the value before you use it.

curl -s "https://api.leadocean.io/v1/enums/job_level" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data.values'
curl -s "https://api.leadocean.io/v1/filters" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  | jq '{people: (.data.filters | length), companies: (.data.companyFilters | length)}'

Both calls are free. LeadOcean has 50 people filters and 34 company filters. Job level takes six values: C-Team, Director, Manager, Other, Staff and VP. Via MCP, leadocean_list_enum_values returned that same six-value list on 2026-10-21.

Step 2: Size the list before you pull it

A count is free and tells you whether the filters are too tight. Here is a custom list: VPs of sales in Germany, at companies of 51 to 500 people, running HubSpot.

{
  "jobLevel": ["VP"],
  "jobFunction": ["Sales & Business Development"],
  "country": ["DE"],
  "employeeRange": ["51-200", "201-500"],
  "technologies": ["HubSpot"]
}

Send it with count=true as a query parameter and limit=1. The body stays flat and filters are arrays.

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":["DE"],"employeeRange":["51-200","201-500"],"technologies":["HubSpot"]}' \
  | jq '.meta'

meta.total is capped at 100,000 and meta.countOnly is true. Nothing is billed.

Step 3: Pull a page of the custom list

Same body, now with a limit. Search takes limit from 1 to 100 and pages with a 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":["DE"],"employeeRange":["51-200","201-500"],"technologies":["HubSpot"],"limit":25}' \
  > page1.json
jq '.meta.nextCursor' page1.json

A page of 25 is 25 records. Pass nextCursor as cursor for the next page. One search pages to 10,000 rows, then meta.depthCapped is true and you narrow the filters instead.

Step 4: Choose the export columns

On Solo and above, POST /v1/exports writes a CSV. You pick the columns, a preset, or the size of numbered blocks. Up to 50,000 rows a request and 500,000 a day.

curl -s -X POST "https://api.leadocean.io/v1/exports" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "de-vp-sales-hubspot",
    "filters": {"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["DE"],"employeeRange":["51-200","201-500"],"technologies":["HubSpot"]},
    "limit": 100,
    "preset": "search"
  }' | jq '.data | {id, status, requested, perRow}'

Two presets exist: search (27 columns, no contact points) and full (45 columns, needs the enrich scope). To pick columns one by one, pass columns with ids from GET /v1/exports/columns, and set caps to choose how many numbered emails or phones each row carries. The create response reports perRow: 1 record per row, or 2 when the columns need an enrichment. The same builder is in the app: filter builder, column picker and the record price before you start.

What you get

The free count for the Step 2 filters, run through the MCP tool leadocean_count_leads on 2026-10-21:

{
  "total": 97,
  "totalIsExact": true,
  "totalAll": 289,
  "distinctCompanies": 75,
  "credits": 0
}

97 is the mailable count (verified, catch_all_valid or catch_all emails). Without an email condition the same filters match 289 people. The 97 people sit at 75 companies.

A search row, response shape from the API reference, placeholder values:

{
  "success": true,
  "data": [
    {
      "profile_data": { "profile_full_name": "Jane Doe" },
      "contact_data": {
        "has_email": true,
        "email_status": "verified",
        "contact_current_experiences": [{ "job_title": "VP Sales", "company_name": "Acme", "company_domain": "acme.com" }]
      },
      "meta": { "source_ids": { "person_id": "1234567890" } }
    }
  ],
  "meta": { "count": 25, "limit": 25, "credits": 25, "nextCursor": "opaque-cursor-string" }
}

Search rows carry email flags, not addresses. Numbered export columns are requested as email_N_address or phone_N_number, and the CSV headers come back as email_1_address and phone_1_number.

Troubleshooting

FAQ