How to Use People Data in an AI Recruiting Platform (5 API Calls)

An AI recruiting platform needs five things from a people data API: a candidate profile, a searchable pool, a free size check, a way to reach people, and a way to find the hiring team. This guide shows one request for each against LeadOcean, with real query shapes and output.

One caveat first. LeadOcean refreshes its dataset monthly, and each record carries its own fetched_at date. It is not a live crawl, so treat the date as part of the answer.

TL;DR

• Five calls cover the core recruiting loop: enrich, search, count, contact, hiring team.
• It takes about 45 minutes and spends about 13 records on the Free plan (1,000 records for life, no card).
• Counting a pool is free. Do it before every search.

Prerequisites

• A LeadOcean account on the Free plan: start free.
• An API key from app.leadocean.io, exported as $LEADOCEAN_API_KEY.
• curl and jq, or any HTTP client. Every request goes to https://api.leadocean.io with the header x-api-key.
• Free runs at 5 requests a second. Above that you get a 429 with Retry-After.

Step 1: Enrich a candidate from a LinkedIn URL

Send one identifier and get back the profile, including career history. Enrich takes exactly one of linkedin_url, email, phone or person_id.

curl -s -X POST https://api.leadocean.io/v1/people/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url": "https://www.linkedin.com/in/jane-doe-example"}'

Since October 2026 the response includes resume_data: past roles in experiences[] (title, company name, start and end dates, job level), plus educations[], certifications[] and awards[], each when held. The current role sits in contact_current_experiences[].

Past employers carry no company_id yet. Match them by name for now.

An enrichment that finds nobody returns a 404 and costs nothing.

Step 2: Search a talent pool with flat filters

Search takes a flat JSON body. Filters are arrays of strings, limit runs 1 to 100 and you page with cursor.

curl -s -X POST https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": ["Technical Recruiter"],
    "country": ["US"],
    "limit": 5
  }'

Each returned person is one record, so limit: 5 spends 5. One search pages to 10,000 rows. When meta.depthCapped is true there is no nextCursor: narrow the filters instead of walking the index.

Enum filters are exact strings. jobLevel takes C-Team, VP, Director, Manager, Staff or Other. Check the values with leadocean_list_enum_values before you send them.

Step 3: Size the pool for free before you spend

Add count=true as a query parameter, not in the body, with limit 1. The response is empty data with meta.countOnly true and a total. It costs nothing.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": ["Technical Recruiter"], "country": ["US"], "limit": 1}'

meta.total is capped at 100,000. For an exact total with a breakdown, call the free MCP tool leadocean_count_leads from Claude or any MCP client. A people count also returns meta.distinctCompanies, the number of employers the matched people span.

This is the step most platforms skip. Run it so your agent never spends records on a pool that is too small or too broad.

Step 4: Get a work email or phone for the shortlist

Search gives you the profile. Reach comes from the contact endpoints. GET /v2/people/email/work returns a work address and GET /v2/people/phone returns a number.

curl -s -G https://api.leadocean.io/v2/people/email/work \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "person_id=PERSON_ID_FROM_STEP_2"

curl -s -G https://api.leadocean.io/v2/people/phone \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "person_id=PERSON_ID_FROM_STEP_2"

A v2 contact call costs one record, including a call that finds nothing. Read email_status before you send. There is no refund for bounces.

Step 5: Find the hiring team at a target company

For account-based recruiting, you often need the people inside one company: talent leads, heads of engineering, HR directors. One endpoint lists them by domain.

curl -s -G https://api.leadocean.io/v1/companies/acme.com/people \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  --data-urlencode "limit=5"

This stops at 10,000 rows per company. Use it to find who owns hiring, then run Step 4 on the two or three that matter.

To size an employer list first, use GET /v1/companies/count or the MCP tool leadocean_count_companies. Both are free and return breakdowns by industry, headcount band and HQ country.

What you get

Two free counts from the MCP tool leadocean_count_leads, run on 2026-10-21. Both count mailable addresses by default: verified, catch_all_valid and catch_all.

Filters: title "Technical Recruiter", country US
total (mailable): 23,913
totalAll (any email status): 74,953
distinctCompanies: 6,510
Top industries: IT Services and IT Consulting 6,174,
                Staffing and Recruiting 5,336,
                Software Development 2,810

Filters: jobFunction "Human Resources", jobLevel Director, country US
total (mailable): 113,046
totalAll (any email status): 304,161
Top industries: Hospitals and Health Care 10,536,
                Higher Education 6,225,
                Financial Services 4,130

A record from Step 1 or 2 follows the shape in the API reference. Placeholder values, response shape from the API reference:

{
  "success": true,
  "data": {
    "profile_data": { "...": "Jane Doe" },
    "contact_data": {
      "has_email": true,
      "contact_current_experiences": [
        { "job_title": "Senior Engineer", "company_name": "Acme" }
      ]
    },
    "resume_data": {
      "experiences": [ { "...": "Engineer at Example Co, start and end dates, job level" } ],
      "educations": [],
      "certifications": []
    },
    "meta": {}
  }
}

Troubleshooting

FAQ