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
- Sign in to the hiring portal and open Settings → Developers.
- In the API Keys card, click New key.
- In Create API key, type a Name that says where the key will live, for example the system that will use it.
- Under Scopes, tick
applications:read. The dialog starts withinvitations:readticked; untick anything this key does not need. - 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:
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:
{
"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:
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.