reqCHECK

Widget Integration

Detailed guide to integrating and customizing the reqCHECK widget with accurate, resilient behavior across all modes.

About Job IDs

Throughout this documentation, references to jobId or data-reqcheck-job refer to the external job ID you registered when creating the job in your reqCHECK dashboard. This is the identifier that links your external job posting system (e.g., Greenhouse, Workday) with reqCHECK, and is not the same as the internal database ID.

Widget Lifecycle & Guardrails
Safety checks before anything renders
  • On load we validate the provided company + job id, ensure the job has at least one skill with weight > 0, and that at least one of those skills has a challenge question with weight > 0.
  • If any check fails, the widget silently bails and hides itself so the user can proceed normally (no blocking, no errors).
  • All network or rendering errors are handled the same way: fail closed, allow the candidate to continue without interruptions.

Result: the widget only appears when there is a valid, scorable quiz. Otherwise it behaves like it was never on the page.

Basic Integration
The simplest way to get started

Load the widget script once in your <head>, then add mode attributes to your elements. The widget auto-scans and initializes only when guardrails pass.

<!-- In <head> - set once -->
<script src="https://cdn.reqcheck.io/widget.js" 
        data-reqcheck-company="your-company-id"></script>

<!-- On any page, any element -->
<!-- data-reqcheck-job uses your external job ID (from dashboard) -->
<form data-reqcheck-mode="protect" data-reqcheck-job="job_123">
  <!-- Your form fields -->
  <input type="email" name="email" data-reqcheck-email-field="true" required />
</form>

<!-- Or for external links -->
<a href="https://jobs.greenhouse.io/apply/123" 
   data-reqcheck-mode="gate" 
   data-reqcheck-job="job_456">
  Apply Now
</a>
Widget Modes
Three modes for different use cases

Form Protection Mode

Use for traditional application forms. Semi-transparent overlay covers the form with a CTA to unlock. If an email is already stored locally, we check for an attempt within the last 24 hours and show current progress on the overlay.

<!-- data-reqcheck-job uses your external job ID (from dashboard) -->
<form data-reqcheck-mode="protect" data-reqcheck-job="job_123">
  <!-- Email field enables smart resume/24h checks -->
  <input type="email" name="email" data-reqcheck-email-field="true" required />
  <input type="text" name="name" required />
  <button type="submit">Submit Application</button>
</form>

Behavior: CTA opens a full-page modal. First step collects email (skipped when already stored). We check for an attempt within the last 24 hours; if none, we generate a new quiz, otherwise we resume progress. On pass, overlay disappears and the form is usable; we store a temporary validation key for backend retrieval. On fail, we record the failed attempt and show that a retry is available in 24 hours while the form remains blocked.

Initialization Options
Auto-init, manual control, or programmatic trigger

By default, the widget automatically finds and initializes all [data-reqcheck-mode] elements. No additional code needed.

<script src="https://cdn.reqcheck.io/widget.js" 
        data-reqcheck-company="your-company-id"></script>
<!-- Automatically finds and initializes all [data-reqcheck-mode] elements -->
Email Capture
Required before quiz, with optional smart detection

All modes require email capture before showing the quiz. You can enable smart email detection to compare the blurred email against any local session and check backend status automatically.

<input
  type="email" 
  name="email"
  required 
  data-reqcheck-email-field="true" <!-- Smart detection: blur to compare with stored email, show check/CTA/warning -->
/>
<!-- Widget monitors this field and checks verification status on blur. -->

Smart Email Detection Behavior:

  • User types email → tabs away
  • Widget checks if it matches a stored email; if different, it checks that email against backend sessions
  • If already passed: Shows reqCHECK checkmark ✓ next to the field
  • If no attempt: Exposes CTA to launch quiz inline/full-page
  • If failed within 24h: Shows "Try again in X hours" warning

Fallback: Without data-reqcheck-email-field, user must click the blocked element to trigger the quiz.

Widget Styling
Customize widget appearance from your dashboard

Widget styles are configured server-side in your reqCHECK dashboard under Settings → Styles. The widget automatically fetches and applies these styles when it initializes.

Available Style Properties:
- Font Color: Color for all text in the widget
- Background Color: Background color for modals and overlays
- Button Color: Background color for all buttons
- Button Text Color: Text color for buttons
- Accent Color: Color for selected answers, progress bars, and success states

How It Works:

  • Configure styles in Settings → Styles in your dashboard
  • Styles are automatically applied to all widget instances for your team
  • No client-side configuration needed - styles are fetched from the backend
  • Widget is fully responsive and adapts to mobile viewports automatically
Pass Threshold
Configured in dashboard only

Pass threshold is configured in your dashboard (per job or company-wide default, 60% default). There is no client-side override to prevent gaming. The widget respects backend settings automatically.

Callbacks & Events
Listen for verification events

Listen for verification events to track in analytics or trigger custom behavior:

ReqCheck.on('verified', (result) => {
  // { passed: true, score: 85, email: "...", jobId: "..." }
  console.log('Candidate passed!', result);
  
  // Track in analytics
  gtag('event', 'reqcheck_passed', { score: result.score });
});

ReqCheck.on('failed', (result) => {
  // { passed: false, score: 45, requiredScore: 60 }
  console.log('Candidate failed', result);
});

ReqCheck.on('abandoned', () => {
  // User closed quiz without completing
  console.log('Quiz abandoned');
});
Test Mode
Test integration without enforcing verification

Enable test mode to render and test the widget without backend enforcement:

<script src="https://cdn.reqcheck.io/widget.js" 
  data-reqcheck-company="your-company-id"
  data-reqcheck-test-mode="true"
</script>

Test Mode Behavior:

  • Widget renders and functions normally
  • Quiz appears and can be completed
  • But: Backend doesn't enforce verification
  • Applications proceed even without passing
  • Shows "TEST MODE" badge in widget

Use for: Staging environments, testing integration, previewing widget before going live.

Content Security Policy (CSP)
Required CSP directives for reqCHECK
<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://cdn.reqcheck.io;
  connect-src 'self' https://api.reqcheck.io;
  style-src 'self' https://cdn.reqcheck.io 'unsafe-inline';
  img-src 'self' https://cdn.reqcheck.io data:;
  font-src 'self' https://cdn.reqcheck.io;
">

Why each directive is needed:

  • script-src - Allows widget JavaScript to load
  • connect-src - Allows API calls to reqCHECK backend
  • style-src 'unsafe-inline' - Allows widget styling (we'll work on removing this requirement)
  • img-src / font-src - For widget assets

Testing CSP: Open browser console and look for CSP violation errors. If widget doesn't appear, likely CSP is blocking it.

Backend Verification
Check verification status in your backend

When a candidate passes verification, reqCHECK stores the result server-side with a 1-hour expiry. When they submit their application, your backend should call the Verification API to check if they passed.

POST /api/v1/verify
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "externalJobId": "job_123", // External job ID (from dashboard, not database ID)
  "email": "candidate@example.com"
}

Returns verification status including whether they passed, their score, and when they completed. Returns 404 if no valid verification found (within 1 hour).

Important: API keys are only used in your backend for verification lookup. Never expose them in frontend code or include them in the widget script. Verifications are stored server-side - no tokens are injected into forms.

Multi-Language Support
Current status and roadmap

Status: Coming Q2 2026

Planned languages: English, Spanish, French, German, Portuguese

For now, all content is English only.

Need Help?

Check the API reference for more advanced integration options.

API Reference