How to Build a Lead List (in Claude)

TL;DR

• Claude reaches LeadOcean through one custom connector URL. You size the audience for free, check a sample, then export a CSV.
• It takes about 20 minutes. The example spends about 260 records: 10 for the spot-check and 250 for the export. Bulk CSV export needs Solo ($97 a month) or above; on Free you page the rows with search.
• Counts, filter lookups and enum lookups cost 0 records. Only people you receive count.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card, 1,000 records one-off, and needs a work email.
• A Claude account that can add a custom connector. Per the Claude docs, October 2026, that covers Free, Pro, Max, Team and Enterprise. Free allows one custom connector, and Team and Enterprise limit who can add one.
• Optional, for the REST checks: curl and a key in your shell as $LEADOCEAN_API_KEY. The chat steps need no key.

export LEADOCEAN_API_KEY="paste-your-key-here"

Step 1: Add LeadOcean as a custom connector

Claude connects from Anthropic's cloud, so you add a public URL and sign in with OAuth. No key is pasted. On Pro and Max, go to Customize, then Connectors, then "+ Add", then "Add custom connector".

Name: LeadOcean
URL:  https://api.leadocean.io/mcp
Request headers: leave empty

Click "Continue", review the authentication settings, then "Add". Sign in on the LeadOcean page that opens and approve. Full click-by-click steps, including Team and Enterprise, are on Connect LeadOcean to Claude.

In a new chat, click "+" at the lower left, then "Connectors", and switch LeadOcean on. Claude asks before it runs a tool.

Step 2: Check your balance

Read the account before you spend anything. The account tool is free and shows your plan, records used and remaining, and your export ceilings.

Use the LeadOcean connector to read my account. Tell me how many records I have left
and my export limits. Do not search or export anything.

The REST route does the same with GET /v1/account, which also costs nothing.

curl -s https://api.leadocean.io/v1/account \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data.records'

Step 3: Size the audience for free

Write the audience as filters, then ask for a count. The example is VP-level sales leaders at US software companies with 51 to 200 staff. Ask Claude to resolve the exact industry string first.

Use leadocean_list_enum_values to confirm the exact industry value for software.
Then use leadocean_count_leads with jobLevel ["VP"], jobFunction ["Sales & Business
Development"], country ["US"], industry ["Software Development"], employeeRange
["51-200"]. Report the total and say which email statuses it counted.
Do not call any tool that spends records.

Filter values are exact strings. A value like "Software" returns nothing, so let Claude look it up. If the count is too big or too small, change one filter and count again.

The same sizing call over REST is a search with count=true as a query parameter and limit at 1. The body stays flat JSON with arrays.

curl -s "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": ["US"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 1
  }' | jq '.meta'

Step 4: Spot-check ten rows

Look at real rows before you buy hundreds. Ten records is a cheap test of whether the filters match the people you mean. A search returns thin records: name, headline, current role, company and location, plus email flags, not addresses.

Use leadocean_search_leads with the same filters and limit 10. Show a table of name,
job title, company and company domain. Flag any row that does not look like a sales
leader, and suggest an excludeTitle list to remove that noise. Do not pull more.

Each person returned costs one record, so this step spends 10. Add the suggested excludeTitle values to your filters, for example ["assistant","intern"], and keep them for the export.

Step 5: Export the list as a CSV

Use an export for the bulk pull instead of paging through the chat. A search page holds at most 100 people, and long tables are hard to read in a conversation. An export writes one file.

Start a LeadOcean export with the same filters, limit 250, preset full. Poll it with
leadocean_get_export until it is done, then give me the download link. Tell me the
record cost before you start.

Claude calls leadocean_export_leads, then leadocean_get_export. Each row costs one record, and the export reserves up to your limit when it starts. A request takes up to 50,000 rows and a day takes up to 500,000. Bulk CSV export is on Solo and above, not on Free. On Free, ask for leadocean_search_leads pages of 100 instead, at the same one record per person.

If you prefer the REST route, the same export is one request. It needs a key with the enrich scope, because the full preset reveals emails.

curl -s https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "US VP sales, software, 51-200",
    "filters": {
      "jobLevel": ["VP"],
      "jobFunction": ["Sales & Business Development"],
      "country": ["US"],
      "industry": ["Software Development"],
      "employeeRange": ["51-200"],
      "emailStatus": ["verified", "catch_all_valid", "catch_all"]
    },
    "limit": 250,
    "preset": "full"
  }' | jq '.data | {id, status, requested, remaining, pollAfter}'

The app does the same on its Exports page. It has a filter builder, a column picker, the record price before you start and a Download button.

What you get

The count in Step 3 is a real run. We ran it on 2026-10-01 with leadocean_count_leads, which spends 0 records, and it returned this (facets trimmed to the filters we sent).

{
  "total": 1603,
  "totalIsExact": true,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all), which is this tool's default.",
  "facets": {
    "country": [{ "value": "US", "count": 1603 }],
    "industry": [{ "value": "Software Development", "count": 1603 }],
    "seniority": [{ "value": "vp", "count": 1603 }],
    "company_size": [{ "value": "51-200", "count": 1603 }]
  },
  "unsupportedFilters": []
}

So 1,603 people matched on 2026-10-01 with a verified, catch_all_valid or catch_all email. That is a mailable count, not everyone we hold for those filters. Your number will differ as the data changes.

The export request returns a job. This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": {
    "id": "<export id>",
    "name": "US VP sales, software, 51-200",
    "status": "queued",
    "requested": 250,
    "perRow": "<1, or 2 when a column needs the full record>",
    "remaining": "<records left after this reservation>",
    "pollAfter": 10,
    "file": null
  }
}

The finished download is a .csv with one row per person. The full preset has 45 columns and up to three emails and two phones. Total spend for the run is 10 plus 250, so 260 records, unless perRow comes back as 2. The full 1,603 fits in one export on Solo or Agency.

Troubleshooting

FAQ