How to Enrich a CSV of Contacts (in Gemini CLI)

TL;DR

• Add the LeadOcean MCP server to Gemini CLI, test 25 rows in the terminal, 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.
• Gemini CLI, Python 3 and curl.
• A browser on the same machine. The Gemini CLI docs, October 2026, say OAuth sign-in opens a local browser and receives a redirect on a localhost port. It does not work over plain SSH.
• 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 LeadOcean as a remote HTTP server with one command. The Gemini CLI docs, October 2026, give the form gemini mcp add --transport http <name> <url>. Add --scope user to load it in every project. The default scope is the current project.

gemini mcp add --transport http --scope user leadocean https://api.leadocean.io/mcp

Do not pass an --header flag. LeadOcean's MCP server signs you in with OAuth 2.1, so no key goes into the config. Our OAuth server supports dynamic client registration, so you add no client ID.

Start gemini, then run these two slash commands. The first opens your browser on LeadOcean. The second lists the server and its tools.

/mcp auth leadocean
/mcp

Gemini CLI should list all 13 LeadOcean tools. The setup for every client, Gemini CLI included, is on MCP for agents.

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 folder where you start Gemini CLI. 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 the terminal

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 prompt into Gemini CLI.

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.

Gemini CLI asks you to confirm MCP tool calls unless a server is marked trusted. Do not set trust on this server. 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 Gemini CLI 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.

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. Since October 2026 a match also carries resume_data: past roles, education, certifications and more, each when we hold it. Past employers carry no company_id yet.

{
  "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 }
      ]
    },
    "resume_data": {
      "experiences": ["<past roles: title, company name, start and end dates, job level>"],
      "educations": ["<schools and degrees>"]
    }
  },
  "meta": { "source": "leadocean", "key_hash": "<cache key>" }
}

If you later search instead of enriching, filter values are exact strings. We read the job levels from the free leadocean_list_enum_values tool on 2026-10-21.

{
  "name": "job_level",
  "total": 6,
  "values": ["C-Team", "Director", "Manager", "Other", "Staff", "VP"]
}

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