How Gonos fits into your platform
From worker signup to ongoing monitoring — here's exactly how background checks work with your app, step by step.
Worker signs up on your platform
A new worker, provider, or applicant joins your platform and needs to be vetted before going live.
Your platform
Your app collects basic info: name, email, date of birth.
Gonos handles
Your backend calls POST /candidates to register them with Gonos.
// Your backend
const candidate = await gonos.candidates.create({
first_name: "Jane",
last_name: "Doe",
email: "jane@example.com",
date_of_birth: "1990-05-15",
});Worker signs FCRA consent
Federal law requires written consent before running a background check. Gonos handles this with a hosted consent page — you just send the worker a link.
Your platform
Your app shows a "Complete background check" button that opens the Gonos consent link.
Gonos handles
Gonos hosts the disclosure + e-signature page. Worker reads the disclosure, signs, and is redirected back to your app.
// Create a consent session
const session = await gonos.consent.createSession({
candidate_id: candidate.id,
package: "standard",
redirect_url: "https://yourapp.com/onboarding/next",
});
// Send this URL to the worker
// session.consent_url → "https://gonos.co/consent/abc123"Identity verified with knowledge-based questions
Before the check runs, the worker answers a short quiz generated from their address history. This confirms they are who they say they are — no third-party vendor needed.
Your platform
Your app shows a "Verify your identity" step. Gonos generates the questions automatically from SSN trace data.
Gonos handles
Generates 5 multiple-choice questions from address history (cities, states, ZIP codes, years). Worker must answer 3 correctly. Locked out after 2 failed attempts.
// Create a KBA session
const kba = await fetch("/api/v1/kba/sessions", {
method: "POST",
body: JSON.stringify({
check_id: check.id,
candidate_id: candidate.id,
}),
});
// Worker answers questions on your UI or Gonos consumer portal
// Then submit answers:
await fetch(`/api/v1/kba/sessions/${kba.id}/submit`, {
method: "POST",
body: JSON.stringify({ answers: [2, 0, 3, 1, 2] }),
});
// Returns: { passed: true, score: 4 }Background check runs automatically
Once consent is signed, Gonos automatically searches federal criminal records, sex offender registries, OFAC sanctions, and more. No action needed from you.
Your platform
Your app shows "Background check in progress" status.
Gonos handles
Gonos queries multiple data sources in parallel: federal courts (PACER/CourtListener), OFAC sanctions, sex offender registry, and SSN trace for identity verification.
// Submit the check after consent
const check = await gonos.checks.create({
candidate_id: candidate.id,
package: "standard",
permissible_purpose: "employment",
});
await gonos.checks.submit(check.id);
// That's it — Gonos handles the restYou get a webhook when results are ready
Gonos sends a real-time webhook to your server when the check completes. You decide what to do based on the result.
Your platform
Your backend receives the webhook and updates the worker's status in your database.
Gonos handles
Webhook payload includes: check_id, disposition (clear/review/adverse), turnaround time, and report_id.
// Your webhook handler
app.post("/webhooks/gonos", (req, res) => {
const { event_type, payload } = req.body;
if (event_type === "check.completed") {
if (payload.disposition === "clear") {
activateWorker(payload.candidate_id);
} else {
flagForReview(payload.candidate_id);
}
}
res.sendStatus(200);
});Adverse action handled automatically
If the check finds something, FCRA requires a specific process: pre-notice → 5 business day wait → final decision. Gonos automates the entire flow.
Your platform
You call one endpoint. Gonos sends the legally-required notices, waits the required period, and notifies you when you can take action.
Gonos handles
Pre-adverse notice sent with consumer rights summary and CRA contact info. After 5 business days, final adverse action notice sent. Consumer gets a free copy of their report.
// Only needed if check result is adverse
await gonos.adverseActions.create({
check_id: check.id,
adverse_reasons: [
"Criminal record found: felony conviction"
],
});
// Gonos handles the rest: notices, waiting period,
// consumer rights, free report copyContinuous monitoring keeps you safe
Background checks are a point-in-time snapshot. With continuous monitoring, Gonos re-screens active workers and alerts you if anything new appears.
Your platform
Enable monitoring on any completed check. Get webhooks when new records are found.
Gonos handles
Automatic re-screening on monthly, quarterly, or annual cadence. Compares new results against the original report.
// Enable monitoring after initial check clears
await fetch(`/api/v1/checks/${check.id}/monitoring`, {
method: "PUT",
body: JSON.stringify({
enabled: true,
frequency: "monthly",
}),
});
// You'll get a monitoring.change_detected webhook
// if anything new appearsTypical timeline
1 min
API integration
3 API calls total
2 min
Worker consent
Hosted consent page
<4 hrs
Check complete
Webhook notification
24/7
Monitoring
Ongoing re-screening
Ready to add background checks to your platform?
Get started in minutes with our sandbox environment. No credit card required.