Background Checks App Overview
Order background checks from leading providers, track results in real time, adjudicate findings with a structured workflow, and stay FCRA-compliant — all without leaving MangoApps Workforce.
What is Background Checks?
Background Checks is the integrated pre-employment screening module inside MangoApps Workforce. It connects your recruiting pipeline to external background check providers — Checkr, Sterling, and HireRight — so HR teams can request checks, receive results via webhook, and make adjudication decisions from a single dashboard. The module is built into the Job Board app and operates as a sub-feature of the recruiting suite.
Every check flows through a structured lifecycle: request, candidate authorization, provider processing, result delivery, and adjudication. FCRA compliance is baked in — disclosure notices, authorization tracking, adverse-action waiting periods, and audit logging happen automatically based on your configuration.
Core Value Proposition:
- 🔗 Multi-Provider Integration — Connect to Checkr, Sterling, or HireRight with API-key configuration and sandbox/production modes
- 📋 FCRA Compliance Built-In — Automatic disclosure delivery, authorization tracking, configurable waiting periods, and adverse action workflows
- ⚖️ Structured Adjudication — Review adverse items, make approve/reject/conditional decisions, and record audit-logged notes
- 📡 Real-Time Webhook Updates — Provider status changes flow into the platform instantly via secure, signature-verified webhooks
At a Glance
| 🔗 Provider Integrations | 📋 FCRA Compliance | ⚖️ Adjudication Workflow | 📡 Webhook Updates |
|---|---|---|---|
| Checkr, Sterling, HireRight | Disclosure, authorization, waiting periods | Approve, reject, conditional, needs review | Signature-verified, real-time status sync |
| 📦 Screening Packages | 📊 Dashboard & Stats | 📧 Email Notifications | 📱 Mobile Access |
|---|---|---|---|
| Basic, Pro, Comprehensive, Executive | Total, pending, clear, needs-review counts | Candidate and recruiter alerts at every stage | Manager view of checks and pending items |
Perfect For:
- 🏢 HR / Admins — Configure providers, choose default packages, set FCRA waiting periods, enable auto-adjudication
- 👥 Recruiters — Request checks for candidates, monitor progress, adjudicate results
- 👤 Hiring Managers — Review adjudication decisions, view candidate background status
How It Works
Background Check Lifecycle
┌──────────────────────────────────────────────────────────────────────────┐
│ BACKGROUND CHECK LIFECYCLE │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ REQUEST │───▶│ INVITE │───▶│ PROCESSING│───▶│ RESULTS │ │
│ │ Check │ │ Candidate │ │ by Provider│ │ Received │ │
│ └──────────┘ └───────────┘ └───────────┘ └──────────────┘ │
│ │ │ │ │ │
│ Recruiter picks FCRA disclosure Provider runs Webhook │
│ candidate and and authorization criminal, employ- delivers │
│ selects package sent via email ment, education clear/consider │
│ checks /suspended │
│ │
│ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ADJUDICATE│───▶│ DECIDE │───▶│ NOTIFY │───▶│ COMPLETE │ │
│ │ Review │ │ Outcome │ │ Parties │ │ & Audit │ │
│ └──────────┘ └───────────┘ └───────────┘ └──────────────┘ │
│ │ │ │ │ │
│ Manager reviews Approve, reject, Email recruiter, Decision and │
│ adverse items conditional, or hiring manager, all status │
│ and notes needs-review and candidate changes logged │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Status Flow
┌────────────────────────────────────────────────────────────────────┐
│ STATUS TRANSITIONS │
├────────────────────────────────────────────────────────────────────┤
│ │
│ pending ───▶ invited ───▶ pending_completion ───┬──▶ clear │
│ │ │
│ ├──▶ consider ──┐ │
│ │ │ │
│ └──▶ suspended ─┤ │
│ │ │
│ ┌────────────────────────────────────────┘ │
│ ▼ │
│ ADJUDICATION │
│ ┌─────────────────────┐ │
│ │ pending │ │
│ │ ├── approved │ (auto or manual) │
│ │ ├── needs_review │ │
│ │ ├── conditional │ │
│ │ └── rejected │ (triggers adverse action) │
│ └─────────────────────┘ │
│ │
│ Any status ───▶ canceled (manual cancellation by manager) │
│ Any status ───▶ error (provider or system failure) │
│ │
└────────────────────────────────────────────────────────────────────┘
Key Features
🔗 Multi-Provider Integration
Connect to one or more background check providers through the SystemIntegration framework. Each provider connector supports sandbox and production environments, connection testing, and custom package mappings.
| Provider | Status | Capabilities |
|---|---|---|
| Checkr | Fully implemented | Create candidates, send invitations, create reports, get status, cancel reports, list packages, webhook processing |
| Sterling | Implemented | Initiate checks, get report status, cancel reports, get candidate reports |
| HireRight | Implemented | Initiate screenings, get screening status, cancel screenings, get applicant history |
Each connector handles:
- API Authentication — Base64-encoded API key (Checkr, Sterling) or Bearer token (HireRight)
- Environment Switching — Toggle between sandbox (testing) and production with a single setting
- Connection Testing — Verify credentials and connectivity before going live
- Error Handling — Timeouts, JSON parse errors, and HTTP failures are caught and returned as structured results
Use Case — Setting Up Checkr:
An admin navigates to the system integrations page, creates a new Background Check integration for Checkr, enters the API key from their Checkr dashboard, selects the sandbox environment for initial testing, and runs a connection test. Once verified, they switch to production and set this integration as the preferred provider in Job Board configuration.
📦 Screening Packages
Choose from four standard screening packages or configure custom packages through the provider integration settings.
| Package | Slug | What’s Included |
|---|---|---|
| Basic Criminal Check | basic_criminal |
SSN verification, National Criminal Database search, Sex Offender Registry check |
| Pro Criminal Check | pro_criminal |
Everything in Basic plus County Criminal searches, Federal Criminal search |
| Comprehensive | comprehensive |
Everything in Pro plus Employment Verification, Education Verification, Professional Reference checks |
| Executive | executive |
Full comprehensive check plus Credit Report, Civil Court searches, Media searches, Extended employment history |
The configuration service supports custom package definitions stored in the provider integration’s JSON configuration. When custom packages are defined, they override the defaults — allowing organizations to match their provider’s specific package catalog.
Pro Tip: Set a default package in the app configuration so recruiters don’t have to pick one every time. The default is applied automatically when requesting checks through the API or auto-request workflows.
📋 FCRA Compliance
The Fair Credit Reporting Act (FCRA) governs how employers use consumer reports in hiring decisions. Background Checks automates the key compliance steps.
| Compliance Step | How It Works |
|---|---|
| Pre-Adverse Action Disclosure | Tracked via fcra_disclosure_sent_at — the system records when the disclosure was sent to the candidate |
| Candidate Authorization | Tracked via fcra_authorization_received_at — checks are not processed until authorization is confirmed |
| Waiting Period | Configurable 5–10 day waiting period (minimum 5 per FCRA) before adverse action can be taken |
| Adverse Action Process | Triggered automatically when a check is rejected — pre-adverse notice, waiting period, then final notice |
| Compliance Verification | The fcra_compliant? method validates both disclosure sent and authorization received before proceeding |
Configuration options:
auto_send_fcra_disclosure— Automatically send the pre-adverse action notice when required (default: on)fcra_waiting_period_days— Number of days to wait before adverse action (default: 5, range: 5–10)
⚖️ Adjudication Workflow
When a background check returns “consider” or “suspended” results, managers must review and make an adjudication decision.
┌────────────────────────────────────────────────────────────────────┐
│ ADJUDICATION WORKFLOW │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Results arrive with consider/suspended status │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ ADVERSE ITEMS │ List of flagged records with type, │
│ │ REVIEW │ description, disposition, date │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ APPROVED │ │ CONDITIONAL │ │ REJECTED │ │
│ │ Clear for │ │ Hire with │ │ Do not │ │
│ │ hire │ │ conditions │ │ hire │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Candidate status Candidate status FCRA adverse │
│ set to "clear" set to action process │
│ "conditional" triggered │
│ │
│ ─── All decisions recorded with notes, user, and timestamp ─── │
│ │
└────────────────────────────────────────────────────────────────────┘
| Decision | Candidate Status | Next Steps |
|---|---|---|
| Approved | clear |
Candidate proceeds in hiring pipeline |
| Needs Review | Unchanged | Escalated for additional investigation |
| Conditional | conditional |
Hire with documented conditions or restrictions |
| Rejected | rejected |
FCRA adverse action process is triggered |
Auto-Adjudication: When auto_adjudicate_clear is enabled, checks that return with a “clear” status are automatically adjudicated as “approved” without manual intervention. This is configurable per integration.
Authorization: Only managers and above (manager_or_above?) can adjudicate or cancel background checks. Recruiters can view checks for their own candidates but cannot make adjudication decisions.
📊 Dashboard & Statistics
The background checks dashboard provides a centralized view of all screening activity with real-time statistics, filtering, and pagination.
Statistics Cards:
| Metric | Description |
|---|---|
| Total Checks | All background checks across all statuses |
| Pending | Checks in pending, invited, or pending_completion status |
| Needs Review | Completed checks awaiting adjudication (consider/suspended with pending adjudication) |
| Clear | Checks that returned with a clear result |
Filtering & Search:
- Filter by status: Pending, Invited, In Progress, Clear, Consider, Suspended, Canceled
- Filter by adjudication: Pending, Approved, Needs Review, Rejected, Conditional
- Search by candidate name or email (via the shared queries concern)
- Pagination at 25 results per page on desktop, 20 on mobile
Table Columns: Candidate (name, email, job), Package, Status (badge), Adjudication (badge), Requested date, Actions (view, adjudicate)
📡 Webhook Processing
Provider status updates arrive via secure webhook endpoints. Each provider has a dedicated endpoint with signature verification.
| Webhook Event | Status Update | Auto-Action |
|---|---|---|
report.created |
pending_completion |
Log event |
report.completed |
Mapped from provider result | Notify recruiter, trigger auto-adjudication if clear |
report.clear |
clear |
Auto-adjudicate if enabled, notify recruiter |
report.consider |
consider |
Notify adjudication required |
report.suspended |
suspended |
Notify adjudication required |
Security measures:
- HMAC Signature Verification — Checkr webhooks are verified using SHA-256 HMAC with the integration’s webhook secret
- Business-Scoped URLs — Optional
/background_check_webhooks/:business_id/checkrendpoint for multi-tenant isolation - Active Integration Check — Webhooks are rejected if the associated integration is inactive
- Idempotency — Duplicate webhooks for already-completed checks are detected and skipped
Adverse Item Extraction: When a report contains records with a “consider” result, the webhook handler automatically extracts adverse items (type, description, disposition, date) and stores them on the background check record.
📧 Email Notifications
The BackgroundCheckMailer sends targeted notifications at each stage of the background check process.
Candidate Notifications:
| When It’s Sent | Key Content | |
|---|---|---|
| Authorization Requested | Check is initiated | FCRA disclosure, authorization link to candidate portal, package details |
| Check In Progress | Provider begins processing | Status update with estimated completion date |
| Check Completed (Clear) | Clear result received | Confirmation that the check is complete |
Recruiter / Hiring Manager Notifications:
| When It’s Sent | Key Content | |
|---|---|---|
| Request Submitted | Check is created | Candidate name, package, provider, link to candidate profile |
| Request Failed | Provider error | Error message, link to retry |
| Report Completed | Check finishes | Result status (clear/consider/suspended), link to view results |
| Adjudication Required | Adverse items found | Adverse item count, status, link to adjudicate |
| Adjudication Completed | Decision is made | Decision (approved/rejected/conditional), adjudicator name, notes |
Recipients are resolved intelligently: the person who requested the check, the job’s recruiter, the hiring manager, and the job creator all receive relevant notifications (deduplicated).
📱 Mobile Access
Managers and admins can view background check status and details from the mobile web interface.
| Mobile View | Features |
|---|---|
| Check List | Status filter pills, stats summary, paginated card list with infinite scroll |
| Check Detail | Status overview, candidate info, check details, timeline |
| Pending Review | Filtered view of checks awaiting adjudication |
Mobile access requires manager_or_above? permissions. The mobile controller shares query logic with the desktop controller through the BackgroundCheckQueries concern, ensuring consistent filtering, statistics, and pagination.
🔍 Audit Trail
Every significant action is recorded in the recruiting audit log via RecruitingAuditLog.log.
| Event | Logged Data |
|---|---|
| Check Created | Candidate name, package, provider |
| Status Changed | Old and new status, candidate name, provider |
| Adjudicated | Candidate name, decision, notes |
| Canceled | Candidate name, cancellation reason |
| Webhook Events | Event type, status, provider, candidate name |
Configuration Reference
App Configuration Schema
The marketplace app configuration is organized into five categories:
General Settings:
| Setting | Type | Default | Description |
|---|---|---|---|
enabled |
Boolean | false |
Master switch — allow recruiting apps to request background checks |
auto_request_on_offer |
Boolean | false |
Automatically initiate a background check when a candidate accepts an offer |
default_package |
Select | pro_criminal |
Default screening package for new requests |
Provider Settings:
| Setting | Type | Description |
|---|---|---|
checkr_enabled |
Boolean | Enable the Checkr provider |
checkr_api_key |
String | Your Checkr API key |
checkr_environment |
Select | Sandbox (testing) or Production (live checks) |
FCRA Compliance:
| Setting | Type | Default | Description |
|---|---|---|---|
auto_send_fcra_disclosure |
Boolean | true |
Auto-send pre-adverse action notice when required |
fcra_waiting_period_days |
Slider (5–10) | 5 |
Days to wait before adverse action (minimum 5 per FCRA) |
Adjudication:
| Setting | Type | Default | Description |
|---|---|---|---|
auto_adjudicate_clear |
Boolean | true |
Automatically approve candidates with clear results |
require_manual_review_consider |
Boolean | true |
Require manual adjudication for consider results |
Notifications:
| Setting | Type | Default | Description |
|---|---|---|---|
notify_recruiter_on_complete |
Boolean | true |
Email recruiter when a background check completes |
notify_on_adverse_items |
Boolean | true |
Immediate notification when adverse items are found |
Permissions & Access Control
| Role | Capabilities |
|---|---|
| Admin / Super Admin | Full access — configure providers, request checks, adjudicate, cancel, view all checks |
| Manager | Request checks, adjudicate results, cancel checks, view all checks |
| Recruiter | Request checks for their candidates, view checks for their candidates/jobs |
| Employee | No access to background checks dashboard |
Background check access is additionally gated by the check_background_checks_enabled filter — if no active background check integration exists for the business, all routes redirect to the dashboard with an explanatory message.
Integration Architecture
Background Checks uses the SystemIntegration framework rather than standalone configuration. This means:
- Provider integrations are created as
SystemIntegrationrecords withcategory: 'background_check' - Configuration (API keys, environment, packages, webhook secrets) is stored as JSON in the integration’s
configurationfield - Job Board preference — the preferred integration ID is stored in the Job Board app’s configuration, allowing administrators to switch providers without reconfiguration
- Multiple providers — organizations can configure multiple providers simultaneously and select which one the Job Board uses
The BackgroundCheckConfigurationService acts as the central configuration resolver, reading settings from both the SystemIntegration and the Job Board app configuration.
Getting Started
Step 1: Configure a Provider Integration
Navigate to system integrations and create a new Background Check integration. Enter your provider’s API key and select the environment (start with sandbox for testing).
Step 2: Test the Connection
Use the built-in connection test to verify your API credentials are valid and the provider is reachable.
Step 3: Set Job Board Preferences
In the Job Board app configuration, select your preferred background check integration. Set the default screening package and enable auto-request on offer acceptance if desired.
Step 4: Configure Compliance Settings
Set FCRA waiting period days, enable auto-send disclosures, and configure adjudication rules (auto-adjudicate clear results or require manual review for all).
Step 5: Configure Webhook Endpoint
Register your webhook URL with your provider. The endpoint follows the pattern:
- Checkr:
POST /background_check_webhooks/checkr(or/background_check_webhooks/:business_id/checkrfor multi-tenant isolation) - Sterling:
POST /background_check_webhooks/sterling - HireRight:
POST /background_check_webhooks/hireright
Step 6: Request Your First Check
Navigate to a candidate’s profile in the Job Board, click “Request Background Check,” select a screening package, and submit. The candidate will receive an authorization email, and you’ll be notified when results are available.
Tips & Best Practices
Use auto-adjudication for clear results. Most background checks come back clear. Enabling
auto_adjudicate_cleareliminates manual work for straightforward cases while still requiring human review for anything flagged.
Start with sandbox mode. Configure your provider in sandbox/testing mode first. Run test checks to verify webhook delivery, email notifications, and the adjudication workflow before switching to production.
Set up business-scoped webhook URLs. For organizations with multiple tenants, use the
/background_check_webhooks/:business_id/checkrendpoint format for proper tenant isolation rather than the generic endpoint.
Review pending adjudications regularly. Use the “Needs Review” count on the dashboard and the pending adjudication view to ensure flagged checks don’t sit unreviewed. Enable
notify_on_adverse_itemsso reviewers are alerted immediately.
Document adjudication decisions thoroughly. Notes are required when adjudicating — use them to record the reasoning behind approve, reject, or conditional decisions. These notes are preserved in the audit trail for compliance purposes.
Frequently Asked Questions
Q: Which background check providers are supported?
A: Checkr (fully implemented with webhook processing), Sterling, and HireRight. All three support initiating checks, getting status, and canceling reports through their respective APIs.
Q: Can I use multiple providers at the same time?
A: Yes. You can configure integrations for multiple providers. The Job Board app configuration lets you select which provider to use as the preferred/default, but all active integrations remain available.
Q: How does FCRA compliance work?
A: The system tracks FCRA disclosure sent and authorization received timestamps. Checks cannot proceed without authorization. When adverse results require rejection, a configurable waiting period (minimum 5 days) is enforced before adverse action can be taken.
Q: What happens when a check returns “consider”?
A: The check enters the adjudication queue. Recruiters and hiring managers are notified. A manager must review the adverse items and make a decision: approve, reject, conditional approval, or escalate for further review.
Q: Can background checks be auto-requested?
A: Yes. Enable auto_request_on_offer in the app configuration to automatically initiate a background check when a candidate accepts an offer.
Q: Is there mobile access?
A: Yes. Managers and admins can view background check status, details, and pending adjudication items from the mobile web interface. Adjudication actions are available on the desktop interface.
