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