Skip to main content
VirtualInterview.ai
Docs menu

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.
A POST with a body
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/applications

Operation listApplications. Scopes: applications:read.

Query parameters
FieldTypeRequired
stagestringNo
jobIdstringNo
limitintegerNo
Response
FieldTypeRequired
applicationsobject[]Yes

One application with its stage history

GET /api/v1/hiring/applications/{id}

Operation getApplication. Scopes: applications:read.

Response
FieldTypeRequired
applicationobjectYes
transitionsobject[]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}/stage

Operation moveApplication. Scopes: applications:write.

Request body
FieldTypeRequired
to"APPLIED" | "SCREENING" | "SCREENED_IN" | "SCREENED_OUT" | "NEEDS_REVIEW" | "INTERVIEW_SCHEDULED" | "INTERVIEW_IN_PROGRESS" | "INTERVIEW_COMPLETED" | "DEBRIEF" | "OFFERED" | "ACCEPTED" | "HIRED" | "REJECTED" | "WITHDRAWN"Yes
reasonstringNo
Response
FieldTypeRequired
applicationobjectYes

Import applicants onto a job (from an ATS or a spreadsheet). Never sends mail

POST /api/v1/hiring/applications/import

Operation importApplicants. Scopes: applications:write.

Request body
FieldTypeRequired
jobIdstringYes
applicantsobject[]Yes
Response
FieldTypeRequired
createdintegerYes
existingintegerYes

Agent advice for an application: interview recommendation, debrief memo and competency assessment

GET /api/v1/hiring/recommendations

Operation listRecommendations. Scopes: recommendations:read.

Query parameters
FieldTypeRequired
applicationIdstringYes
Response
FieldTypeRequired
recommendationobject | nullYes
debriefobject | nullYes
competencyAssessmentobject | nullYes

Scorecards filed on an application's interview

GET /api/v1/hiring/scorecards

Operation listScorecards. Scopes: scorecards:read.

Query parameters
FieldTypeRequired
applicationIdstringYes
Response
FieldTypeRequired
scorecardsobject[]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/scorecards

Operation submitScorecard. Scopes: scorecards:write.

Request body
FieldTypeRequired
applicationIdstringYes
overallScorenumberYes
recommendation"STRONG_YES" | "YES" | "MAYBE" | "NO" | "STRONG_NO"Yes
notesstringNo
criteriaobject[]Yes
Response
FieldTypeRequired
scorecardIdstringYes

Interview schedule requests and their booked times

GET /api/v1/hiring/schedules

Operation listSchedules. Scopes: schedules:read.

Query parameters
FieldTypeRequired
applicationIdstringNo
Response
FieldTypeRequired
schedulesobject[]Yes

Ask the scheduling agent to propose slots with a panel

POST /api/v1/hiring/schedules

Operation requestSchedule. Scopes: schedules:write.

Request body
FieldTypeRequired
applicationIdstringYes
panelistUserIdsstring[]Yes
durationMinutesintegerNo
timeZonestringNo
Response
FieldTypeRequired
queuedbooleanYes
jobIdstringYes

Offers and their status

GET /api/v1/hiring/offers

Operation listOffers. Scopes: offers:read.

Query parameters
FieldTypeRequired
statusstringNo
Response
FieldTypeRequired
offersobject[]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/offers

Operation draftOffer. Scopes: offers:draft.

Request body
FieldTypeRequired
applicationIdstringYes
salaryAmountnumberNo
salaryCurrencystringNo
startDatestringNo
Response
FieldTypeRequired
offerobjectYes
notestringYes

Goal, live status per stage and blockers for a job

GET /api/v1/hiring/jobs/{id}/plan

Operation getJobPlan. Scopes: plans:read.

Response
FieldTypeRequired
planobjectYes

Set headcount, target date, comp band and pause for a job

POST /api/v1/hiring/jobs/{id}/goal

Operation setJobGoal. Scopes: plans:write.

Request body
FieldTypeRequired
headcountinteger | nullNo
targetDatestring | nullNo
compBandobject | nullNo
pausedbooleanNo
defaultPanelUserIdsstring[]No
meetingType"auto" | "meet" | "teams" | "zoom" | "phone" | "onsite"No
meetingDetailstring | nullNo
nextStepsstring | nullNo
responseDaysinteger | nullNo
stepsobjectNo
Response
FieldTypeRequired
goalobjectYes

Open agent proposals awaiting a person

GET /api/v1/hiring/proposals

Operation listProposals. Scopes: proposals:read.

Response
FieldTypeRequired
proposalsobject[]Yes

Approve a proposal as the key's creator (human-scoped key)

POST /api/v1/hiring/proposals/{id}/approve

Operation approveProposal. Scopes: proposals:write.

Response
FieldTypeRequired
proposalobjectYes
movedstring | nullYes
prefillobject | nullYes
queuedstring | nullYes
offerDraftIdstring | nullYes

Override a proposal with a required reason code (human-scoped key)

POST /api/v1/hiring/proposals/{id}/override

Operation overrideProposal. Scopes: proposals:write.

Request body
FieldTypeRequired
reasonCodestringYes
notestring | nullNo
Response
FieldTypeRequired
proposalobjectYes

Jobs and candidates

Jobs and candidates routes
RouteScopeWhat it does
GET /api/v1/hiring/jobsjobs:readLists jobs, newest first. Query: page, limit, status (active or inactive).
POST /api/v1/hiring/jobsjobs:writeCreates an active job. Body: title (required), company, location, jobType, description. Answers 201 with the job in data.
GET /api/v1/hiring/candidatescandidates:readLists 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:

List response
{
  "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.

Request body
{
  "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:

Response
{
  "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

Webhook subscription routes
RouteScopeWhat it does
GET /api/v1/hiring/webhookswebhooks:readLists your endpoints with their events, whether they are active and when they last received a delivery.
POST /api/v1/hiring/webhookswebhooks:writeRegisters an endpoint. Body: url, events, optional secret.
DELETE /api/v1/hiring/webhooks?id=…webhooks:writeRemoves an endpoint.
Was this page clear?