Background checks

Accurate Background integration setup, ordering checks, and webhook status updates.

InsightHire integrates with Accurate Background to order background checks from the candidate profile and receive status updates via webhook. Credentials can be per-organization or fall back to platform-level env vars for sandbox testing.

Settings path

Prerequisites

1. Accurate Background account with API Client ID and Client Secret (Accurate API docs).
2. Org Admin role to save credentials.
3. Webhook URL registered in Accurate Developer Portal.

Setup steps

1. Connect credentials

On the Accurate setup page, enter:

Submit via backgroundChecks.connectAccurate. InsightHire calls testAccurateAuth unless skipAuthTest is set.

Credentials stored in ats_integrations with platform ACCURATE.

2. Register webhook

Copy the webhook URL from setup (also returned by backgroundChecks.accurateStatus):

{API_BASE_URL}/api/webhooks/accurate

Example: https://api.insighthire.com/api/webhooks/accurate

In Accurate Developer Portal → Webhooks, add this URL.

Optional: configure the same webhook secret in InsightHire and send it as header:

• X-Accurate-Webhook-Secret or
• X-Webhook-Secret

Sandbox environments may not auto-fire webhooks — use Accurate's portal testing module.

3. Test connection

Use Test connection (backgroundChecks.testAccurateConnection) to verify:

• alive — Accurate /alive endpoint reachable
• authOk — credentials accepted
• packageCount — packages listable
• credentialSource — org or platform

Platform vs org credentials

backgroundChecks.accurateStatus reports:

• connected — active integration with resolvable credentials
• hasOrgCredentials — tenant supplied own keys
• usingPlatformFallback — org has no keys; platform env used
• clientIdMasked — first 8 chars for identification

Ordering a background check

From the candidate profile, recruiters call backgroundChecks.initiateAccurateCheck:

Candidate requirements: first name, last name, and email must be present.

Order flow

1. Create Accurate candidate via API
2. Create local background_check_orders row (status PENDING)
3. Create Accurate order with reference codes [orderId, organizationId]
4. Update candidate backgroundCheckStatus
5. Log activity accurate.order.created

Workflows:

• INTERACTIVE — candidate receives Accurate invitation email (default)
• EXPRESS — expedited flow per Accurate package rules

Package selection

backgroundChecks.listAccuratePackages returns available packages. Sandbox accounts may return empty on /package — UI falls back to PKG_BASIC.

Webhook status updates

Accurate POSTs to /api/webhooks/accurate with payload shape:

{
  "id": "...",
  "eventType": "ORDER_STATUS_CHANGE",
  "eventInfo": {
    "orderId": "...",
    "orderStatus": "IN_PROGRESS",
    "orderResult": null,
    "percentageComplete": 50
  }
}

InsightHire:

1. Logs event in webhook_events
2. Matches orderId to background_check_orders.externalId
3. Updates order status, result, percentageComplete, lastWebhookAt
4. Maps Accurate status → candidate backgroundCheckStatus

Status mapping handled by mapAccurateStatusToBackgroundCheckStatus.

Monitoring orders

backgroundChecks.listOrders returns recent orders with:

• External Accurate order ID
• Status, result, package type, workflow
• percentageComplete, lastWebhookAt

View on candidate profile background check card.

Disconnect

backgroundChecks.disconnectAccurate sets integration isActive: false. Existing orders remain; new orders require reconnect.

Troubleshooting

API reference

Related

• Integrations overview
• Compliance settings — who can order checks