List building

The job in one paragraph

List building means turning an ideal customer profile into rows you can contact: people at the right companies, in the right roles, with an address you can send to. You describe the audience as filters. You get back people, not a CSV of guesses. LeadOcean does this over REST, over a hosted MCP server and from the Exports page in the app. It does not run sequences or a dialer, so the list leaves LeadOcean as a file or an API response and goes to your own sending tool.

The workflow

1. Check the account. GET /v1/account (MCP: leadocean_get_account). Free. It shows how many records you have left.
2. Look up exact filter values. GET /v1/enums and GET /v1/filters (MCP: leadocean_list_enum_values, leadocean_list_filters). Free. Filter strings must match exactly.
3. Size the audience. POST /v1/people/search?count=true with "limit": 1, or leadocean_count_leads. Free. meta.total stops at 100,000, so a bigger list needs a narrower filter.
4. Preview a page. POST /v1/people/search (MCP: leadocean_search_leads). 1 record per person returned, up to 100 per page. Paginate with cursor. Check ten rows before you pull ten thousand.
5. Pull the full list. POST /v1/exports (MCP: leadocean_export_leads). 1 record per row, up to 50,000 rows per request. Request numbered columns such as email_1_address and email_1_status.
6. Fill phone gaps. GET /v2/people/phone (MCP: leadocean_find_phone). 1 record per call, even when it finds nothing.
7. Build the account side. POST /v1/companies/search (MCP: leadocean_search_companies). 1 record per company returned. Use it when you want accounts first and people second.

By default the count tool only counts people whose best email is verified, catch_all_valid or catch_all. The number you see describes the mailable audience, not everyone who matches the other filters.

curl -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":["Advertising & Marketing"],"country":["US"],"employeeRange":["51-200"],"limit":1}'

A worked example

The audience is VPs of marketing at US companies with 51 to 200 employees. On 1 October 2026 we ran leadocean_count_leads with jobLevel VP, jobFunction Advertising & Marketing, country US and employeeRange 51-200. It returned 5,910 people with a mailable email. The count cost 0 records.

Exporting all 5,910 rows is 5,910 records. Adding phones for 2,000 of them through GET /v2/people/phone is 2,000 more, miss or not. The total is 7,910 records.

On Free, the first 1,000 records are yours once, with no card. You could export the first 1,000 rows to test fit. On Pro the month is $499, flat, with no per-record price, inside fair use. See pricing.

Tools that fit

• Lead List Builder skill: Claude sizes, searches and exports a list from a plain-English brief.
• Audience Sizer skill: free counts only, to test a filter before you spend.
• Bulk Exporter skill: runs the export step with the column set you choose.
• Find companies by technology and find people by department: the filters behind two common list recipes.
• Build a lead list in Claude Code and the Claude Code setup: the MCP route, step by step.
• The Exports page in the app at app.leadocean.io: filter builder, column picker and the record price before you start. It has no sequencer, so you download the CSV and load it elsewhere.

To compare options, read the best lead list building tools and company list building APIs for B2B. For the term itself, see what is a lead list.

Pitfalls

• Stale data. The dataset is refreshed monthly, and each record carries its own fetched_at date. Rebuild a list that is older than a quarter, and drop rows with an old date before a big send.
• Catch-all emails. catch_all and catch_all_valid addresses accept any mail, so a send can still bounce. There is no refund for bounces. Read email_status and send to verified first.
• Rate limits and caps. The limit is 100 requests per second per key, on every plan. Exports stop at 50,000 rows per request and 500,000 rows per day. Split a larger list by country or seniority.
• Enum strings. Filter values are exact strings: jobLevel is C-Team, VP or Director, seniority is lowercase such as c_suite, and the department is Advertising & Marketing, not "Marketing & Advertising". Check leadocean_list_enum_values first.

FAQ