AI match jobs

Submit a candidate resume and receive a ranked list of your company's open job postings by match score. The AI analyses skill overlap, gaps, and contextual signals to rank each job.

Scope required: ai:match

POST /api/v1/external/ai/match-jobs
Authorization: Bearer sk_live_<key>
Content-Type: application/json

This endpoint counts towards the AI rate limit window (24 hours).

---

Request body

You must supply exactly one of resume_text or resume_url — not both.

Field	Type	Required	Constraints	Description
resume_text	string	Cond.	50 – 50,000 chars	Raw text content of the resume
resume_url	string	Cond.	HTTPS URL, max 2,048 chars	Publicly accessible URL to a resume file
limit	integer	No	1 – 20 (default: 5)	Maximum number of job matches to return
min_score	number	No	0.0 – 1.0 (default: 0)	Only return jobs at or above this match score
async	boolean	No	Default: false	If true, process asynchronously and return a job ID for polling

---

Example: synchronous request

curl -X POST "https://api.oikohire.com/api/v1/external/ai/match-jobs" \
  -H "Authorization: Bearer sk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "resume_text": "Alex Johnson — Senior Backend Engineer with 6 years of experience in TypeScript, NestJS, PostgreSQL, and cloud infrastructure...",
    "limit": 5,
    "min_score": 0.3
  }'

Synchronous response 200 OK

{
  "status": "success",
  "data": {
    "matches": [
      {
        "job_id": "clx9job123abc",
        "title": "Senior Backend Engineer",
        "location": "Tokyo, Japan",
        "employment_type": "FULL_TIME",
        "match_score": 0.87,
        "rationale": "Matches 7/8 skills: typescript, postgresql, nestjs",
        "skills_gap": {
          "matched": [
            "typescript",
            "postgresql",
            "nestjs",
            "docker",
            "redis",
            "aws",
            "graphql"
          ],
          "missing": ["kubernetes"]
        }
      }
    ]
  }
}

Match object fields

Field	Type	Description
job_id	string	Unique ID of the matched job
title	string	Job title
location	string | null	Job location
employment_type	string	e.g. FULL_TIME, PART_TIME, CONTRACT
match_score	number	0.0 – 1.0 score of resume-to-job fit
rationale	string	Human-readable explanation of the score
skills_gap.matched	string[]	Up to 10 skills found in both the resume and job
skills_gap.missing	string[]	Up to 10 skills required by the job but absent from the resume

---

Example: async request

curl -X POST "https://api.oikohire.com/api/v1/external/ai/match-jobs" \
  -H "Authorization: Bearer sk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "resume_url": "https://cdn.example.com/resumes/alex-johnson.pdf",
    "limit": 10,
    "async": true
  }'

Async response 202 Accepted

{
  "status": "accepted",
  "data": {
    "job_id": "extjob_abc123",
    "status": "queued",
    "check_status_url": "/api/v1/external/jobs/extjob_abc123"
  }
}

Poll check_status_url using your API key until status is completed or failed. See Async job status.

---

Idempotency

This endpoint supports idempotency via the Idempotency-Key header. If you send the same header value within the deduplication window, the original response is returned without re-running the match:

POST /api/v1/external/ai/match-jobs
Idempotency-Key: my-unique-request-id-001