Developers

OikoHire API Reference

Integrate our powerful AI recruitment engine directly into your workflows. Search candidates, score technical skills, and match resumes programmatically.

Overview

The OikoHire API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.oikohire.com/v1

Data Format

All requests and responses use standard JSON format.

Authentication

The OikoHire API uses API keys to authenticate requests. You can view and manage your API keys in the Developer Settings of your dashboard.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value in the Authorization header.

Keep your keys secure

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Key Safety Warning

The OikoHire API is server-only. Browser requests (CORS calls) are explicitly blocked. Never publish your sk_live_ key in client-side repositories, frontend code, or public pages.

Example Authorization Header

Code

curl https://api.oikohire.com/v1/external/candidates?limit=1 \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json"

Rate Limits

We limit the number of requests you can make to our API to ensure stability for all users. The current limits are based on your subscription tier. Standard requests are rate-limited separately from resource-intensive AI operations.

Tier	Standard Endpoints	AI Endpoints (Score/Match)
Starter	60 / min	100 / day
Pro	300 / min	500 / day
Agency / Enterprise	1,000 / min	2,500 / day

If you exceed these limits, you will receive a 429 Too Many Requests response. Check the X-RateLimit-Remaining and Retry-After headers for rate limit status and when to resume.

Errors & Codes

The external API uses conventional HTTP response codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with OikoHire's servers.

HTTP Status	Code	Meaning
400	BAD_REQUEST	Malformed request body or invalid parameter
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Key is revoked, or plan limit exceeded
404	NOT_FOUND	Resource not found
422	UNPROCESSABLE	Validation error in request body
429	RATE_LIMITED	Rate limit exceeded — check Retry-After header
500	INTERNAL_ERROR	Server error — contact support

Core Endpoints

POST

Match Resume to Jobs

POST/v1/external/ai/match-jobs

Submits a candidate's resume (text or URL) and returns a list of highly relevant job postings from your internal database, scored and explained by our AI.

Parameters

Name	Type	Description
resume_text	string	Raw text content of the candidate resume. Either this or resume_url is required.
resume_url	string	Public URL to a PDF or DOCX resume.
limit	integer	Maximum number of matches to return. Default is 5, max is 20.
min_score	float	Minimum match score (0.0 to 1.0) to filter results.

Example Request

cURL

curl -X POST https://api.oikohire.com/v1/external/ai/match-jobs \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -H "Idempotency-Key: 6f8c9a3e-abc4-4d12-b9c1-e60d57a2f1b0" \
 -d '{
 "resume_text": "Experienced Frontend Engineer with 5 years in React, TypeScript, and Tailwind CSS...",
 "limit": 3,
 "min_score": 0.85
 }'

Example Response

JSON

{
 "status": "success",
 "data": {
 "matches": [
 {
 "job_id": "job_9f8a7b6c",
 "title": "Senior React Developer",
 "company": "TechFlow Inc.",
 "match_score": 0.92,
 "rationale": "Strong overlap in React and TypeScript experience."
 }
 ]
 }
}

POST

Score Mock Interview

POST/v1/external/ai/score-interview

Analyzes a transcript of a technical interview and provides automated scoring across multiple dimensions (technical accuracy, communication, problem-solving).

Parameters

Name	Type	Description
transcript*	string	Full text transcript of the interview conversation.
role*	string	The role being interviewed for (e.g., "Backend Engineer").
rubric_id	string	Optional ID of a custom scoring rubric defined in your dashboard.

Example Request

cURL

curl -X POST https://api.oikohire.com/v1/external/ai/score-interview \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -H "Idempotency-Key: 7a5d2b1f-ef93-4c81-a3d2-b71e48c3e109" \
 -d '{
 "role": "Data Scientist",
 "transcript": "[Interviewer]: Can you explain bias-variance tradeoff?..."
 }'

Example Response

JSON

{
 "status": "success",
 "data": {
 "overall_score": 85,
 "dimensions": {
 "technical_accuracy": {
 "score": 90,
 "feedback": "Excellent explanation."
 }
 }
 }
}

GET

Search Candidates

GET/v1/external/candidates

Search for candidates in the OikoHire database using keyword and filter criteria. Returns a paginated list of matching candidate profiles. Counts against your plan's searchLimit.

Query Parameters

Name	Type	Description
q	string	Keyword or natural-language search query.
skills	string[]	Comma-separated list of required skills (e.g. `skills=React,TypeScript`).
location	string	City, country, or "remote".
experience_min	integer	Minimum years of experience.
page	integer	Page number, starting at 1. Default: 1.
limit	integer	Results per page. Default: 10, max: 50.

Example Request

cURL

curl -G https://api.oikohire.com/v1/external/candidates \
 -H "Authorization: Bearer YOUR_API_KEY" \
 --data-urlencode "q=senior backend engineer" \
 --data-urlencode "skills=Node.js,PostgreSQL" \
 --data-urlencode "location=remote" \
 --data-urlencode "limit=5"

Example Response

JSON

{
 "status": "success",
 "data": {
 "candidates": [
 {
 "id": "cand_abc123",
 "name": "Alex Kim",
 "headline": "Senior Backend Engineer",
 "location": "Remote",
 "skills": ["Node.js", "PostgreSQL", "TypeScript"],
 "experience_years": 7,
 "match_score": 0.91
 }
 ],
 "pagination": {
 "page": 1,
 "limit": 5,
 "total": 42
 }
 }
}

Ready to start building?

Generate your API keys in the developer dashboard and start integrating OikoHire's intelligent recruitment features today.