How to Enrich a CSV of Contacts (in Cursor)

TL;DR

• Add the LeadOcean MCP server to Cursor, 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 of your 1,000 free records. The real number is the count of matched rows.

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.
• Cursor, 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 remote server to mcp.json. Use ~/.cursor/mcp.json for every project or .cursor/mcp.json for one. The Cursor MCP docs, October 2026, show remote servers as a url entry.

{
  "mcpServers": {
    "leadocean": {
      "url": "https://api.leadocean.io/mcp"
    }
  }
}

Save the file and start the sign-in for leadocean from Cursor's MCP list. Your browser opens on LeadOcean for an OAuth sign-in. No key goes into the file. Our OAuth server supports dynamic client registration, so you add no client ID.

Then confirm the tools loaded. Cursor should list all 13 LeadOcean tools. The full walkthrough, with sign-in and troubleshooting, is on Connect LeadOcean to Cursor.

Step 2: Put your contacts in a CSV

Keep the file 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 first 25 rows in pilot.csv, so the first run stays cheap.

Step 3: Pilot 25 rows in chat

Run a small batch first. The pilot gives you the match rate and shows whether your identifiers work, before you commit the whole file. Paste this into Cursor's agent chat.

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.

Cursor asks you to approve MCP tool calls. Read the arguments before you accept. 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.

Chat suits a few dozen rows. Past that, each row is a model turn, and a script is faster and cheaper.

Open pilot_enriched.csv before you go on. Check the match rate first: if most rows came back empty, your identifiers are the problem, not the data. Then read email_status, which tells you how much of the file is safe to send.

Step 4: Run the full file with a script

Send one enrich request per row. Set reveal_email to true to get the addresses and phones we hold, at no extra record. You can paste this script into a file, or ask Cursor's agent to create it for you.

This version is resumable. It appends to enriched.csv and skips any row already written, so a stop on a 402 loses nothing.

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

KEY = os.environ["LEADOCEAN_API_KEY"]
URL = "https://api.leadocean.io/v1/people/enrich"
COLS = ["result", "email_status", "best_email", "best_phone"]

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

def ident(row):
    return row.get("email") or row.get("linkedin_url") or row.get("first_name", "") + row.get("last_name", "")

done = set()
if os.path.exists("enriched.csv"):
    with open("enriched.csv", newline="") as g:
        done = {ident(r) for r in csv.DictReader(g)}

with open("contacts.csv", newline="") as f:
    rows = list(csv.DictReader(f))
fields = list(rows[0].keys()) + COLS
fresh = not os.path.exists("enriched.csv")

matched = 0
with open("enriched.csv", "a", newline="") as g:
    out = csv.DictWriter(g, fieldnames=fields)
    if fresh:
        out.writeheader()
    for row in rows:
        key = ident(row)
        if key in done:
            continue
        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 this run. Records spent: {matched}.")

Run it with python3 enrich.py. The final line is your record cost for that run. To run it again after a stop, change nothing. It picks up where it left.

The script sends one request at a time, below even the Free rate of 5 requests a second. It writes a row for every input, so a failed run still leaves a file you can compare against contacts.csv.

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. Safe to send: verified and catch_all_valid. Do not send to invalid, spam_trap, abuse or disposable. Treat role, risky and derived with care. Bounces are not refunded.

Read the status on the enriched record, not in a search row. Search can show verified for a person who enriches as untested, and the enriched answer is the correct one.

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.

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

We did not run a paid enrichment for this page, so there is no measured match rate here. Your cost is the matched count the script prints.

Troubleshooting

FAQ