How to put a data enrichment API to work on revenue (five requests)

Enrichment pays for itself in five places: sizing a segment, scoring an inbound lead, routing by account, finding the buyers and backfilling the CRM. This guide runs one request for each against the LeadOcean API.

Competitor guides, such as Crustdata's use-case article (September 2026), explain the ideas in prose. This one is the version you can paste into a terminal.

TL;DR

• Five use cases, five requests: a free count, a person enrich, a company enrich, a people search plus enrich by id, and a CSV export.
• It takes about 30 minutes end to end.
• Steps 1 to 4 spend about 8 records and run on the free plan. The Step 5 export spends 100 and needs Solo ($97 a month) or above. The count costs nothing.

Prerequisites

• A LeadOcean API key from app.leadocean.io. The free plan has 1,000 records, one-off, no card.
• The key exported as $LEADOCEAN_API_KEY.
• curl and jq.
• Placeholders below (Jane Doe, acme.com) stand in for your own leads and accounts.

All requests go to https://api.leadocean.io with the header x-api-key. You are billed in records, one per person or company returned. See pricing.

Step 1: Size the segment before you spend anything

Counting first stops you buying a list that does not exist. This is the use case for territory planning and quota setting.

Send count=true and limit=1 as query parameters. The response has no rows and no cost.

curl -s -G "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "jobLevel=VP" \
  --data-urlencode "jobFunction=Sales & Business Development" \
  --data-urlencode "country=US" \
  --data-urlencode "employeeRange=201-500" \
  --data-urlencode "count=true" \
  --data-urlencode "limit=1" | jq '.meta | {total, totalIsExact, countOnly}'

Enum values are exact strings. If a filter returns nothing, check the list with GET /v1/enums/job_level first.

Read meta.total as a ceiling on what you can pull, not a forecast of what you will close. It is capped at 100,000, and totalIsExact tells you when it is a floor. Run it for each region before you set a quota. If one region comes back at a few hundred, you have found a coverage gap before a rep did.

Step 2: Score an inbound lead from one email

A form fill gives you an email and little else. One enrich call tells you whether the person is real, what they do and whether the address is safe to send to. This is lead scoring.

Send exactly one of linkedin_url, email, phone or person_id.

curl -s -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"email": "jane.doe@acme.com"}' \
  | jq '.data.contact_data | {has_email, has_phone, email_status, email_type}'

email_status is a verification result. Score verified and catch_all_valid as safe. Treat risky and role as a manual check. A person we hold nothing for is a 404 and costs nothing.

Wire this to your form handler. Call enrich on submit, write email_status and email_type to the lead record, and set the lead score from them. A work_other address usually belongs to a former employer, so do not score it as a work email. Free-mail signups with a personal type go to a nurture queue, not to a rep.

Step 3: Route the account by company fit

Routing fails when the rep sees a person but not the company. Look the company up by domain and decide the queue from what comes back. This is account scoring and territory routing.

curl -s -X POST "https://api.leadocean.io/v1/companies/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain": "acme.com"}' \
  | jq '{industries: .data.company_data.company_industries,
         marketability: .data.company_metrics.marketability_score,
         technologies: [.data.company_detected_technologies[]?.technology_product]}'

The company record carries industry, headcount band, funding where known, detected website technologies and a marketability_score. Route on the fields you trust. Funding is held for a small share of companies, so never make it the only rule.

A workable first rule has two lines. Send accounts above your chosen marketability_score cutoff to the named-account queue. Send accounts whose detected technologies match your integration list to the partner-led queue. Pick the cutoff by looking at fifty of your own closed deals, not by copying ours.

Step 4: Find the buyers at a hot account

An account that scores high needs a named buyer. Search the domain for the roles you sell to, then enrich the one you pick by person_id. This is contact discovery for account-based plays.

Search first. It returns thin rows with has_email flags and costs one record per row.

curl -s -X POST "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain": ["acme.com"],
       "jobLevel": ["C-Team", "VP", "Director"],
       "jobFunction": ["Sales & Business Development"],
       "emailStatus": ["verified"],
       "emailType": ["work"],
       "limit": 5}' > buyers.json

jq -r '.data[0].meta.source_ids.person_id' buyers.json

Then enrich that id and reveal the contact points. reveal_email costs no extra record.

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\": \"$(jq -r '.data[0].meta.source_ids.person_id' buyers.json)\", \"reveal_email\": true}" \
  | jq '.data.contact_data.contact_emails[0], .data.contact_data.contact_phones[0].phone'

To list everyone we hold at one company instead, use GET /v1/companies/{domain}/people. It stops at 10,000 rows.

Search rows publish has_email and has_phone flags, not the addresses. Skip any row where both are false before you enrich, because there is nothing to return. That check is the cheapest filter you have, and it keeps the enrich step to one record per real buyer.

Step 5: Backfill the CRM with one export

A CRM full of half-empty contacts needs a bulk pull, not a loop of single calls. POST /v1/exports runs a search as a CSV job. This is CRM backfill. Bulk CSV export is included on Solo and Agency, not on Free. On Free, page the Step 4 search instead.

curl -s -X POST "https://api.leadocean.io/v1/exports" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "vp-sales-us-201-500",
       "filters": {"jobLevel": ["VP"],
                   "jobFunction": ["Sales & Business Development"],
                   "country": ["US"],
                   "employeeRange": ["201-500"],
                   "emailStatus": ["verified"]},
       "limit": 100,
       "preset": "full",
       "caps": {"emails": 1, "phones": 1}}'

Poll GET /v1/exports/{id} until status is done, then call GET /v1/exports/{id}/download. The call reserves up to limit records and bills each row written. One export takes up to 50,000 rows, and an account takes 500,000 a day.

Match the CSV to your CRM on email or on person_id, and overwrite only the empty fields. Numbered columns come back as email_1_address, email_1_status and phone_1_number. Import email_1_status too, so your CRM can suppress anything that is not verified before the first send. Bounced emails are not refunded, so the status column is your protection.

What you get

Step 1 ran on 1 October 2026 through the free leadocean_count_leads MCP tool, with the same filters:

{
  "total": 11207,
  "totalIsExact": true,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all)"
}

That is 11,207 mailable US VPs of sales at companies with 201-500 employees. It is a mailable count, not everyone matching the filters.

For the record-level steps, this is the response shape from the API reference, with placeholder values:

{
  "success": true,
  "data": {
    "profile_data": { "...": "identity, headline, current role" },
    "contact_data": {
      "has_email": true,
      "has_phone": true,
      "email_status": "verified",
      "email_type": "work",
      "contact_emails": [
        { "email": "jane.doe@acme.com", "type": "work", "status": "verified" }
      ],
      "contact_phones": [{ "phone": "+14155550133", "type": "mobile" }]
    },
    "meta": { "schema": "leadocean.person.v1", "fetched_at": "<date>" }
  }
}

contact_emails and contact_phones appear only when you send reveal_email: true.

Troubleshooting

FAQ