Find recruits, then verify them — one REST API.

Why teams switch to VerifyRef

• ✓Talent pool first — upload resumes and AI-match to a JD for free, then verify shortlists
• ✓One API call replaces manual chasing — consent, reminders, and collection are automated
• ✓~95% reference response rate with built-in 24- and 72-hour reminders
• ✓AI sentiment scoring and red-flag detection on every response
• ✓Pay per use — no monthly subscription needed like Xref or Referoo
• ✓Sandbox keys (rc_test_) let you dry-run the full flow for free

Compare pricing and features on our alternatives page. Prefer MCP for agent hosts? See AI agents & MCP.

Setup checklist

Copy this sequence when scaffolding an integration or guiding a setup assistant:

1. Create a sandbox API key — Sign up at verifyref.com, then open Dashboard → Developer settings and create an rc_test_ key (free, no emails sent).
2. Validate the key — GET /api/v1/account with Authorization: Bearer rc_test_... to confirm the key works.
3. Upload resumes (optional) — POST /api/v1/talent-pool/candidates with a PDF/DOCX resume — free, no credits.
4. Match to a job (optional) — POST /api/v1/talent-pool/match with a jobDescription to get top fits with scores.
5. Create a reference check — POST /api/v1/checks with candidate details (or candidateId), references, questionnaireId or inline questions, optional externalId + externalSource, and Idempotency-Key.
6. Register a webhook — POST /api/v1/webhooks with url + events (e.g. check.completed), or use the dashboard after signing in.
7. Verify inbound signatures — Validate X-VerifyRef-Signature (HMAC-SHA256) on every inbound webhook POST.
8. Write results to your ATS — On check.completed, use externalId to match the ATS record and store dashboardUrl and reportUrl.

What you can build

Quick start

1. Grab a sandbox key. Sign up free, then open Dashboard → Developer settings (requires login) and create an rc_test_ key — free, no credits charged, no real emails sent.
2. Create a check. Pass externalId + externalSource so we can correlate the result back to your ATS record. Set questionnaireId to a template ID from Templates in the dashboard.
3. Listen for webhooks. Register a URL once; we POST signed events as the check progresses.

curl -X POST https://verifyref.com/api/v1/checks \
  -H "Authorization: Bearer rc_test_..." \
  -H "Idempotency-Key: ats-app-12345" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "candidateName": "Jane Doe",
    "candidateEmail": "jane@example.com",
    "externalId": "12345",
    "externalSource": "bullhorn",
    "metadata": { "requisitionId": "REQ-99" },
    "questionnaireId": "YOUR_TEMPLATE_ID",
    "references": [
      { "name": "Ref Name", "email": "ref@example.com", "relationship": "Manager" }
    ]
  }'

import crypto from "node:crypto";

export function verifyVerifyRef(rawBody: string, signature: string, secret: string) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Authentication

Every request uses a Bearer token in the Authorization header. Generate keys in Dashboard → Developer settings (requires login) — only the team owner can create or revoke them. There is no public API for creating or rotating keys; manage them in the dashboard.

Keep secrets server-side. Never embed an API key in a browser, mobile app, or public repo. Rotate immediately if a key is exposed.

Base URL & versioning

All examples on this page use VerifyRef's production API host (https://verifyref.com). API keys work against this URL whether you read these docs locally or on verifyref.com — examples never use a dev-only host.

Every response includes an X-VerifyRef-Version header so you can pin behavior. Breaking changes always ship under a new version date.

Idempotency

Network retries are inevitable. Send the same Idempotency-Key header on POST /checksand we'll return the original check instead of creating a duplicate.

• Use a stable, unique value per logical request (e.g. your ATS application ID).
• Replays return the same response shape with idempotentReplay: true.
• Keys are scoped per team; rotate freely between live and sandbox.

Endpoints

{ "data": { "team": "Acme Corp", "credits": 150 } }

{
  "success": true,
  "checkId": "clx...",
  "status": "AWAITING_CONSENT",
  "jobId": "job_...",
  "externalId": "12345",
  "externalSource": "bullhorn",
  "sandbox": false
}

{
  "data": {
    "id": "clx...",
    "status": "COMPLETED",
    "candidate": { "name": "John Doe", "email": "john@example.com" },
    "externalId": "12345",
    "externalSource": "bullhorn",
    "metadata": { "requisitionId": "REQ-99" },
    "dashboardUrl": "https://verifyref.com/check/clx...",
    "reportUrl": "https://verifyref.com/api/export/check/clx...",
    "references": [
      {
        "name": "Jane Smith",
        "relationship": "Manager",
        "status": "COMPLETED",
        "sentiment": { "score": 0.9, "label": "POSITIVE", "analysis": "..." },
        "redFlags": { "score": 0, "flags": [], "analysis": "No red flags." },
        "responses": [{ "question": "Would you hire them again?", "answer": "Yes." }]
      }
    ]
  }
}

Talent pool (free)

No credits. Upload resumes, filter, and AI-match candidates to a job description.

curl -X POST https://verifyref.com/api/v1/talent-pool/candidates \
  -H "Authorization: Bearer rc_test_..." \
  -F "resume=@./candidate.pdf"

Jobs, templates & credits

Video interviews & surveys

Webhooks CRUD

Requires a prior credit purchase on the team. Full event docs are in Webhooks below.

{
  "url": "https://example.com/hooks/verifyref",
  "events": ["check.completed", "email.bounced"]
}

Webhooks

Register HTTPS endpoints in Dashboard → Developer settings (requires login) or via POST /webhooks. We POST a signed JSON payload for every subscribed event, retry on failure with exponential backoff, and surface delivery status in your dashboard.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "check.completed",
  "timestamp": "2026-05-20T10:30:00Z",
  "data": {
    "checkId": "clx...",
    "candidateName": "Jane Doe",
    "candidateEmail": "jane@example.com",
    "status": "COMPLETED",
    "externalId": "12345",
    "externalSource": "bullhorn",
    "metadata": { "requisitionId": "REQ-99" },
    "dashboardUrl": "https://verifyref.com/check/clx...",
    "reportUrl": "https://verifyref.com/api/export/check/clx...",
    "completedAt": "2026-05-20T10:30:00Z"
  }
}

Errors & rate limits

Errors always return JSON in the shape { "error": { "code", "message", "details?" } }. The v1 rate limit is 100 requests/minute per API key.

Dashboard-only features

These product features are available in the VerifyRef dashboard but are not exposed on the public REST API (v1) today:

• Exit interviews — same credit model as employee surveys (1 credit per 2 recipients); create and analyze in the dashboard. See Exit Interviews.
• Voice reference completion — referees can optionally complete feedback via an AI voice conversation on the questionnaire link; written responses remain the default.
• API key management — create and revoke keys only in Developer settings (no key CRUD API).
• Template & job editing — API can list templates and create/list jobs; full edit UX is in the dashboard.

For AI assistants & agents

Building a setup assistant on top of VerifyRef? Anchor on these public, crawlable resources (no login required):

• /docs/agents — MCP install, tool workflow, credit purchase
• /AGENTS.md — short agent quickstart
• /openapi.yaml — machine-readable spec
• /llms.txt — product summary, setup checklist, and link map
• /docs/integrations — ATS recipes and field mappings
• #setup-checklist — numbered integration steps on this page

Dashboard URLs (/team/api, /team/integrations) require the user to sign in. For unattended setup, use the REST API or MCP with a key the user provides, or direct them to /sign-up first. Default to sandbox keys (rc_test_) when scaffolding — no credits charged, no emails sent.