Affordable Volunteer Background Checks

Authentication

Include your API key in the Authorization header. Keys start with vb_live_ and are shown only once at creation.

Authorization: Bearer vb_live_XXXXXXXXXXXXXXXX
Content-Type: application/json

Identity verification required. Before any API or webhook access, an owner or admin on the account must complete a free, one-time identity verification in Settings → Account. Until then, every request (and webhook subscription) returns 403 with code: identity_verification_required.

POST /checks

Order a direct background check (no volunteer record created). Deducts 1 credit. Response includes checkId and volunteerId: null. As with every endpoint, the account must have completed identity verification first (see Authentication above).

curl -X POST https://www.volunteerbadge.com/api/v1/checks \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Smith",
    "dob": "03/15/1985",
    "ssn": "123456789",
    "address": "123 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip": "60601"
  }'

POST /checks/instant

Certified no-SSN instant check on name + DOB + state, for when you already hold the subject's signed FCRA authorization. Your organization must enable Allow screening without a U.S. SSN in Settings → Screening. Requires authorizationOnFile: true and a permissiblePurpose (volunteer_screening, employment_screening, or youth_serving_organization). Middle name required; SSNs are rejected. Same owner identity-verification gate as POST /checks.

curl -X POST https://www.volunteerbadge.com/api/v1/checks/instant \
  -H "Authorization: Bearer vb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Smith",
    "dob": "03/15/1985",
    "state": "IL",
    "permissiblePurpose": "volunteer_screening",
    "authorizationOnFile": true
  }'

GET /checks/:id

Poll for check status and result. Direct checks return volunteerId: null; volunteer-linked checks include the volunteer UUID.

GET /adverse-actions

List adverse-action cases for the authenticated organization. Query params: page, limit (max 100), status, checkId, volunteerId, updatedSince (ISO-8601). Use this to recover a missed adverse_action.* webhook. Returns status, notice delivery, and dispute outcome — not letter text or consumer statements. Sandbox keys return an empty list.

GET /adverse-actions/:caseId

One case, including subjectName. A case that belongs to another organization returns 404. Sandbox keys return 404.

POST /applications

Send a volunteer application invite.

{
  "templateId": "uuid",
  "email": "volunteer@example.com",
  "deliveryMethod": "email"
}

GET /volunteers

Paginated volunteer list. Query params: page, limit, status. Each row includes rescreenDueAt.

GET /volunteers/:id

One volunteer, including rescreenDueAt and their checks.

PATCH /volunteers/:id

Archive or restore. Body: { "status": "archived" } or { "status": "approved" }. Archived volunteers are excluded from auto re-screen. Records are retained — there is no hard delete. Returns 409 when archive is blocked (pending decision or incomplete adverse action).

POST /volunteers/:id/rescreen

Send the short FCRA re-screen consent link (not a full application). Optional deliveryMethod: email (default), sms (requires smsConsentAttested: true), or link. Does not reuse prior authorization. Sandbox keys return a simulated invite and do not send email.

POST /chat

Natural-language endpoint for API customers. Send plain English requests to run checks or query credits.

Webhooks

Events: check.complete, check.error, application.submitted, volunteer.created, adverse_action.case_opened, adverse_action.notice_sent, adverse_action.dispute_opened, adverse_action.dispute_resolved, adverse_action.completed. Payloads are signed with HMAC-SHA256 in the X-VolunteerBadge-Signature header. See support: API & webhooks for payload fields.

API Reference