API & webhooks (developers)

VolunteerBadge has a simple REST API for managing volunteers, sending applications, ordering background checks, and receiving real-time events. If you'd rather not write code, see Import volunteers for the spreadsheet importer, or Connect to Claude to drive everything in plain English.

Authentication

Create an API key in Settings → API(you'll accept the CRA End-User Agreement the first time). Keys look like vb_live_… — treat them like a password and never expose one in client-side code. Send it as a bearer token on every request:

Authorization: Bearer vb_live_xxxxxxxxxxxxxxxxxxxx

Sandbox / test mode

Build and test your whole integration — including webhooks — before going live, using a sandbox key. In Settings → API, click “Create sandbox test key”. Sandbox keys start with vb_test_ (live keys start with vb_live_) and can be created with no agreement and no identity verification.

A test key hits the same endpoints with the same request shape. In sandbox:

• No credit is charged and no real check runs — nothing reaches the screening vendor.
• You get an instant simulated response, and your registered webhooks fire for real (check.complete / check.error), so you can validate your handler end-to-end.
• Nothing is persisted — POST /api/v1/volunteers, PATCH /api/v1/volunteers/{id}, POST /api/v1/volunteers/{id}/rescreen, and POST /api/v1/applications return simulated IDs without writing a roster row or sending an invite.

The outcome is deterministic from the subject you send (like a test card number):

Sandbox check IDs are prefixed chk_test_, and every sandbox response includes "mode": "test". When you're ready for production, generate a vb_live_ key (that one requires the CRA agreement + identity verification, since it furnishes real consumer reports) and run the exact same code.

Endpoints

Create a volunteer

Push a person into VolunteerBadge — e.g. migrating a roster or syncing from another system. Posting the same email twice returns the existing record instead of duplicating it.

curl -X POST https://www.volunteerbadge.com/api/v1/volunteers \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jamie",
    "last_name": "Rivera",
    "email": "jamie@example.com",
    "phone": "443-790-8081",
    "dob": "1981-05-29",
    "state": "FL",
    "last_check_date": "2025-06-01",
    "fcra_authorization_on_file": true,
    "status": "approved"
  }'

# → { "volunteerId": "f883...", "created": true }

List volunteers

curl "https://www.volunteerbadge.com/api/v1/volunteers?status=approved&page=1&limit=25" \
  -H "Authorization: Bearer vb_live_..."

# → { "volunteers": [ { "id": "...", "first_name": "...", "status": "approved",
#                       "rescreenDueAt": "2026-06-01T00:00:00.000Z", ... } ],
#     "pagination": { "page": 1, "limit": 25, "total": 42, "totalPages": 2 } }

Get one volunteer

curl https://www.volunteerbadge.com/api/v1/volunteers/f883... \
  -H "Authorization: Bearer vb_live_..."

# → { "id": "...", "firstName": "Jamie", "status": "approved",
#     "rescreenDueAt": "2026-06-01T00:00:00.000Z", "checks": [ ... ] }

Archive or restore a volunteer

Archiving removes someone from auto re-screen without deleting records (FCRA retention). Restore with { "status": "approved" } — that restore still requires a completed background check on file, same as the dashboard.

curl -X PATCH https://www.volunteerbadge.com/api/v1/volunteers/f883... \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "archived" }'

# → { "id": "f883...", "status": "archived" }

Archive is blocked (HTTP 409) while a decision is pending or FCRA adverse action is incomplete.

Send a re-screen consent link

This emails (default), texts, or returns a link for the short FCRA authorization form — not a full application. The volunteer confirms their address, signs, and the $5 check runs. Prior authorization is not reused. Archived volunteers must be restored first. SMS requires smsConsentAttested: true.

curl -X POST https://www.volunteerbadge.com/api/v1/volunteers/f883.../rescreen \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "deliveryMethod": "email" }'

# → { "inviteId": "...", "consentUrl": "https://www.volunteerbadge.com/rescreen/...",
#     "deliveryMethod": "email", "expiresAt": "..." }

List application templates

Every application you send is built from one of your templates, and POST /api/v1/applicationsneeds that template's id. This is how you look them up:

curl https://www.volunteerbadge.com/api/v1/templates \
  -H "Authorization: Bearer vb_live_..."

# → { "templates": [
#      { "id": "3f9a1c22-7b64-4e08-9d15-8a2c7e4b1f60",
#        "name": "Youth & Children", "sector": "youth",
#        "isDefault": true, "fieldCount": 14, "sendCount": 37,
#        "createdAt": "...", "updatedAt": "..." } ] }

Your defaulttemplate is returned first, so an integration that just wants “the normal one” can take templates[0].idwithout sorting. Only your own organization's templates are ever returned. The question definitions themselves aren't included — fieldCount is there to tell similar templates apart.

Send a volunteer application (consent-first invite)

Emails or texts the applicant your application, so they complete the FCRA disclosure and sign the authorization themselves. This is the path to use when you don't already hold a signed authorization — and the one that supports applicants with no middle name, since they attest to that on the signed form.

curl -X POST https://www.volunteerbadge.com/api/v1/applications \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "3f9a1c22-7b64-4e08-9d15-8a2c7e4b1f60",
    "email": "jamie@example.com"
  }'

# → { "applicationId": "...", "applyUrl": "https://www.volunteerbadge.com/apply/<token>",
#     "deliveryMethod": "email", "expiresAt": "2026-09-01T00:00:00.000Z" }

templateId is the only required field. Get it from GET /api/v1/templates above — or, if you just want to paste one in by hand, open Recruit → Applications, click the template to edit it, and take the UUID from the end of the browser URL (/dashboard/applications/builder/<templateId>). A template that doesn't belong to your organization returns 404.

Waiving identity verification for one invite

