# How to Update Candidate Status via API in the Hiring Agent Repository

> Update candidate status via API with the interviewstreet hiring agent. Learn how to build custom wrappers with FastAPI or Flask to expose status endpoints for efficient candidate management.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: api-reference
- Published: 2026-06-26

---

**The interviewstreet/hiring-agent repository does not implement a REST API for updating candidate status; it operates entirely through local Python functions and command-line tools, requiring you to build a custom FastAPI or Flask wrapper to expose status endpoints.**

The interviewstreet/hiring-agent codebase is a specialized Python tool designed for parsing résumé PDFs, extracting structured candidate data with large language models (LLM) such as Google Gemini, and generating evaluation scores. Because the architecture centers on local script execution rather than client-server communication, there are no HTTP routes, request handlers, or built-in endpoints to modify a candidate’s hiring status via API.

## Why the Repository Lacks a Candidate Status API

According to the hiring-agent source code, the project is architected as a standalone evaluation engine rather than a web service. All modules are invoked directly via Python imports or CLI commands, with no HTTP server infrastructure present in any configuration or routing files.

**Core Components of the Evaluation Pipeline**

- **PDF parsing & text extraction**: The [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) modules handle ingestion of résumé files and conversion to structured text.
- **Prompt generation**: The [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) module and Jinja2 templates in `prompts/templates/*.jinja` construct LLM queries based on extracted data.
- **LLM provider abstraction**: The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) files manage API calls to Gemini and handle retry logic.
- **Scoring & evaluation**: The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) and [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) modules process LLM responses into numeric scores and formatted output.
- **Configuration**: The [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) and `.env.example` files manage environment variables for API keys and model selection.

None of these files contain Flask apps, FastAPI routers, or HTTP handlers, confirming that the repository does not support remote status updates.

## The Current Local Workflow

Rather than updating a candidate record through a `PATCH` request, hiring-agent runs evaluations locally by chaining functions from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) to [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py). This workflow generates a score but does not persist or modify a "status" field in any external system.

### Running a Resume Evaluation via Python

```python
from pdf import extract_resume_data
from evaluator import evaluate_resume
from score import print_evaluation_results

# 1. Extract structured résumé data from the PDF

resume_data = extract_resume_data("candidate_resume.pdf")

# 2. Run the LLM evaluation

score = evaluate_resume(resume_data)

# 3. Display the results

print_evaluation_results(score, candidate_name="John Doe")

```

Executing this script creates a one-time evaluation output; it does not store candidate statuses such as "Interviewed" or "Rejected" in a database or expose them via an API.

## How to Build a Candidate Status Update API

Because the repository lacks native HTTP capabilities, you must implement a service layer to expose candidate status functionality. The most efficient approach wraps the existing evaluation logic in a FastAPI application.

### Choose a Web Framework

**FastAPI** is recommended for this integration due to its native Pydantic support and automatic OpenAPI documentation generation, though Flask is a viable alternative.

### Create Pydantic Data Models

Define models to validate incoming status updates and candidate identification:

```python
from pydantic import BaseModel

class StatusUpdate(BaseModel):
    status: str  # e.g., "Screened", "Interviewed", "Hired"

    updated_by: str

```

### Implement the Status Update Endpoint

Add a route handler that receives status changes and persists them to your chosen storage layer:

```python
from fastapi import FastAPI

app = FastAPI()

@app.patch("/candidates/{candidate_id}/status")
async def update_status(candidate_id: int, payload: StatusUpdate):
    # Retrieve candidate from SQLite/PostgreSQL or in-memory store

    # Update candidate.status = payload.status

    # Optionally trigger re-evaluation using evaluator.py logic

    return {"candidate_id": candidate_id, "new_status": payload.status}

```

### Persist State and Integrate Evaluation

Connect the new API to a database (SQLite, PostgreSQL, or even a JSON file) and modify the route to invoke `evaluate_resume()` when a résumé is uploaded, automatically setting `status = "evaluated"` upon completion.

## Summary

- The interviewstreet/hiring-agent repository provides **no built-in API** for candidate status management; it is a local CLI and library tool.
- Current functionality is limited to **PDF parsing** ([`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)), **LLM scoring** ([`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)), and **result printing** ([`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)).
- To enable status updates via API, you must implement a **custom FastAPI/Flask service** that wraps the existing evaluation pipeline.
- Key integration points involve the `extract_resume_data()` and `evaluate_resume()` functions for triggering evaluations upon status changes.

## Frequently Asked Questions

### Does hiring-agent include a REST API for candidate management?

No. The repository contains no HTTP servers, routes, or request handlers. All interactions rely on direct Python function calls or command-line scripts.

### Which source files handle the resume evaluation workflow?

The primary workflow files are [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for text extraction, [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) for scoring logic, and [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) for formatting output. Supporting modules include [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) for LLM integration and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) for API retry handling.

### Can I update a candidate’s hiring status using the command line?

No. The CLI and library functions only support résumé parsing and score generation. There is no built-in mechanism to store or update discrete hiring statuses such as "Rejected" or "Offer Extended."

### What is the fastest way to add status update functionality to this repository?

Implement a FastAPI wrapper service that imports the existing evaluation functions. Create a `PATCH /candidates/{id}/status` endpoint that updates a database record, and optionally wire the `evaluate_resume()` function to trigger when résumés are re-uploaded.