How to Build an Enrichment Stack for Client Campaigns (8 Steps, One API)

Agencies do not need eight vendors to enrich a client list. They need eight jobs done in the right order: size, find, expand, enrich, verify, call, export, repeat. This guide runs all eight against one API.

TL;DR

• Eight calls take a client brief to a mailable list: two free sizing calls, then search, roster, enrich, work email, phone and export.
• The walkthrough takes about 45 minutes and spends about 40 records, which fits the Free plan's 1,000.
• Sizing is free. A count, a 404 and an empty page cost nothing, so you only spend on rows you will use.

Prerequisites

• A LeadOcean account. Free is $0 with 1,000 records for life, no card, 5 requests a second.
• An API key in your shell: export LEADOCEAN_API_KEY=...
• curl and jq. For Claude or another MCP client, the hosted server is at https://api.leadocean.io/mcp.
• A client brief with a target: here, US marketing agencies with 11 to 50 staff, and their C-level contacts.

Every request goes to https://api.leadocean.io with the header x-api-key.

Step 1: Size the company list (free)

Use GET /v1/companies/count before you touch a search. It takes the company-search filters and returns an exact total with breakdowns. It costs no records.

curl -s -G "https://api.leadocean.io/v1/companies/count" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "industry=Marketing Services" \
  --data-urlencode "hqCountry=US" \
  --data-urlencode "employeeRange=11-50"

The MCP equivalent is leadocean_count_companies. If the total is wrong for the client, change the filters now. It is the cheapest edit in the whole workflow.

Step 2: Size the people list (free)

Count the contacts at those companies. Send count=true as a query parameter with limit=1. The JSON body rejects unknown fields.

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 '{"industry":["Marketing Services"],"jobLevel":["C-Team"],"country":["US"],"employeeRange":["11-50"],"limit":1}'

meta.total is capped at 100,000 and meta.countOnly is true. The MCP tool leadocean_count_leads also reports distinctCompanies, which tells you how many employers the people span.

Step 3: Search companies

Pull the company records you want to work. Each company returned is one record. Start with 10 to check the shape.

curl -s -X POST "https://api.leadocean.io/v1/companies/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"industry":["Marketing Services"],"hqCountry":["US"],"employeeRange":["11-50"],"limit":10}'

The body is flat JSON. Filters are arrays of strings. Enum values are exact strings, so resolve them first with GET /v1/enums or the MCP tool leadocean_list_enum_values. Page with meta.nextCursor.

Step 4: Pull the people at each company

For one target account, list the people we hold at the domain. This is thin data: names, titles, ids. Contact points come later.

curl -s "https://api.leadocean.io/v1/companies/acme.com/people?limit=25" \
  -H "x-api-key: $LEADOCEAN_API_KEY"

One record is billed per person returned. A roster stops at 10,000 rows and sets meta.depthCapped to true on the last page. To find a specific buyer across many companies, use people search with jobLevel and jobFunction instead.

Step 5: Enrich one person

Enrichment takes exactly one of linkedin_url, email, phone or person_id. Search rows carry meta.source_ids.person_id. Send it back to enrich that exact person.

curl -s -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"person_id":"1234567890","reveal_email":true}'

There is no name plus domain lookup. Search by domain first, then enrich by person_id. Since 17 October 2026 the response also carries resume_data: past roles, education, certifications and awards. That helps an agency write a first line that is not generic. A person we hold nothing for is a 404 and costs nothing.

Step 6: Get a verified work email

When you only need the address, call the v2 endpoint. It returns one address or data: null, and only addresses that were checked: verified, catch_all_valid or catch_all.

curl -s "https://api.leadocean.io/v2/people/email/work?person_id=1234567890" \
  -H "x-api-key: $LEADOCEAN_API_KEY"

The v2 contact endpoints cost one record per call, including a call that finds nothing. Search with hasEmail=true or an emailStatus filter first so you do not pay for misses. We do not refund bounces, so read email_status before you send.

Step 7: Get phone numbers

Some client campaigns need a call list. GET /v2/people/phone returns every number we hold, best first, each with a type of mobile, direct or office.

curl -s "https://api.leadocean.io/v2/people/phone?person_id=1234567890" \
  -H "x-api-key: $LEADOCEAN_API_KEY"

Filter with hasPhone=true in search to find people who have a number before you spend. The v2 response does not include a do-not-call flag, so run your own suppression check.

Step 8: Export the list

When the client list is final, export it in one request instead of paging by hand. POST /v1/exports takes the same filters as people search, 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":"acme-client-q4","limit":2000,"preset":"full",
       "filters":{"industry":["Marketing Services"],"jobLevel":["C-Team"],"country":["US"],"employeeRange":["11-50"],"emailStatus":["verified"]}}'

Poll GET /v1/exports/{id}, then call /v1/exports/{id}/download. Every row costs one record. Bulk CSV export is not on Free. It is included on Solo, and Agency allows 50k rows a file. You can also run it from the Exports page in app.leadocean.io, which shows the record price before you start.

What you get

Free counts run on 21 October 2026 for the brief above. People count, leadocean_count_leads: industry Marketing Services, jobLevel C-Team, country US, employeeRange 11-50. It counts verified, catch_all_valid and catch_all emails by default, so it is a mailable-people count.

{
  "total": 3254,
  "totalIsExact": true,
  "totalAll": 8327,
  "distinctCompanies": 1701,
  "credits": 0
}

Company count, leadocean_count_companies: industry Marketing Services, hqCountry US, employeeRange 11-50 (top three states shown, trimmed).

{
  "total": 5351,
  "totalIsExact": true,
  "facets": { "hq_state": [
    { "value": "California", "count": 972 },
    { "value": "Florida", "count": 562 },
    { "value": "New York", "count": 460 }
  ]},
  "credits": 0
}

Both calls cost 0 records. The gap between 3,254 mailable and 8,327 total is the people without a checked address.

Response shape from the API reference, with placeholder values, for step 5:

{
  "success": true,
  "data": {
    "profile_data": { "profile_full_name": "Jane Doe" },
    "contact_data": {
      "has_email": true,
      "email_status": "verified",
      "contact_emails": [{ "email": "jane@acme.com", "type": "work", "status": "verified" }],
      "contact_phones": [{ "phone": "+1 415 555 0133" }]
    },
    "resume_data": {}
  },
  "meta": {}
}

Troubleshooting

FAQ