Replace phone-tag reference checks with one API call.

Why teams switch to VerifyRef

• ✓One API call replaces manual chasing — consent, reminders, and collection are automated
• ✓~95% reference response rate with built-in 3- and 7-day reminders
• ✓AI sentiment scoring and red-flag detection on every response
• ✓Pay per check — no monthly subscription needed like Xref or Referoo
• ✓3 free credits on sign-up, no credit card required
• ✓Sandbox keys (rc_test_) let you dry-run the full flow for free

Compare pricing and features on our alternatives page.

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. Create a reference check — POST /api/v1/checks with candidate details, references, questionnaireId, externalId + externalSource, and Idempotency-Key header.
4. Register a webhook — POST /api/v1/webhooks subscribing to check.completed, or use the dashboard after signing in.
5. Verify inbound signatures — Validate X-VerifyRef-Signature (HMAC-SHA256) on every inbound webhook POST.
6. 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. You can also manage keys programmatically once you have a live key.

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." }]
      }
    ]
  }
}

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.

For AI assistants & agents

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

• /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 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.