How to Enrich a Lead (From One Email to a Full Record)

Lead enrichment is the step where you take a lead with one or two fields and fill in the rest from a data provider. You send an email or a LinkedIn URL, you get back title, company, location and contact details.

TL;DR

• Enrichment takes one identifier (email, LinkedIn URL, phone or person ID) and returns a full record. It is one API call.
• This walkthrough takes about 20 minutes and spends about 27 LeadOcean records. The free plan has 1,000 for life.
• Size the list first with a free count, enrich second, and read email_status before you send anything.

Prerequisites

• A LeadOcean account on the free plan: app.leadocean.io/register. No card.
• An API key exported as $LEADOCEAN_API_KEY.
• curl and jq. Any HTTP client works the same way.
• One lead you already hold: a work email or a LinkedIn URL.

What counts as enrichment

Enrichment fills gaps. It is not the same as prospecting, where you search a database for people you do not hold yet.

Most teams need both. Search finds the account's people, enrichment completes the ones you already have from a form, a CRM or an event list.

What gets added, and why it matters

Most forms capture a name and an email. That is not enough to route, score or personalise a lead. Enrichment adds the fields your process needs.

• Person: job title, job level, job function, location, LinkedIn URL, work email with a status, phone numbers.
• Company: industry, headcount, HQ country, funding, detected technologies.
• History: past roles, education and certifications, since October 2026.

The payoff is practical. Routing rules need company size. Scoring needs seniority. Outreach needs a deliverable address. If a field is blank, the rule fails or the lead sits unworked.

Two cautions. Enriched data is a snapshot, so check fetched_at and re-enrich old rows before a big send. And match rate is not accuracy: a returned email can still be risky or catch_all, so filter on email_status.

Step 1: Size the list before you spend anything

Count first. A count tells you whether the audience exists and costs no records.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true&limit=1" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobLevel": ["VP"],
    "jobFunction": ["Sales & Business Development"],
    "country": ["DE"]
  }' | jq '.meta'

count=true goes in the query string, not the JSON body. The body is flat JSON and every filter is an array of strings. meta.total is capped at 100,000.

Enum values are exact strings. If a filter returns nothing, check the allowed values with the free GET /v1/enums call or the leadocean_list_enum_values MCP tool.

Step 2: Enrich one lead

Pick the identifier you hold. The endpoint takes 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",
    "reveal_email": true
  }' | jq .

There is no name plus domain lookup. If you only have a name and a company, search by domain first, then enrich by person_id.

A person we hold nothing for returns 404 and costs nothing. A hit costs one record.

Step 3: Enrich the company

Company enrichment works the same way on the account side. Send a domain.

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 .

To size a company list before you pull it, use GET /v1/companies/count. It is free and returns an exact total with breakdowns by industry, headcount band, HQ country and HQ state.

Step 4: Find the rest of the buying group

Enrichment on one contact rarely closes the account. Pull the other people at the same company.

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

This returns up to 25 people, one record each, as thin rows without contact points. Use cursor to page. The roster stops at 10,000 rows with meta.depthCapped true. It takes no role filters, so to pull only buyers, run POST /v1/people/search with domain plus jobLevel and jobFunction.

Step 5: Do it in bulk

For a list of a few thousand rows, loop over your identifiers and respect the rate limit: 5 requests a second on Free, 50 on Solo, 200 on Agency. Above it you get a 429 with a Retry-After header.

while read -r email; do
  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\": \"$email\"}" >> enriched.jsonl
  sleep 0.25
done < emails.txt

For whole segments rather than known leads, use POST /v1/exports. It takes up to 50,000 rows a request and 500,000 a day. Bulk CSV export is not on the free plan. The app at app.leadocean.io has an Exports page with a filter builder, a column picker and a price preview before you download.

If you work from an AI client, the hosted MCP server at https://api.leadocean.io/mcp exposes 13 tools, including free count and filter tools, with OAuth sign-in and no key to paste.

What you get

The Step 1 count, run on 2026-10-21 with the free MCP tool leadocean_count_leads (jobLevel VP, jobFunction Sales & Business Development, country DE). It spent 0 records.

{
  "total": 1395,
  "totalIsExact": true,
  "totalAll": 3893,
  "distinctCompanies": 905
}

total counts people whose best email is verified, catch_all_valid or catch_all, the tool's default. totalAll is the same filters with no email condition.

Step 2 returns one person. This is the response shape from the API reference, with placeholder values. It is not a real record.

{
  "success": true,
  "data": {
    "profile_data": { "profile_full_name": "Jane Doe" },
    "contact_data": {
      "has_email": true,
      "email_status": "verified",
      "email_type": "work",
      "contact_emails": [
        { "email": "jane.doe@acme.com", "type": "work", "status": "verified" }
      ],
      "contact_phones": [{ "phone": "+1 415 555 0133", "type": "mobile" }],
      "contact_current_experiences": [
        { "job_title": "VP Sales", "company_name": "Acme", "company_domain": "acme.com" }
      ]
    },
    "resume_data": { "experiences": [], "educations": [], "certifications": [] },
    "meta": { "fetched_at": "2026-10-01", "schema": "leadocean.person.v1" }
  }
}

Since October 2026, person enrichment also returns career history in resume_data: past roles, education, certifications and awards, each when we hold it. Past employers do not carry a company_id yet.

Read email_status before you send. It has 13 values, from verified to spam_trap. There is no refund for bounced emails.

The dataset refreshes monthly, and each record carries its own fetched_at date.

Troubleshooting

FAQ