把经验证的测评，放进你已经在用的系统里。

四种接入方式，按投入从少到多排列。

集成到底换来了什么。

六个端点，讲完整套 API。

基础 URL 为 https://hirovia.com/api/v1。使用 设置 → API 中的 bearer token 鉴权。以 hv_test_ 开头的密钥属于沙盒；hv_live_ 是正式密钥，会计入你的方案用量。每个密钥每分钟 120 次请求。

创建候选人

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
}

你可以自行把候选人引导到 assessment_url，也可以设置 send_email，由 Hirovia 以贵公司的名义给他们发邮件。

读取结果

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 是 0–100 的排序分数。band 是对岗位匹配度的通俗表述。validity_flags 非空，说明作答显得敷衍或存在作假 — 无论分数多高，都应对这份档案保持怀疑。

不用真实候选人就能跑通整个流程

curl -X POST https://hirovia.com/api/v1/candidates/412/simulate \
  -H "Authorization: Bearer hv_test_..." \
  -H "Content-Type: application/json" \
  -d '{"band": "weak"}'

返回一位结构完整的已完成候选人，包含报告结构，让你几分钟内就能构建并测试自己的结果处理逻辑。传入 "band": "weak"，可得到一份被标记的低分档案，顺便验证异常路径。

{ "error": { "message": "unknown role 'manager' - call GET /api/v1/roles for valid ids",
             "status": 400 } }

通过 API 创建的候选人，计费方式与其他候选人完全一致。