How to Find Lookalikes You Can Actually Trust (With the LeadOcean API)

TL;DR

• A lookalike list is trustworthy when you can name every filter behind it and see the matching field on every row. LeadOcean returns filter matches, not a similarity score.
• It takes about 10 minutes. The run spends about 26 records: 1 for the seed, 25 for one page of companies.
• Sizing, enum lookups and the account read are free. You only pay for rows you receive.

Prerequisites

• A LeadOcean account and API key from app.leadocean.io. The free plan has no card and 1,000 records, one-off. The key needs the enrich and search scopes, which Free keys get.
• The key in your shell as $LEADOCEAN_API_KEY.
• curl and jq. Prefer an agent? The same steps work over the hosted MCP server at https://api.leadocean.io/mcp.

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

Step 1: Enrich the seed company

Start from one company you already sell to and read its fields. A lookalike is only as good as the seed profile, so check that profile first. This call costs 1 record, and a domain we hold nothing for is a 404 that costs nothing.

curl -s https://api.leadocean.io/v1/companies/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"domain": "acme.com"}' \
  | jq '.data.company_data | {
      name: .company_name,
      domain: .company_domain,
      industries: [.company_industries[].name2],
      band: .company_employees.number_of_employees_code,
      hq: .company_primary_address.country_code
    }'

Write down three things: the industry, the headcount band and the headquarters country. Fields we hold nothing for come back null. If the band or country is null, you cannot copy it into a filter, so pick the value by hand.

Step 2: Turn the seed into exact filter values

Filter values are exact strings, and a guessed value is the most common reason a lookalike search returns nothing. Resolve each one against the closed list before you search. The lookup is free.

curl -s "https://api.leadocean.io/v1/enums/industry?q=software" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq

Over MCP, the same lookup is a tool call.

Use leadocean_list_enum_values with name "industry" and q "software". Do not call any tool that spends records.

The headcount filter employeeRange takes one of eight bands: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000 and 10001+. The country filter hqCountry takes an ISO 3166-1 alpha-2 code such as US. A band is broader and cheaper than minEmployees and maxEmployees, which skip any company with no headcount on file.

Step 3: Size the list for free

Count before you buy. Send count=true as a query parameter with limit set to 1. You get meta.total and an empty data, and no records are spent however often you ask.

curl -s "https://api.leadocean.io/v1/companies/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "hqCountry": ["US"],
    "limit": 1
  }' | jq '.meta | {total, totalIsExact, totalWithheld}'

Read three fields. total is capped at 100,000. totalIsExact is false when it is a floor. totalWithheld appears when a filter could not be applied, and then total is null instead of a number that lies.

That last field is the trust check. If totalWithheld names a filter, the rows would ignore it, so drop it or narrow another way and count again.

For a company count with breakdowns, call GET /v1/companies/count with the same filters. It is free, returns no rows and splits the total by industry, headcount band, HQ country, HQ state and NAICS.

curl -s "https://api.leadocean.io/v1/companies/count?industry=Software%20Development&employeeRange=51-200&hqCountry=US" \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq

Over MCP the same call is leadocean_count_companies. On 21 October 2026 it returned 9,261 companies for Software Development, 51-200 employees, HQ in the US, with California the largest state at 2,398.

Step 4: Pull one page and verify every row

Now buy one page. Search takes the same filters as the count, with limit up to 100. Add excludeName for the seed's name, and drop the seed by domain in the output in case another record shares it.

curl -s https://api.leadocean.io/v1/companies/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "hqCountry": ["US"],
    "excludeName": ["Acme"],
    "limit": 25
  }' | tee page1.json | jq -r '.data[].company_data
    | select(.company_domain != "acme.com")
    | [.company_name, .company_domain,
       .company_employees.number_of_employees_code,
       .company_primary_address.country_code] | @tsv'

This costs 25 records, one per company returned. The table is the audit. Every row shows the band and country that matched, so a wrong row is visible before anyone writes to it.

A page that has more rows carries meta.nextCursor. Pass it back unchanged as cursor to get page two. A cursor is tied to one filter set, so change a filter and you start a new search.

Step 5: Widen or narrow one filter at a time

Change one filter per run and recount, so you know which filter did what. Drop the country to widen. Add keywords or technologies to narrow, then count again before you pull.

Here is the pattern with real numbers. These are free MCP counts of mailable C-Team and VP people at the matching companies, not company counts. Each added filter shrinks the list.

Counted 1 October 2026. Your numbers will differ as the data changes.

When the people are what you need, size them for free before pulling. Pass the lookalike domains to the people search with count=true and limit 1. For a big pull, a people export takes up to 50,000 rows a request and 500,000 a day through POST /v1/exports.

curl -s "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "domain": ["example-one.com", "example-two.com", "example-three.com"],
    "jobLevel": ["C-Team", "VP"],
    "limit": 1
  }' | jq '.meta.total'

What you get

Step 2 returns the closed list for the industry search. This is the real MCP output on 1 October 2026 for industry with q set to "software":

{"name":"industry","description":"Company industry. One of 534 normalised values.","total":534,"matched":7,"values":["Computer Software","Data Security Software Products","Desktop Computing Software Products","Embedded Software Products","IT System Custom Software Development","Mobile Computing Software Products","Software Development"],"truncated":false}

Seven industries contain "software". Pick one, or pass several, because values inside one filter join with OR.

Step 3 returns an envelope with no rows. This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": [],
  "meta": {
    "count": 0,
    "limit": 1,
    "total": "<number, capped at 100000>",
    "totalIsExact": true,
    "countOnly": true
  }
}

Step 4 returns one record per company in the leadocean.company.v1 shape. This is the response shape from the API reference, trimmed to the fields used above, with placeholder values.

{
  "success": true,
  "data": [
    {
      "company_data": {
        "company_name": "Acme",
        "company_domain": "acme.com",
        "company_employees": { "number_of_employees_code": "51-200" },
        "company_primary_address": { "country_code": "US" }
      },
      "company_metrics": { "completion_score": "<0-100>", "marketability_score": "<0-100>" },
      "meta": { "schema": "leadocean.company.v1" }
    }
  ],
  "meta": { "count": 25, "limit": 25, "credits": 25, "nextCursor": "<opaque string>" }
}

Troubleshooting

FAQ