How to Source Candidates With a Recruitment Data API (Talent Acquisition)

A talent acquisition team needs three things from a data API: a count before it spends, a filter that matches the role, and a profile with career history. LeadOcean does all three over REST and MCP. This guide walks through each with real requests.

One honest note on "real time". The LeadOcean dataset refreshes monthly, and each record carries its own fetched_at date. Queries and enrichment are live API calls. The underlying profiles are not a minute-by-minute feed.

TL;DR

• The walkthrough takes about 20 minutes and spends about 3 records. Counts, sizing and empty enrichments are free.
• Filter by title, country, employeeRange and profile keywords. Enrich by person_id to get past roles, education and certifications.
• Free gives 1,000 records for life, no card. Bulk CSV export needs Solo or above.

Prerequisites

• A LeadOcean API key from app.leadocean.io. Free needs no card.
• The key exported as $LEADOCEAN_API_KEY.
• curl and jq. Examples use Acme, acme.com and Jane Doe as placeholders.

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

Step 1: Size the talent pool for free

Count before you search. Send count=true and limit=1 as query parameters. Arrays go comma-separated.

curl -s -G https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "title=Data Engineer" \
  --data-urlencode "country=US" \
  --data-urlencode "employeeRange=201-500" \
  --data-urlencode "count=true" \
  --data-urlencode "limit=1" | jq '.meta | {total, totalIsExact, countOnly}'

meta.total stops at 100,000, so a wide market returns a floor. Narrow it until totalIsExact is true.

Step 2: Add profile keywords to match the role

Titles vary, so match the skill too. keywords searches the person's own headline, summary, skills and job descriptions. Several values OR together.

curl -s -G https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "title=Data Engineer" \
  --data-urlencode "country=US" \
  --data-urlencode "employeeRange=201-500" \
  --data-urlencode "keywords=Snowflake" \
  --data-urlencode "count=true" \
  --data-urlencode "limit=1" | jq '.meta.total'

Check enum values before you guess them. employeeRange takes exact strings such as 201-500. The free GET /v1/enums endpoint lists them.

Step 3: Search the pool

Search returns a thin row with a person_id and contact flags. Each person returned costs 1 record. The body is flat JSON and filters are arrays.

curl -s https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": ["Data Engineer"],
    "country": ["US"],
    "employeeRange": ["201-500"],
    "keywords": ["Snowflake"],
    "limit": 2
  }' | jq '.data[] | {person_id: .meta.source_ids.person_id, contact_data}'

Page with the cursor value from the response. limit runs 1 to 100. One search pages to 10,000 rows. When meta.depthCapped is true, narrow the filters instead of walking further.

Step 4: Enrich one candidate for career history

Enrich takes exactly one of linkedin_url, email, phone or person_id. There is no name plus company lookup, so search first and pass the person_id.

curl -s https://api.leadocean.io/v1/people/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id": "PERSON_ID_FROM_STEP_3", "reveal_email": true}' \
  | jq '.data.resume_data'

It costs 1 record. A person we hold nothing for is a 404 and costs nothing. Past employers carry no company_id yet, so match them by name.

Step 5: Look at the pool through an AI agent

The hosted MCP server at https://api.leadocean.io/mcp signs in with OAuth, so no key is pasted. It has 13 tools. Counting is free.

Count Data Engineers in the US at companies with 201-500 employees
whose profile mentions Snowflake. Tell me how many employers that spans.
Do not search yet.

The agent calls leadocean_count_leads, which also returns distinctCompanies. That number tells you how many employers you could source from.

Step 6: Export the shortlist

For hundreds of candidates, export instead of paging. POST /v1/exports takes up to 50,000 rows a request and 500,000 a day. Bulk CSV export is not on Free.

curl -s https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "title": ["Data Engineer"],
      "country": ["US"],
      "employeeRange": ["201-500"],
      "keywords": ["Snowflake"]
    },
    "limit": 500,
    "preset": "full"
  }'

The search filters go under filters. preset picks the columns: full includes emails, phones, current role, education and skills, search carries only what a search row holds. GET /v1/exports/columns lists every column id. Poll GET /v1/exports/{id}, then download from GET /v1/exports/{id}/download. The app at app.leadocean.io has an Exports page with a filter builder, a column picker and a price preview if you prefer clicks.

What you get

Free MCP counts run on 2026-10-21. Both count only addresses worth sending to (verified, catch_all_valid or catch_all), which is the tool default. They are not a count of every candidate.

Enrich output, response shape from the API reference, placeholder values:

{
  "success": true,
  "data": {
    "profile_data": { "profile_full_name": "Jane Doe" },
    "contact_data": {
      "email_status": "verified",
      "contact_current_experiences": [ { "job_title": "Data Engineer", "company_name": "Acme" } ]
    },
    "resume_data": {
      "experiences": [ { "...": "title, company name, start and end dates, job level" } ],
      "educations": [ { "...": "school, degree" } ],
      "certifications": [ { "...": "name" } ]
    }
  }
}

Fields appear only when held. Read email_status before you send. LeadOcean gives no refund for bounces.

Troubleshooting

FAQ