API reference
The hiring API has 16 operations generated from the code, each listed below with its method, path, scopes and fields, plus routes for jobs, candidates, webhook subscriptions and bulk invitations. Requests and responses are JSON, and every call needs a Bearer API key with the scopes named.
Reference · Last checked against the product on
Conventions
- Base URL:
https://hiring.virtualinterview.ai/api/v1/hiring. - GET operations take their fields as query parameters. POST operations take a JSON body. A
{id}in a path is part of the URL. - Timestamps are ISO 8601 strings in UTC. A field with no value is usually
null. - Responses are not cached; read them fresh each time.
curl -X POST https://hiring.virtualinterview.ai/api/v1/hiring/applications/APP_ID/stage \
-H "Authorization: Bearer $VI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "DEBRIEF", "reason": "Panel finished" }'The same operations are published as an OpenAPI 3.1 document at /api/v1/openapi.json, with request and response schemas. It needs no key. Operation ids below match the document’s operationId and the MCP tool names.
Operations
Stage names are the values of stage in each response, for example APPLIED, DEBRIEF or HIRED. Moves into a human-only stage need decisions:human; see Authentication and scopes.
overrideProposal takes a reasonCode from this list: disagree_with_evidence, need_more_evidence, role_on_hold, candidate_withdrew, better_fit_elsewhere or other.
List applications, optionally by stage or job
GET /api/v1/hiring/applicationsOperation listApplications. Scopes: applications:read.
| Field | Type | Required |
|---|---|---|
stage | string | No |
jobId | string | No |
limit | integer | No |
| Field | Type | Required |
|---|---|---|
applications | object[] | Yes |
One application with its stage history
GET /api/v1/hiring/applications/{id}Operation getApplication. Scopes: applications:read.
| Field | Type | Required |
|---|---|---|
application | object | Yes |
transitions | object[] | Yes |
Move an application to a stage. Reject, offer and hire need a human-scoped key; reject and screen-out need a reasonCode
POST /api/v1/hiring/applications/{id}/stageOperation moveApplication. Scopes: applications:write.
| Field | Type | Required |
|---|---|---|
to | "APPLIED" | "SCREENING" | "SCREENED_IN" | "SCREENED_OUT" | "NEEDS_REVIEW" | "INTERVIEW_SCHEDULED" | "INTERVIEW_IN_PROGRESS" | "INTERVIEW_COMPLETED" | "DEBRIEF" | "OFFERED" | "ACCEPTED" | "HIRED" | "REJECTED" | "WITHDRAWN" | Yes |
reason | string | No |
| Field | Type | Required |
|---|---|---|
application | object | Yes |
Import applicants onto a job (from an ATS or a spreadsheet). Never sends mail
POST /api/v1/hiring/applications/importOperation importApplicants. Scopes: applications:write.
| Field | Type | Required |
|---|---|---|
jobId | string | Yes |
applicants | object[] | Yes |
| Field | Type | Required |
|---|---|---|
created | integer | Yes |
existing | integer | Yes |
Agent advice for an application: interview recommendation, debrief memo and competency assessment
GET /api/v1/hiring/recommendationsOperation listRecommendations. Scopes: recommendations:read.
| Field | Type | Required |
|---|---|---|
applicationId | string | Yes |
| Field | Type | Required |
|---|---|---|
recommendation | object | null | Yes |
debrief | object | null | Yes |
competencyAssessment | object | null | Yes |
Scorecards filed on an application's interview
GET /api/v1/hiring/scorecardsOperation listScorecards. Scopes: scorecards:read.
| Field | Type | Required |
|---|---|---|
applicationId | string | Yes |
| Field | Type | Required |
|---|---|---|
scorecards | object[] | Yes |
File a scorecard as the key's creator: one {key, score 1-5} per rubric competency, with the 0-100 overall and the recommendation computed (scale rubric-1-5). The old 1-10 shape is still accepted
POST /api/v1/hiring/scorecardsOperation submitScorecard. Scopes: scorecards:write.
| Field | Type | Required |
|---|---|---|
applicationId | string | Yes |
overallScore | number | Yes |
recommendation | "STRONG_YES" | "YES" | "MAYBE" | "NO" | "STRONG_NO" | Yes |
notes | string | No |
criteria | object[] | Yes |
| Field | Type | Required |
|---|---|---|
scorecardId | string | Yes |
Interview schedule requests and their booked times
GET /api/v1/hiring/schedulesOperation listSchedules. Scopes: schedules:read.
| Field | Type | Required |
|---|---|---|
applicationId | string | No |
| Field | Type | Required |
|---|---|---|
schedules | object[] | Yes |
Ask the scheduling agent to propose slots with a panel
POST /api/v1/hiring/schedulesOperation requestSchedule. Scopes: schedules:write.
| Field | Type | Required |
|---|---|---|
applicationId | string | Yes |
panelistUserIds | string[] | Yes |
durationMinutes | integer | No |
timeZone | string | No |
| Field | Type | Required |
|---|---|---|
queued | boolean | Yes |
jobId | string | Yes |
Offers and their status
GET /api/v1/hiring/offersOperation listOffers. Scopes: offers:read.
| Field | Type | Required |
|---|---|---|
status | string | No |
| Field | Type | Required |
|---|---|---|
offers | object[] | Yes |
Create an offer DRAFT, pre-filled from the job's comp band. Sending stays with a person in the portal
POST /api/v1/hiring/offersOperation draftOffer. Scopes: offers:draft.
| Field | Type | Required |
|---|---|---|
applicationId | string | Yes |
salaryAmount | number | No |
salaryCurrency | string | No |
startDate | string | No |
| Field | Type | Required |
|---|---|---|
offer | object | Yes |
note | string | Yes |
Goal, live status per stage and blockers for a job
GET /api/v1/hiring/jobs/{id}/planOperation getJobPlan. Scopes: plans:read.
| Field | Type | Required |
|---|---|---|
plan | object | Yes |
Set headcount, target date, comp band and pause for a job
POST /api/v1/hiring/jobs/{id}/goalOperation setJobGoal. Scopes: plans:write.
| Field | Type | Required |
|---|---|---|
headcount | integer | null | No |
targetDate | string | null | No |
compBand | object | null | No |
paused | boolean | No |
defaultPanelUserIds | string[] | No |
meetingType | "auto" | "meet" | "teams" | "zoom" | "phone" | "onsite" | No |
meetingDetail | string | null | No |
nextSteps | string | null | No |
responseDays | integer | null | No |
steps | object | No |
| Field | Type | Required |
|---|---|---|
goal | object | Yes |
Open agent proposals awaiting a person
GET /api/v1/hiring/proposalsOperation listProposals. Scopes: proposals:read.
| Field | Type | Required |
|---|---|---|
proposals | object[] | Yes |
Approve a proposal as the key's creator (human-scoped key)
POST /api/v1/hiring/proposals/{id}/approveOperation approveProposal. Scopes: proposals:write.
| Field | Type | Required |
|---|---|---|
proposal | object | Yes |
moved | string | null | Yes |
prefill | object | null | Yes |
queued | string | null | Yes |
offerDraftId | string | null | Yes |
Override a proposal with a required reason code (human-scoped key)
POST /api/v1/hiring/proposals/{id}/overrideOperation overrideProposal. Scopes: proposals:write.
| Field | Type | Required |
|---|---|---|
reasonCode | string | Yes |
note | string | null | No |
| Field | Type | Required |
|---|---|---|
proposal | object | Yes |
Jobs and candidates
| Route | Scope | What it does |
|---|---|---|
GET /api/v1/hiring/jobs | jobs:read | Lists jobs, newest first. Query: page, limit, status (active or inactive). |
POST /api/v1/hiring/jobs | jobs:write | Creates an active job. Body: title (required), company, location, jobType, description. Answers 201 with the job in data. |
GET /api/v1/hiring/candidates | candidates:read | Lists interview invitations with their status and scores. Query: page, limit, jobId, status. |
A job has id, title, company, location, jobType, description, isActive, createdAt and updatedAt. jobType is one of FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, TEMPORARY or OTHER.
A candidate row has id, candidateEmail, candidateName, status, interviewScore, resumeMatchScore, createdAt, completedAt and job (id and title). An unknown status answers 400 and lists the accepted values.
Both lists are paged the same way:
{
"data": [ … ],
"pagination": { "page": 1, "limit": 20, "total": 57, "totalPages": 3 }
}Bulk invitations
POST /api/v1/invitations invites candidates to a job’s interview, exactly as an invitation sent from the portal does: each candidate gets the invitation email and each invitation uses one interview from your organisation’s plan. It needs the invitations:write scope. Note the path: it sits under /api/v1, not /api/v1/hiring.
{
"jobId": "JOB_ID",
"candidates": [
{ "email": "sam@example.com", "name": "Sam Lee" }
]
}expiresInDays is optional; leave it out to use the default expiry. Each call takes a bounded batch of candidates. The response reports every candidate:
{
"created": 1,
"skipped": 0,
"total": 1,
"results": [ { "email": "sam@example.com", "invitationId": "cm4…" } ]
}A candidate is skipped, with a reason in error, when they were already invited to the job, the address cannot receive mail, or the plan has no interviews left (No interviews remaining). An invitation that fails is not charged. A draft or closed job answers 409 before anything is spent. Plans are described in Hiring plans and usage.
Webhook subscriptions
| Route | Scope | What it does |
|---|---|---|
GET /api/v1/hiring/webhooks | webhooks:read | Lists your endpoints with their events, whether they are active and when they last received a delivery. |
POST /api/v1/hiring/webhooks | webhooks:write | Registers an endpoint. Body: url, events, optional secret. |
DELETE /api/v1/hiring/webhooks?id=… | webhooks:write | Removes an endpoint. |