Verify Ref Logo

API Documentation

A complete guide to integrating automated reference checks into your own applications using the VerifyRef API.

Getting Started

VerifyRef's API follows RESTful conventions and returns data in JSON format. It is designed to be simple to use for any developer familiar with standard web APIs.

Note: API access is available to all Team plans. Each request that creates a check will consume credits from your team's balance.

Authentication

All API requests must be authenticated using an API Key. You can generate and manage your API keys in the Team Settings page of your dashboard.

Include your API key in the Authorization header of every request using the Bearer token scheme:

Authorization: Bearer rc_live_7d8f...

Security Tip: Never expose your API key in client-side code (like inside a React app or HTML file). Always make requests from your secure backend server.

Base URL

All endpoints are relative to the following base URL:

https://verifyref.com/api/v1

Endpoints

GET/account

Retrieves details about your team's account, including the current credit balance. Use this to verify your API key connection and check if you have enough credits before creating a check.

Example Response

{
  "data": {
    "team": "Acme Corp",
    "credits": 150
  }
}
GET/jobs

Returns a list of all jobs (positions) created by your team.

Example Response

{
  "data": [
    {
      "id": "job_123...",
      "title": "Senior Frontend Engineer",
      "status": "OPEN",
      "location": "Remote",
      "department": "Engineering"
    }
  ]
}
POST/jobs

Create a new job position to group your reference checks.

Request Body Parameters

  • title * (string): Job title.
  • description (string): Job description.
  • location (string): e.g. "New York, NY".
  • department (string): e.g. "Sales".

Example Request

{
  "title": "Product Manager",
  "location": "London",
  "department": "Product"
}

Success Response

{
  "success": true,
  "data": {
    "id": "job_789...",
    "title": "Product Manager",
    "status": "OPEN"
  }
}
GET/templates

Returns a list of all questionnaire templates available to your team. You can use the id of a template when creating a new check to automatically use its questions.

Example Response

{
  "data": [
    {
      "id": "cm1...",
      "title": "Standard Engineering Reference",
      "description": "For senior backend roles"
    },
    {
      "id": "cm2...",
      "title": "Sales Representative Check",
      "description": null
    }
  ]
}
POST/checks

Creates a new reference check request. This action will:

  • Create a new check in your dashboard.
  • Send an email to the candidate asking for their consent.
  • Deduct 1 credit from your team's balance.

Request Body Parameters

  • candidateName * (string): Full name of the candidate.
  • candidateEmail * (string): Email address of the candidate.
  • references * (array): List of reference objects.
  • jobId (string): ID of an existing job to associate this check with.
  • newJob (object): Or create a new job inline (see parameters above).
  • questionnaireId (string): The ID of an existing template.

Example Request (With Job)

{
  "candidateName": "Alice Johnson",
  "candidateEmail": "alice@example.com",
  "jobId": "job_123...",
  "questionnaireId": "cm1...", 
  "references": [
    {
      "name": "Bob Smith",
      "email": "bob@previous-company.com",
      "relationship": "Direct Manager"
    }
  ]
}

Success Response

{
  "success": true,
  "checkId": "clx...",
  "status": "AWAITING_CONSENT",
  "jobId": "job_123..."
}
GET/checks/:id

Retrieves the full details and results of a specific reference check, including AI analysis and red flags.

Example Response

{
  "data": {
    "id": "clx...",
    "status": "COMPLETED",
    "candidate": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "job": {
      "title": "Senior Engineer",
      "status": "OPEN"
    },
    "references": [
      {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "relationship": "Manager",
        "status": "BOUNCED",
        "sentiment": null,
        "redFlags": null,
        "responses": []
      },
      {
        "name": "Bob Jones",
        "email": "bob@example.com",
        "relationship": "Peer",
        "status": "COMPLETED",
        "sentiment": {
          "score": 0.9,
          "label": "POSITIVE",
          "analysis": "Reference was highly complimentary..."
        },
        "redFlags": {
          "score": 0,
          "flags": [],
          "analysis": "No red flags detected."
        },
        "responses": [
          {
            "question": "Would you hire them again?",
            "answer": "Absolutely, without hesitation."
          }
        ]
      }
    ]
  }
}

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your VerifyRef account. Instead of polling the API for changes, webhooks will push data to your server as events happen.

Setting Up Webhooks

You can create and manage webhooks through the Team Settings page or via the API endpoints below.

  1. Create a webhook endpoint that accepts POST requests
  2. Register the webhook URL in your VerifyRef dashboard
  3. Select which events you want to receive
  4. Save the webhook secret for signature verification

Available Events

check.completed

Triggered when all references have submitted their responses and the check is complete.

check.consent_given

Triggered when a candidate gives consent for their reference check.

reference.responded

Triggered when a reference submits their response (fires for each reference).

email.bounced

Triggered when a reference request email bounces (invalid email address).

Webhook Payload

All webhook events follow this structure. The id field is a unique UUID for each event delivery, which can be used for deduplication.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "check.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "checkId": "clx...",
    "candidateName": "John Doe",
    "candidateEmail": "john@example.com",
    "jobId": "clx...",
    "status": "COMPLETED",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Verifying Webhook Signatures

Each webhook request includes an X-VerifyRef-Signature header containing an HMAC-SHA256 signature of the payload. You should verify this signature to ensure the request came from VerifyRef.

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
const signature = req.headers['x-verifyref-signature'];
const isValid = verifyWebhook(req.body, signature, YOUR_WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Managing Webhooks via API

GET/api/v1/webhooks

List all webhooks for your team.

POST/api/v1/webhooks

Create a new webhook endpoint.

{
  "url": "https://api.example.com/webhooks",
  "events": [
    "check.completed",
    "reference.responded"
  ]
}
PATCH/api/v1/webhooks/:id

Update webhook (toggle active status or modify events).

DELETE/api/v1/webhooks/:id

Delete a webhook endpoint.

Important: Webhook URLs must use HTTPS. Your endpoint should respond with a 2xx status code within 10 seconds to be considered successful. Failed deliveries will be retried up to 3 times with exponential backoff.

Rate Limits & Errors

To ensure fair usage, the API is rate limited to 100 requests per minute per API key.

401Unauthorized. Invalid or missing API key.
402Payment Required. Insufficient team credits. Log back into your dashboard to purchase more credits.
429Too Many Requests. You have exceeded the rate limit.
500Internal Server Error. Something went wrong on our end.