How to Enrich a CSV of Contacts (in VS Code)

TL;DR

• Add the LeadOcean MCP server to VS Code, test 25 rows in chat, then run the full file with a short Python script against POST /v1/people/enrich.
• It takes about 20 minutes. Each person we match spends one record. A person we hold nothing for is a 404 and costs nothing.
• A 200-row file spends at most 200 records, which fits inside the 1,000 free ones. Your real number depends on how many rows match.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card and 1,000 records, one-off. Its keys get both the search and enrich scopes.
• An API key in your shell as $LEADOCEAN_API_KEY. The chat steps use OAuth and need no key. The script step does.
• VS Code with chat set up, Python 3 and curl.
• A CSV with one identifier per row: an email or a linkedin_url. Enrich takes exactly one of linkedin_url, email, phone or person_id. There is no name plus company lookup.

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

Step 1: Connect the LeadOcean MCP server

Add one http server to .vscode/mcp.json. VS Code starts it, opens a browser sign-in, and lists the tools. No key is pasted into the file.

{
  "servers": {
    "leadocean": {
      "type": "http",
      "url": "https://api.leadocean.io/mcp"
    }
  }
}

The VS Code MCP docs, October 2026, say to review tool approval requests as they appear. Open Configure Tools in the chat input to see all 13 LeadOcean tools. The full walkthrough, with sign-in and troubleshooting, is on Connect LeadOcean to VS Code.

Step 2: Put your contacts in a CSV

Keep the file small and plain. Use a header row, one person per row, and no commas inside fields. The identifier column is what we match on. Name and company are for your own checking.

first_name,last_name,company,email,linkedin_url
Jane,Doe,Acme,jane.doe@acme.com,
John,Roe,Example Corp,,https://www.linkedin.com/in/john-roe-example

Save it as contacts.csv in the project. These rows are placeholders. Put your own 25 in a second file, pilot.csv, so the first run stays cheap.

Step 3: Pilot 25 rows in chat

Run a small batch first. The pilot tells you the match rate and shows whether your identifiers work, before you commit the whole file.

Read pilot.csv. For each row, call leadocean_get_lead with the email, or the
linkedin_url when there is no email. Stop after 25 rows. Write pilot_enriched.csv
with the original columns plus job title, company, email_status and has_phone.
Skip rows with no identifier. Do not call any other LeadOcean tool that spends
records. At the end, tell me how many rows matched and how many returned nothing.

A leadocean_get_lead call that finds nobody costs nothing, the same as the REST 404. Every match costs one record, so 25 rows spend at most 25. The agent counts matches for you. Check that figure against GET /v1/account in Step 5.

Chat is the right tool up to a few dozen rows. Past that, each row is a model turn, and a script is faster and cheaper.

Read the output file before you go on. Look at three things. First, the match rate: if most rows came back empty, your identifiers are the problem, not the data. Second, the email_status column: it tells you how much of the file is safe to send. Third, whether the job titles are current enough for your use. Fix the CSV, not the prompt, if rows failed.

Step 4: Run the full file with a script

Send one enrich request per row. Pass reveal_email as true to get the addresses and phones we hold, at no extra record. The script writes enriched.csv and stops on a 402 so it never loops against an empty balance.

import csv, json, os, time, urllib.request, urllib.error

KEY = os.environ["LEADOCEAN_API_KEY"]
URL = "https://api.leadocean.io/v1/people/enrich"

def enrich(body):
    req = urllib.request.Request(
        URL, data=json.dumps(body).encode(), method="POST",
        headers={"x-api-key": KEY, "content-type": "application/json"})
    try:
        with urllib.request.urlopen(req) as r:
            return r.status, json.load(r)
    except urllib.error.HTTPError as e:
        if e.code == 429:
            time.sleep(int(e.headers.get("Retry-After", "1")))
            return enrich(body)
        return e.code, None

with open("contacts.csv", newline="") as f, open("enriched.csv", "w", newline="") as g:
    rows = csv.DictReader(f)
    out = csv.DictWriter(g, fieldnames=rows.fieldnames + [
        "result", "email_status", "best_email", "best_phone"])
    out.writeheader()
    matched = 0
    for row in rows:
        body = {"reveal_email": True}
        if row.get("email"):
            body["email"] = row["email"]
        elif row.get("linkedin_url"):
            body["linkedin_url"] = row["linkedin_url"]
        else:
            out.writerow({**row, "result": "no_identifier"})
            continue
        code, data = enrich(body)
        if code == 402:
            print("Out of records. Stopping.")
            break
        if code != 200:
            out.writerow({**row, "result": "not_found" if code == 404 else f"http_{code}"})
            continue
        matched += 1
        c = data["data"].get("contact_data", {})
        emails, phones = c.get("contact_emails") or [], c.get("contact_phones") or []
        out.writerow({**row, "result": "matched",
                      "email_status": c.get("email_status") or "",
                      "best_email": emails[0]["email"] if emails else "",
                      "best_phone": phones[0]["phone"] if phones else ""})
    print(f"Matched {matched} rows. Records spent: {matched}.")

Run it with python3 enrich.py. The script prints the match count when it finishes. That count is your record cost.

Two details keep the run safe. The script sends one request at a time, so it stays inside the Free plan's 5 requests a second. It also writes a row for every input, so a failed run still leaves a file you can compare against contacts.csv. Rows with no identifier are marked no_identifier and cost nothing. To resume after a 402, remove the rows already done from contacts.csv and run it again.

Step 5: Check the cost, then check the statuses

GET /v1/account is free. It returns records used and remaining, so you can compare it with the script's count.

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

Then filter on email_status before you send anything. Read the status on the enriched record, not in a search row. Search counts verified more loosely, so the enriched answer is the correct one. Do not send to invalid, spam_trap, abuse or disposable. Bounces are not refunded.

What you get

The output is enriched.csv: your original columns plus result, email_status, best_email and best_phone. Rows with no match say not_found and spent nothing. This is the shape of a matched row, with placeholder values.

first_name,last_name,company,email,linkedin_url,result,email_status,best_email,best_phone
Jane,Doe,Acme,jane.doe@acme.com,,matched,verified,jane.doe@acme.com,+14155550133
John,Roe,Example Corp,,https://www.linkedin.com/in/john-roe-example,not_found,,,

Each enrich call returns this response shape from the API reference, with placeholder values. The contact_emails and contact_phones arrays appear only when reveal_email is true.

{
  "success": true,
  "data": {
    "profile_data": { "...": "name, headline, current role, company" },
    "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", "priority": 1 }
      ]
    }
  },
  "meta": { "source": "leadocean", "key_hash": "<cache key>" }
}

Statuses are exact strings. We read the list from the free leadocean_list_enum_values tool on 2026-10-21 (description and labels trimmed).

{
  "name": "email_status",
  "total": 13,
  "matched": 13,
  "values": ["verified","catch_all_valid","catch_all","risky","unknown","untested",
             "invalid","role","disposable","spam_trap","abuse","derived","none"],
  "truncated": false
}

Troubleshooting

FAQ