How to Automate Candidate Sourcing (With Claude Code)

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

## Candidate sourcing

### Role: Senior Python engineer, Austin, software company
Search filters (LeadOcean names):
- title: ["Software Engineer"]
- seniority: ["senior"]
- country: ["US"]
- city: ["Austin"]
- industry: ["Software Development"]
- keywords: ["python"]   (matches the person's own headline, summary and skills)
- employeeRange: ["51-200", "201-500", "501-1000"]
- emailStatus: ["verified", "catch_all_valid", "catch_all"]

### Exclusions
- Skip anyone whose profile_url is already in ats-export.csv.
- excludeCompanyName: [the names of our active clients]

### Rules
- Count first, search second, export last. State the record cost before each step.
- Stop and ask before spending more than 200 records in a session.
- Never guess skills or years of experience. Use only fields the API returned.
- Write rows to shortlists/. Show at most 10 rows in chat.

claude mcp add --transport http leadocean https://api.leadocean.io/mcp
claude mcp list

/mcp

Use leadocean_count_leads with title ["Software Engineer"], country ["US"],
seniority ["senior"], keywords ["python"],
employeeRange ["51-200","201-500","501-1000"], city ["Austin"],
industry ["Software Development"]. Report the total and say which email
statuses it counted. Then count again without city and industry. Do not call any tool that spends records.

curl -s "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "title": ["Software Engineer"],
    "country": ["US"],
    "seniority": ["senior"],
    "city": ["Austin"],
    "industry": ["Software Development"],
    "keywords": ["python"],
    "employeeRange": ["51-200", "201-500", "501-1000"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 1
  }' | jq '.meta | {total, totalIsExact}'

Use leadocean_search_leads with the same filters and limit 10. Show a table of name,
headline, company and email_status. Flag any headline that is not a software engineer
so I can add it to excludeTitle. Save the rows to shortlists/sample.json.

mkdir -p shortlists
curl -s "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "title": ["Software Engineer"],
    "country": ["US"],
    "seniority": ["senior"],
    "city": ["Austin"],
    "industry": ["Software Development"],
    "keywords": ["python"],
    "employeeRange": ["51-200", "201-500", "501-1000"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 10
  }' | tee shortlists/sample.json \
  | jq '.data[] | {name: .profile_data.profile_full_name, headline: .profile_data.profile_headline, person_id: .meta.source_ids.person_id, email_status: .contact_data.email_status}'

For the first three rows in shortlists/sample.json, call leadocean_get_lead with the row's
person_id and reveal_email true. Report email, email_status and
contact_still_at_company_status. Save the results to shortlists/enriched.json.

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 4>", "reveal_email": true}' \
  | jq '.data.contact_data | {email_status, email_type, contact_still_at_company_status}'

curl -s https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "Senior Python engineers, Austin, 51 to 1,000 staff",
    "filters": {
      "title": ["Software Engineer"],
      "country": ["US"],
      "seniority": ["senior"],
      "city": ["Austin"],
      "industry": ["Software Development"],
      "keywords": ["python"],
      "employeeRange": ["51-200", "201-500", "501-1000"],
      "emailStatus": ["verified", "catch_all_valid", "catch_all"]
    },
    "limit": 148,
    "preset": "full"
  }' | tee export.json | jq '.data | {id, status, requested, estimatedTotal, pollAfter}'

ID=$(jq -r '.data.id' export.json)
curl -s https://api.leadocean.io/v1/exports/$ID -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data.status'
curl -s https://api.leadocean.io/v1/exports/$ID/download -H "x-api-key: $LEADOCEAN_API_KEY" -o candidates.csv

Read candidates.csv and ats-export.csv. Remove anyone whose profile URL is in the ATS file.
Write shortlists/final.csv with name, headline, company, email_1_address and email_1_status.
Do not add any column the CSV does not already have.

{
  "total": 148,
  "totalIsExact": true,
  "totalAll": 364,
  "distinctCompanies": 106,
  "facets": {
    "seniority": [{ "value": "senior", "count": 148 }],
    "company_size": [
      { "value": "51-200", "count": 58 },
      { "value": "201-500", "count": 55 },
      { "value": "501-1000", "count": 35 }
    ],
    "industry": [{ "value": "Software Development", "count": 148 }]
  }
}

{
  "success": true,
  "data": {
    "profile_data": {
      "profile_full_name": "Jane Doe",
      "profile_headline": "<headline>",
      "profile_url": "https://www.linkedin.com/in/janedoe"
    },
    "contact_data": {
      "contact_emails": [{ "email": "jane.doe@acme.com", "type": "work", "status": "verified" }],
      "contact_phones": [{ "phone": "+14155550133", "type": "mobile" }],
      "email_status": "verified",
      "contact_still_at_company_status": "<status>"
    },
    "resume_data": {
      "experiences": [
        { "job_title": "Software Engineer", "company_name": "Acme", "start_date": "2019-03", "end_date": "2022-06", "company_id": null }
      ],
      "educations": [{ "educational_establishment": "<school>", "diploma": "<degree>" }],
      "r_skills": ["python"]
    }
  },
  "meta": { "source_ids": { "person_id": "<person_id>" }, "schema": "leadocean.person.v1" }
}