LeadOcean API documentation — search, enrich and verify 700M+ profiles

Quickstart

Create an account and a key is waiting for you — no card, 1,000 records a month. Send it as the x-api-key header and make your first call.

Get your API key

curl "https://api.leadocean.io/v1/search?title=Founder&country=US&minEmployees=50&maxEmployees=200&limit=5" \
  -H "x-api-key: $LEADOCEAN_API_KEY"

200 OK · application/json

{
  "success": true,
  "data": [
    {
      "profile_data": {
        "profile_full_name": "Sarah Chen",
        "profile_headline": "Founder & CEO at CloudSync",
        "profile_url": "https://www.linkedin.com/in/…"
      },
      "contact_data": {
        "has_email": true,
        "email_status": "verified",
        "contact_current_experiences": [{
          "company_name": "CloudSync",
          "company_domain": "cloudsync.com",
          "job_title": "Founder & CEO",
          "company_employees": { "number_of_employees": 120 }
        }]
      }
    }
  ],
  "meta": { "count": 5, "source": "own", "nextCursor": "…" }
}

Authentication

Every request carries your key in the x-api-key header. Keys have scopes: enrich covers /v1/enrich and /v1/company, search covers /v1/search. You can view, copy or rotate a key at any time in your account.

Agents connect differently. The MCP server uses OAuth 2.1 — your assistant signs in to your LeadOcean account and never sees a key. See MCP server.

Records and limits

Usage is metered in records returned. Every person or company we hand back counts one: a search page of 25 counts 25, enriching one person counts 1 (plus 1 when you reveal the email), a company lookup counts 1. Requests rejected for rate limits or quota are never counted, and a search page is trimmed to what is left in your month rather than overshooting it.

Limit	Value
Rate	100 requests per second per key, paced evenly. Over that, `429` with `Retry-After: 1`.
Past your records	A paid account is paced to one request a minute until the records reset at the start of next month — never cut off. Every answer carries `meta.notice` and `X-Quota-State: over-limit` so your code knows why it slowed down. The free plan is refused once its 1,000 are spent.
Free tier	1,000 records a month, 1 key, full API and MCP access.
Pro	Production volume, 5 keys.
Page size	`limit` up to 100 records per search request.

Search people

GET /v1/search (also accepted as POST with a JSON body). Combine the filters below; arrays are comma-separated in the query string. Results are thin person records — identity, headline, current role and company, location, and the has_email / email_status flags. Contact details come from enrichment.

Page with meta.nextCursor: pass it back as cursor. Cursors are opaque and tied to one filter set. meta.total is the size of the segment where the source can give one, and meta.unsupportedFilters names any filter the answering dataset ignored.

Enrich a person

POST /v1/enrich · 1 record · +1 with reveal_email

One person by LinkedIn profile URL (preferred) or work email. Returns the full leadocean.person.v1 record. Email addresses and phone numbers are included only when reveal_email is true — that performs the paid lookup.

Field	Type	Meaning
linkedin_url	string (URL)	LinkedIn profile URL. One of linkedin_url or email is required.
email	string	Work email address.
reveal_email	boolean · default false	Include contact emails and phones (+1 record).

Company lookup

POST /v1/company · 1 record

One company by website domain (preferred) or LinkedIn company URL. Returns leadocean.company.v1: firmographics, detected technologies and metrics.

Field	Type	Meaning
domain	string	Website domain, e.g. stripe.com. One of domain or linkedin_url is required.
linkedin_url	string (URL)	LinkedIn company page URL.

Filters and usage endpoints

GET /v1/filters is public and returns every filter, the allowed enum values and the schema names — useful when you generate queries programmatically. GET /v1/usage returns this month's records used, your plan, and per-day and per-key totals for the last 30 days.

Filter reference

Live filter list unavailable right now — fetch https://api.leadocean.io/v1/filters directly.

Response schema

Two shapes, stable across sources and versions. Unknown values are null, never guessed; dates are YYYY-MM-DD strings.

leadocean.person.v1

profile_data	profile_id, profile_url, first / last / full name, headline, summary, picture, languages, address (city, state, country, country_code), status, tags, expertises, metrics, last modified and last seen dates
contact_data	contact_emails[] and contact_phones[] (only with `reveal_email`), contact_current_experiences[], still-at-company status, `has_email`, `email_status`
resume_data	experiences[], educations[], certifications[], awards[], skills[]
meta	key, key_hash, sources[], fetched_at, schema

leadocean.company.v1

company_data	name, description, industry, employee count and size code, headquarters address, founded year, website, social links
company_detected_technologies	technologies found on the company website
company_metrics	followers and employee counts

Experience objects carry company_name, company_domain, company_industry, company_employees, job_title, job_seniority, job_functions[], start and end dates and a current flag. The exhaustive field list is in llms-full.txt.

Errors and headers

Success is { success: true, data, meta }; failure is { success: false, error: { message, details? } }.

Status	Meaning
400	Validation failed — details names the fields
401	Missing, wrong or revoked key
403	Key lacks the scope, or the account is suspended
404	No matching person or company
402	Free plan: the month's 1,000 records are spent
429	Faster than your rate — 100 a second, or 1 a minute once a paid account is over its records — honour Retry-After
503	No dataset available right now — retry shortly

Response headers: X-Source (which dataset answered), X-Request-Id (quote it in support requests), X-RateLimit-Limit and X-RateLimit-Policy, and Retry-After on 429.

MCP server

The hosted server lives at https://api.leadocean.io/mcp and speaks Streamable HTTP with OAuth 2.1. Add the URL in your client, sign in with your LeadOcean account, and the tools appear. Nothing is pasted, and you can disconnect an app any time from API keys → Connected apps.

Client	How to add it
Claude	Settings → Connectors → Add custom connector → paste the URL → Connect.
ChatGPT	Settings → Security and login → Developer mode, then Connectors → Add → paste the URL, authentication OAuth.
Claude Code	`claude mcp add --transport http leadocean https://api.leadocean.io/mcp` then `claude mcp login leadocean`.
Cursor	mcp.json: `{"mcpServers":{"leadocean":{"url":"https://api.leadocean.io/mcp"}}}`
Codex	config.toml: `[mcp_servers.leadocean] url = "https://api.leadocean.io/mcp"` then `codex mcp login leadocean`.
VS Code	.vscode/mcp.json: `{"servers":{"leadocean":{"type":"http","url":"https://api.leadocean.io/mcp"}}}`
Windsurf	mcp_config.json with `serverUrl` set to the URL above.
Gemini CLI	settings.json with `httpUrl` set to the URL above, then `/mcp auth leadocean`.

Tool catalog

These are the exact descriptions the server gives the model, so an agent can plan work without reading this page.

Catalog unavailable right now — fetch https://api.leadocean.io/mcp/tools.

llms.txt

The whole API is published as plain Markdown for models: llms.txt is the index and llms-full.txt has every endpoint, parameter, enum value, schema field group, error and tool. Both are generated from the running API, so they never drift. Paste the URL into Claude, add it to Cursor as a doc, or fetch it in your own system prompt.

Ask your assistant: “Read https://api.leadocean.io/llms-full.txt and use it as the reference for the LeadOcean API.”

The LeadOcean API

Quickstart

Authentication

Records and limits

Search people

Enrich a person

Company lookup

Filters and usage endpoints

Filter reference

Response schema

leadocean.person.v1

leadocean.company.v1

Errors and headers

MCP server

Tool catalog

llms.txt