API Reference

Base URL

https://api.innohire.ai/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are generated from Settings → API Keys in the InnoHire.ai dashboard. Keys start with ihk_live_, are shown only once, can be given an expiry, and can be revoked at any time. The X-API-Key header is accepted as an alternative. Keep keys on your server; never embed them in browser or mobile code.

Scopes

Each key only works for the features selected when it was created. Calling an endpoint outside the key's scopes returns 403. Billing, profile and key-management endpoints are never available to API keys.

Rate Limits

Endpoints

POST /evaluate

The primary endpoint. Accepts a job description and one or more resume texts. Returns match scores, gap analysis, screening questions, and generated content.

Request body:

{
  "job_description": "string (required)",
  "resumes": [
    {
      "id": "string (optional, your internal ID)",
      "text": "string (required, plain text content)"
    }
  ],
  "options": {
    "generate_questions": true,
    "generate_boolean_string": true,
    "generate_outreach": true
  }
}

Response (200 OK):

{
  "job_id": "job_xk29a",
  "evaluated_at": "2026-02-20T10:42:00Z",
  "candidates": [
    {
      "id": "your-internal-id",
      "rank": 1,
      "overall_score": 87,
      "semantic_similarity": 0.84,
      "matched_skills": ["Python", "FastAPI", "PostgreSQL"],
      "missing_skills": ["Docker"],
      "gap_severity": { "Docker": "moderate" },
      "experience_years_relevant": 5.2,
      "screening_questions": [
        "Describe a time you optimised a PostgreSQL query under load.",
        "How would you containerise a Python FastAPI service?"
      ],
      "boolean_search_string": ""Python" AND "FastAPI" AND ("PostgreSQL" OR "MySQL")",
      "linkedin_outreach_draft": "Hi [Name], I came across your profile..."
    }
  ]
}

POST /bulk-screen

Accepts up to 1000 resumes (Enterprise) for asynchronous processing. Returns a job ID immediately; use the /jobs/{job_id} endpoint to poll for results.

POST /bulk-screen
{
  "job_description": "string",
  "resume_urls": ["https://...", "https://..."],   // signed URLs to resume files
  "webhook_url": "https://your-app.com/webhook"    // optional: receive results on completion
}

Response (202 Accepted):

{
  "job_id": "bulk_98zq1",
  "status": "queued",
  "estimated_completion_seconds": 45
}

GET /jobs/{job_id}

Poll the status and retrieve results of an async bulk screening job.

GET /jobs/bulk_98zq1

Response:
{
  "job_id": "bulk_98zq1",
  "status": "completed",   // queued | processing | completed | failed
  "progress": 100,
  "candidates": [...]      // same format as /evaluate response
}

POST /analyze-transcript

Submit an interview transcript (plain text) for NLP evaluation.

POST /analyze-transcript
{
  "transcript": "Interviewer: Tell me about... Candidate: Sure, I...",
  "job_description": "string (optional, improves role-alignment scoring)",
  "interview_type": "behavioural" | "technical" | "mixed"
}

Response (200 OK):

{
  "overall_interview_score": 76,
  "competency_scores": {
    "technical_depth": 82,
    "communication_clarity": 74,
    "problem_solving": 80
  },
  "star_completeness_avg": 3.2,
  "concern_flags": ["low ownership signals"],
  "interviewer_summary": "Candidate demonstrated..."
}

Error Codes

Webhooks

Provide a webhook_url in bulk requests to receive a POST when processing completes. The payload is identical to the GET /jobs/{job_id} response. Webhooks are signed with an HMAC-SHA256 header for verification.

SDK & Code Examples

A Python SDK is available for rapid integration:

pip install innohire-sdk

from innohire import InnoHireClient

client = InnoHireClient(api_key="YOUR_API_KEY")

result = client.evaluate(
    job_description="...",
    resumes=[{"id": "c1", "text": "..."}]
)

print(result.candidates[0].overall_score)  # e.g. 87