How to Enrich a List of LinkedIn URLs (in Python)

You can enrich a list of LinkedIn URLs in Python with one short script: read the URLs, call POST /v1/people/enrich for each, wait out any 429, and write the answers to a CSV. This guide gives you the script and explains each part.

TL;DR

• One Python file, 32 lines, one dependency (requests). It reads urls.txt and writes people.csv.
• Time: about 10 minutes to set up. At 4 requests a second, 1,000 URLs take at least 4 minutes.
• Cost: 1 LeadOcean record per URL we hold a match for. A miss is a 404 and is free, so the Free plan's 1,000 records cover up to 1,000 matches.

Prerequisites

• Python 3.9 or newer and pip install requests.
• A LeadOcean API key, exported as $LEADOCEAN_API_KEY. The Free plan gives you one with 1,000 records for life, no card.
• A urls.txt file with one LinkedIn profile URL per line.

Step 1: Get a key and prepare the list

Sign up at app.leadocean.io, create a key and put it in your shell. Never write the key into the source file.

export LEADOCEAN_API_KEY="your-key-here"
printf '%s\n' \
  "https://www.linkedin.com/in/jane-doe-acme" \
  "https://www.linkedin.com/in/john-roe-acme" > urls.txt

The enrich endpoint takes exactly one identifier per call: linkedin_url, email, phone or person_id. Enrich does not page. You make one call per URL, so "paging" here means walking your file line by line.

Step 2: Write the script

Save this as enrich.py. Requests go to https://api.leadocean.io with the x-api-key header.

import csv, os, time, requests

URL = "https://api.leadocean.io/v1/people/enrich"
HEADERS = {"x-api-key": os.environ["LEADOCEAN_API_KEY"]}

def enrich(session, linkedin_url):
    for _ in range(5):
        try:
            res = session.post(URL, headers=HEADERS, timeout=30,
                json={"linkedin_url": linkedin_url, "reveal_email": True})
        except requests.RequestException:
            time.sleep(1)
            continue
        if res.status_code == 429:
            time.sleep(max(int(res.headers.get("Retry-After", 1)), 1))
            continue
        return res.status_code, res.text
    return 0, "gave up after 5 tries"

def main():
    with open("urls.txt") as f:
        urls = [line.strip() for line in f if line.strip()]
    with open("people.csv", "w", newline="") as out, requests.Session() as s:
        writer = csv.writer(out)
        writer.writerow(["linkedin_url", "status", "json"])
        for u in urls:
            status, body = enrich(s, u)
            writer.writerow([u, status, body])
            time.sleep(0.25)

if __name__ == "__main__":
    main()

Three choices in that file matter:

• reveal_email: True returns the contact points on the record. It adds no extra record.
• The 0.25 second pause keeps you at 4 requests a second, under the Free plan's limit of 5.
• On a 429 the code reads Retry-After, sleeps that many seconds, and tries again, up to 5 times. See API rate limits and 429 errors.

Step 3: Run it

python3 enrich.py
head -3 people.csv

The status column tells you what happened per URL: 200 is a match, 404 is nobody found. Filter on it before you load rows anywhere else.

Step 4: Parse the fields you need

The CSV stores the raw JSON so you lose nothing. When you know which fields you want, parse each row with json.loads. The current role is in contact_current_experiences[] and phones are in contact_phones[].phone. Since October 2026 the same call also returns career history in resume_data: past roles, education, certifications and awards.

import csv, json

with open("people.csv") as f:
    for row in csv.DictReader(f):
        if row["status"] == "200":
            person = json.loads(row["json"])["data"]
            contact = person.get("contact_data") or {}
            emails = contact.get("contact_emails") or [{}]
            print(person["profile_data"].get("profile_full_name"),
                  contact.get("email_status"), emails[0].get("email"))

Past employers carry no company_id yet. If you need a company record, call POST /v1/companies/enrich with the domain.

What you get

The response shape from the API reference, with placeholder values. This is not a real person.

{
  "success": true,
  "data": {
    "profile_data": { "profile_full_name": "Jane Doe", "profile_headline": "VP Sales at Acme" },
    "contact_data": {
      "has_email": true,
      "email_status": "verified",
      "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" }]
    },
    "resume_data": { "experiences": [], "educations": [], "certifications": [] }
  },
  "meta": { "key_hash": "...", "fetched_at": "2026-10-01" }
}

Source: response shape from the API reference (openapi.json, October 2026), with field names from the enrich docs. Each record also carries a fetched_at date, and the dataset refreshes monthly.

Troubleshooting

FAQ