Skip to main content

OikoHire External API

OikoHire exposes a REST API that lets your backend systems search talent, run AI-powered candidate matching, and score interview transcripts — all without requiring a user session.

Who can use the API?

The external API is available exclusively to Company accounts on an active paid or trialling subscription. API keys are scoped per company and cannot be used by Candidate or Recruiter accounts.

Base URL​

All API endpoints are served under:

https://api.oikohire.com/api/v1

Available endpoints at a glance​

MethodPathScopeDescription
GET/external/health(public)Liveness check — no key required
GET/external/candidatescandidates:readSearch the candidate pool
POST/external/ai/match-jobsai:matchMatch a resume against your open jobs
POST/external/ai/score-interviewai:scoreScore an interview transcript
GET/external/jobs/:idjobs:readPoll the status of an async job

Quick start​

curl https://api.oikohire.com/api/v1/external/candidates \
  -H "Authorization: Bearer sk_live_<your_key>" \
  -H "Content-Type: application/json" \
  -G --data-urlencode "q=senior typescript" \
     --data-urlencode "skills=typescript,react" \
     --data-urlencode "limit=5"

The same request with fetch:

const url = new URL('https://api.oikohire.com/api/v1/external/candidates');
url.searchParams.set('q', 'senior typescript');
url.searchParams.set('skills', 'typescript,react');
url.searchParams.set('limit', '5');

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.OIKOHIRE_API_KEY}` },
});

if (!response.ok) {
  throw new Error(`OikoHire request failed: ${response.status}`);
}

const result = await response.json();
console.log(result.data.candidates);
tip

Keep the API key on your server. Never expose it in browser JavaScript, mobile application bundles, or a public repository.

Next steps​