Skip to main content
VirtualInterview.ai
Docs menu

Hiring API overview

The hiring API lets your own systems read and update the hiring portal: applications, scorecards, schedules, offers, job goals, agent proposals, jobs, candidates, invitations and webhooks. Every call runs inside one organisation, under one API key and its scopes. Moves that decide a candidate’s outcome need a key a person controls.

Explanation · Last checked against the product on

What the API covers

There are four ways to connect. All of them use the same API keys, created under Settings → Developers in the hiring portal.

Ways to connect
SurfaceWhereUse it to
REST API/api/v1/hiring/…Read and update hiring records. 16 operations come from one shared list, plus jobs, candidates and webhook subscriptions.
Bulk invitations/api/v1/invitationsInvite candidates to a job’s interview from another system.
MCP server/api/mcpLet an AI agent call the same operations as tools, with the same scopes.
WebhooksYour HTTPS endpointReceive signed events when something changes in the portal.

Each operation is listed with its method, path, scopes and fields in the API reference.

One organisation per key

A key belongs to the organisation it was created in. Every request reads and writes only that organisation’s data: an application, job or offer from another organisation answers as not found.

A key also stops working at once if the organisation is suspended or locked for deletion, and when someone revokes it in the portal. Writes made with a key are recorded under the person who created it.

People make hiring decisions

Agents and integrations may propose; a person decides. The API enforces this with the decisions:human scope:

  • Moving an application to REJECTED, SCREENED_OUT, OFFERED, ACCEPTED or HIRED is refused unless the key carries decisions:human.
  • Approving or overriding an agent proposal needs it too.
  • An offer can only be drafted through the API. Sending it to the candidate stays with a person in the portal.

Grant decisions:human only to a key that a person operates, never to an unattended agent. The full scope list is in Authentication and scopes.

Versioning and the OpenAPI document

Every path starts with /api/v1. The REST operations are also published as an OpenAPI 3.1 document, which needs no key: /api/v1/openapi.json. Import it into an API client or a code generator to get request and response types.

The REST routes, the OpenAPI document and the MCP server read one list of operations, so a field added to one appears in all three.

Where you’ll see this

In the hiring portal, open Settings → Developers. The page has two cards, API Keys and Webhooks, and links to the quickstart, this reference and the OpenAPI document. Only people whose role includes Manage Integrations & API Keys see the tab; see Roles and permissions.

Was this page clear?