Search candidates

Search the OikoHire candidate pool. Only candidates who have a public profile and have consented to AI matching and recruiter discovery are returned.

Scope required: candidates:read

GET /api/v1/external/candidates
Authorization: Bearer sk_live_<key>

---

Query parameters

Parameter	Type	Required	Constraints	Description
q	string	No	Max 300 chars	Free-text search against headline, summary, and skills
skills	string	No	Comma-separated, max 20 items, max 80 chars each	Filter by skill keywords (all must match)
location	string	No	Max 120 chars	Filter by location (case-insensitive substring match)
experience_min	integer	No	0 – 60	Minimum years of experience
page	integer	No	Min 1 (default: 1)	Page number
limit	integer	No	1 – 50 (default: 10)	Results per page

---

Example request

curl "https://api.oikohire.com/api/v1/external/candidates" \
  -H "Authorization: Bearer sk_live_<key>" \
  -G \
  --data-urlencode "q=backend engineer" \
  --data-urlencode "skills=typescript,postgresql" \
  --data-urlencode "location=Tokyo" \
  --data-urlencode "experience_min=3" \
  --data-urlencode "limit=5"

---

Response 200 OK

{
  "status": "success",
  "data": {
    "candidates": [
      {
        "id": "clx1abc23def456",
        "name": "Alex Johnson",
        "headline": "Senior Backend Engineer",
        "location": "Tokyo, Japan",
        "skills": ["typescript", "postgresql", "nestjs"],
        "experience_years": 6,
        "updated_at": "2026-07-08T12:34:56.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 42,
      "total_pages": 9
    }
  }
}

Candidate object fields

Field	Type	Description
id	string	Unique candidate identifier
name	string | null	Candidate's display name (may be null if not provided)
headline	string | null	Professional headline
location	string | null	Self-reported location
skills	string[]	Up to 20 skills from the candidate's profile
experience_years	integer | null	Self-reported years of experience
updated_at	ISO 8601	When the profile was last updated

---

Notes

• Results are ordered by updatedAt descending (most recently active first).
• Candidates who have disabled discoverable or aiMatching in their privacy settings are excluded.
• This endpoint counts towards the standard rate limit window (60 seconds).