AI score interview

Submit a verbatim interview transcript and a target role to receive an AI-generated scorecard. The scorecard evaluates the candidate across three dimensions and produces an overall score and hiring recommendation.

Scope required: ai:score

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

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

---

Request body

Field	Type	Required	Constraints	Description
transcript	string	Yes	50 – 50,000 chars	Full verbatim text of the interview
role	string	Yes	2 – 120 chars	Job title or role being evaluated (e.g., "Senior Backend Engineer")
rubric_id	string	No	Max 100 chars	ID of a custom scoring rubric configured in your company account
async	boolean	No	Default: false	If true, process asynchronously and return a job ID

---

Example: synchronous request

curl -X POST "https://api.oikohire.com/api/v1/external/ai/score-interview" \
  -H "Authorization: Bearer sk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Interviewer: Can you walk me through your approach to API design? Candidate: Absolutely. I always start with the consumer in mind — for example, I recently designed a RESTful API for a payment service. I focused specifically on clear error messages and versioning because...",
    "role": "Senior Backend Engineer"
  }'

Synchronous response 200 OK

{
  "status": "success",
  "data": {
    "overall_score": 78,
    "dimensions": {
      "technical_accuracy": {
        "score": 82,
        "feedback": "Candidate demonstrated strong knowledge of API design patterns and clearly articulated trade-offs."
      },
      "communication": {
        "score": 75,
        "feedback": "Responses were structured and used concrete examples effectively."
      },
      "problem_solving": {
        "score": 77,
        "feedback": "Showed methodical thinking but could elaborate further on edge-case handling."
      }
    },
    "summary": "Strong technical candidate with clear communication. Recommended for a follow-up technical round.",
    "recommendation": "Advance to next round"
  }
}

Scorecard fields

Field	Type	Description
overall_score	integer (0–100)	Composite score across all dimensions
dimensions.technical_accuracy.score	integer (0–100)	Knowledge correctness and depth
dimensions.technical_accuracy.feedback	string	Qualitative dimension feedback
dimensions.communication.score	integer (0–100)	Clarity, structure, use of examples
dimensions.communication.feedback	string	Qualitative dimension feedback
dimensions.problem_solving.score	integer (0–100)	Approach, trade-off reasoning
dimensions.problem_solving.feedback	string	Qualitative dimension feedback
summary	string	One-paragraph narrative summary
recommendation	string	e.g., "Advance to next round", "Do not advance"

---

Example: async request

curl -X POST "https://api.oikohire.com/api/v1/external/ai/score-interview" \
  -H "Authorization: Bearer sk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "...",
    "role": "Product Manager",
    "async": true
  }'

Async response 202 Accepted

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

Poll check_status_url with your API key until status is completed. See Async job status.

---

Idempotency

Include an Idempotency-Key header to deduplicate identical requests within the deduplication window:

POST /api/v1/external/ai/score-interview
Idempotency-Key: interview-session-001