Skip to main content
VirtualInterview.ai
Docs menu

API quickstart

Create an API key under Settings → Developers in the hiring portal, give it the applications:read scope, and send it as a Bearer token to /api/v1/hiring/applications. You get back your organisation’s applications as JSON. The whole path takes a few minutes and needs only curl.

Start here · Last checked against the product on

Before you start

You need a hiring portal account whose role includes Manage Integrations & API Keys. Owners and admins have it by default. If you don’t see Developers under Settings, ask one of them, or see Roles and permissions.

Create a key

  1. Sign in to the hiring portal and open Settings → Developers.
  2. In the API Keys card, click New key.
  3. In Create API key, type a Name that says where the key will live, for example the system that will use it.
  4. Under Scopes, tick applications:read. The dialog starts with invitations:read ticked; untick anything this key does not need.
  5. Click Create key. The API key created dialog shows the key once. Copy it into your secret store now: the portal keeps only a hash and shows just the first characters afterwards.

Make your first request

Put the key in an environment variable, then call the applications list:

Shell
curl https://hiring.virtualinterview.ai/api/v1/hiring/applications \
  -H "Authorization: Bearer $VI_API_KEY"

A successful call returns status 200 and a body like this:

Response
{
  "applications": [
    {
      "id": "cm3…",
      "number": 42,
      "jobId": "cm2…",
      "stage": "INTERVIEW_COMPLETED",
      "candidate": { "name": "Sam Lee", "email": "sam@example.com" },
      "resumeMatchScore": null,
      "interviewScore": null,
      "lastTransitionAt": "2026-11-14T09:30:00.000Z"
    }
  ]
}

Scores are null until the candidate has been scored. Narrow the list with query parameters:

Shell
curl "https://hiring.virtualinterview.ai/api/v1/hiring/applications?stage=DEBRIEF&limit=10" \
  -H "Authorization: Bearer $VI_API_KEY"

A 401 means the key is wrong, revoked or its organisation is not active. A 403 means the key lacks the scope; the error names the one it needs. Every status is listed in Errors and rate limits.

What’s next

  • Browse every operation and its fields in the API reference.
  • Get told about changes instead of polling: Webhooks.
  • Give an AI agent the same access through the MCP server.
Was this page clear?