Settings → Screening → “Require identity verification” is an organization-wide default, but a single invite can override it — the same way the per-invite payer choice overrides your org's payer default. Use it when you confirm someone's ID another way, e.g. an elderly volunteer whose ID you check in person at intake and who would struggle with the selfie step.

curl -X POST https://www.volunteerbadge.com/api/v1/applications \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "3f9a1c22-7b64-4e08-9d15-8a2c7e4b1f60",
    "email": "jamie@example.com",
    "requireIdVerification": false,
    "idVerificationReason": "ID checked in person at intake on 2026-08-18"
  }'

Omit requireIdVerification and the invite inherits your org setting. Set it to true to require verification for one person even when your org default is off. Setting it to false requires idVerificationReason (10 characters or more): waiving the step that ties a real person to the record being screened is worth a note, and we store it on the invite so anyone reviewing that volunteer later can see how their identity was confirmed.

You do not need a second organization or a second API key for this.

The returned applyUrlis the same link the applicant receives, so you can show it in your own UI or fall back to it if someone doesn't get the email.

Order a background check

Requires firstName, middleName, lastName, dob, ssn, address, city, state, zip. middleName is required by default— it confirms identity and reduces false matches on common names. This endpoint runs the same SSN trace/address-history lookup as an invited applicant's check. This consumes 1 credit.

curl -X POST https://www.volunteerbadge.com/api/v1/checks \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jamie", "middleName": "Alex", "lastName": "Rivera",
    "dob": "1981-05-29", "ssn": "123456789",
    "address": "12112 Blue Hill Trail", "city": "Lakewood Ranch",
    "state": "FL", "zip": "34211"
  }'

# → { "checkId": "...", "status": "processing", "result": null, "message": "..." }

# Optional — omit both fields to inherit org settings
    "includeMisdemeanors": false,
    "includeTrafficViolations": true

Subscribe to check.complete (search finished) and check.adjudicated (human review finished, for checks with potential records) and you never need to poll. GET /api/v1/checks/{id} is there whenever you want to read the current state directly.

Check a check's status

Use the checkId returned by POST /api/v1/checks or POST /api/v1/checks/instant exactly as given — no prefix, no encoding:

curl https://www.volunteerbadge.com/api/v1/checks/8f2b1c34-5d6e-4a70-9b81-2c3d4e5f6a7b \
  -H "Authorization: Bearer vb_live_..."

# → { "checkId": "...", "volunteerId": null, "status": "complete", "result": "clear",
#     "type": "direct", "creditsCharged": 1,
#     "offenderCount": 0, "errorMessage": null,
#     "completedAt": "...", "createdAt": "...",
#     "reportUrl": "...", "reportDownloadUrl": "..." }

type is direct for checks you order through /checks or /checks/instant, and fullfor a check produced by a volunteer's signed application. The response includes a legacy ssnTraceIncluded field that defaults to true in the database — do not branch on it. It does not reliably indicate whether an SSN trace actually ran: certified no-SSN checks (/checks/instant) have no trace even though the field may read true. SSN-bearing checks run a trace; check the report or dashboard SSN Trace card for the actual address-history result.

A check is only ever visible to the organization that ordered it — another org's checkId returns 404, not the record.

reportDownloadUrl is a short-lived signed link, generated per request once the check is no longer processing — fetch it when you need it rather than storing it.

Polling a sandbox check

Sandbox checks are simulated and never stored, so a chk_test_... id has no database row behind it. GET /api/v1/checks/{id} still answers for one — the outcome is encoded in the id, so it returns the same deterministic result the POST gave you, with "sandbox": true and creditsCharged: 0. That means you can build and test your polling loop end to end on a test key. A records-result sandbox check reports pending_adjudication with a null result and stays there, exactly as production does until a human finishes the review.

Certified instant check (no SSN)

Run an immediate check on firstName, middleName, lastName, dob, state with no SSN— for when you already hold the subject's signed FCRA disclosure and written authorization. Certify it per request with authorizationOnFile: true and a permissiblePurpose (one of volunteer_screening, employment_screening, youth_serving_organization). middleName is required unless you pass "requireMiddleName": false. SSNs are rejected on this endpoint.

curl -X POST https://www.volunteerbadge.com/api/v1/checks/instant \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jamie", "middleName": "Lee", "lastName": "Rivera",
    "dob": "1981-05-29", "state": "FL",
    "permissiblePurpose": "volunteer_screening",
    "authorizationOnFile": true
  }'

# → { "checkId": "...", "status": "...", "result": "...", "certified": { ... } }

Same screening-scope rule as POST /api/v1/checks: omit includeMisdemeanors / includeTrafficViolations to inherit Settings → Screening; send either flag to override that check only.

Errors

Webhooks

Instead of polling, register a URL in Settings → Webhooks and VolunteerBadge will POST to it when things happen. Available events:

Adverse-action webhooks include caseId, checkId, and volunteerId (null for direct checks). Notice and dispute events also include identifiers like noticeId, stage, or disputeId when available.

Each delivery is a JSON POST with two headers — X-VolunteerBadge-Event (the event name) and X-VolunteerBadge-Signature(an HMAC-SHA256 of the raw body, signed with your endpoint's secret):

POST  (your endpoint)
X-VolunteerBadge-Event: adverse_action.notice_sent
X-VolunteerBadge-Signature: 9f86d081...

{
  "event": "adverse_action.notice_sent",
  "data": {
    "caseId": "...",
    "checkId": "...",
    "volunteerId": "...",
    "stage": "pre",
    "noticeId": "...",
    "deliveryStatus": "delivered"
  },
  "timestamp": "2026-07-18T18:00:00.000Z"
}

Always verify the signature before trusting a payload. In Node:

import crypto from 'crypto';

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}