Put verified assessment inside the system you already use.
Hirovia is a measurement layer, not another place to log in. Four ways to connect it — from a mail rule that takes two minutes to a full REST integration with your ATS.
Get a sandbox key — free Read the API reference
Sandbox candidates are never billed · no card to start
Four ways to connect, in order of effort.
Cc or forward applications to your private intake address. Hirovia reads the sender, matches the position from the subject, stores the résumé and invites the candidate. A Gmail or Outlook forwarding rule is the entire integration.
Best for: teams whose applications already arrive by emailA white-label application page under your company's name. Link it from your careers site or embed it in an iframe. Candidates apply and are assessed in one flow.
Best for: careers pages without an ATS behind themPaste a list of names and emails, pick the position, and every applicant gets a unique link. Export scored results back out as CSV.
Best for: one-off campaigns and pilotsCreate candidates from your ATS the moment an application lands, poll for scores, and write the composite back onto your own record. JSON in, JSON out, bearer-token auth.
Best for: ATS vendors, RPOs, and anyone with an internal hiring systemBounces and spam complaints are reported back automatically, so an invitation to a mistyped address shows up as a problem instead of silence.
Included with every methodA sandbox key creates real candidate records that are never billed — and lets you simulate a completed assessment, so you can test your scoring logic without sitting a 30-minute test.
Free, unlimitedWhat integration actually buys you.
If you run hiring
- Assessment starts the second an application lands, not when someone gets round to it
- Scores live next to your own candidate records — no second system to check
- Your ATS can sort, filter and reject on verified capability instead of keyword match
- No copy-paste step to forget on a busy day
If you build hiring software
- Add a real assessment layer without building psychometrics or hiring an I/O psychologist
- 20 researched role profiles, scoring, validity checks and interview guides, ready to use
- White-label: your users never see our brand
- Per-assessment pricing you can resell, from $0.25 at volume
The API in five endpoints.
Base URL https://hirovia.com/api/v1. Authenticate with a bearer token
from Settings → API. Keys beginning hv_test_ are sandbox;
hv_live_ are real and count toward your plan. 120 requests per minute per key.
| Endpoint | Does |
|---|---|
GET /ping | Confirms the key works and tells you which mode you're in |
GET /roles | The 20 position ids you can assess for |
POST /candidates | Creates a candidate and returns their unique assessment link |
GET /candidates | Lists candidates, filterable by status and position |
GET /candidates/{id} | One candidate with scores; add ?include=report for the full report |
POST /candidates/{id}/simulate | Sandbox only. Fakes a completed assessment so you can test result handling |
Create a candidate
curl -X POST https://hirovia.com/api/v1/candidates \
-H "Authorization: Bearer hv_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"email": "jane@example.com",
"role": "cam",
"send_email": true
}'
{
"id": 412,
"name": "Jane Doe",
"role": "cam",
"role_title": "Corporate Accounts Manager",
"status": "invited",
"test": true,
"assessment_url": "https://hirovia.com/a/xJ2f8Kq1",
"invitation_emailed": false
}
Send the candidate to assessment_url yourself, or set
send_email and Hirovia emails them under your company's name.
Read the result
curl https://hirovia.com/api/v1/candidates/412 \ -H "Authorization: Bearer hv_test_..."
{
"id": 412,
"status": "completed",
"completed_at": "2026-08-19T10:41:00Z",
"scores": {
"composite": 89,
"role_fit": 90,
"band": "Exceptional",
"scenarios_pct": 78,
"validity_flags": []
}
}
composite is the 0–100 ranking number. band is the
plain-language reading of role fit. A non-empty validity_flags means the responses
looked careless or gamed — treat that profile with suspicion regardless of its score.
Test the whole loop without a real candidate
curl -X POST https://hirovia.com/api/v1/candidates/412/simulate \
-H "Authorization: Bearer hv_test_..." \
-H "Content-Type: application/json" \
-d '{"band": "weak"}'
Returns a fully-formed completed candidate, including the report structure,
so you can build and test your result handling in minutes. Pass "band": "weak" to get
a flagged, low-scoring profile and check your unhappy path too.
Errors
Every failure returns the same shape, with an HTTP status that means what it says.
{ "error": { "message": "unknown role 'manager' - call GET /api/v1/roles for valid ids",
"status": 400 } }
| Status | Meaning |
|---|---|
| 400 | Something in your request is wrong; the message says what |
| 401 | Missing, invalid or revoked key |
| 402 | Free trial exhausted — add a payment method |
| 403 | Sandbox-only endpoint called with a live key |
| 404 | No such candidate in your account |
| 429 | Over 120 requests in a minute |
API candidates bill exactly like every other candidate.
What counts
- Only completed assessments. Creating a candidate through the API is free, the same as any invitation
- Live-key candidates count toward your plan's included volume and your monthly invoice
- Volume rates apply automatically — down to $0.25 per assessment at scale
- Your first five candidates are free, however they were created
What never counts
- Sandbox candidates are never billed and never consume your free trial
- Simulated completions are free and unlimited
- Invitations that are never taken cost nothing, ever
- Bounced or undelivered invitations cost nothing
So you can build and test the entire integration at zero cost, then swap one key to go live.
Get a sandbox key and try it now.
Free, unlimited, and nothing bills until you swap in a live key.