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 issued per workspace and can be generated from Settings → API Keys in the InnoHire.ai dashboard. Keys have configurable expiry and rate limits.

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