Skip to main content

​
Core concepts

This page explains the Verification workflow from the customer’s perspective: how you start work, how SNH AI processes it, and how you receive outcomes.

​
What Verification does

The Verification service automates employment and education verification. You send applicant and history data. SNH AI researches contacts, performs outbound outreach, processes inbound responses, and returns structured results.

​
Order → Search → Result

One order can contain multiple searches (for example employment and education together). Each search progresses independently.

​
Status lifecycle

Orders and searches each have a status that progresses through a defined set of values.

​
Order status

​
Search status

​
Verification result outcomes

When a search completes, the verificationResult.outcome field contains one of: Additional outcomes may be introduced as the platform expands. For forward compatibility, treat any unrecognized outcome as requiring manual review.

​
How you get responses

  1. Create response (sync): 201 with verificationOrderId and searchIds — the order was accepted, not finished.
  2. Webhooks (async, preferred): Configure webhookConfig on the order or rely on organization defaults. Verify X-Webhook-Signature.
  3. Polling (async fallback): Use GET /orders/{id}/searches for search status and verification results. Use GET /orders/{id}/searches/{searchId} when you also need activity history. Use GET /orders/{id} only for order-level status — its nested search list is a summary and does not include results.
See Webhook overview and Quickstart.

​
Batch vs single order

  • Single order: POST /background-check/v1/orders — primary integration path.
  • Batch: POST /background-check/v1/batches submits many orders in one HTTP call. Each order is independent — record every verificationOrderId and track work with order endpoints. See API overview.

​
Supported schemas

Request and response field schemas are listed under Schemas in the navigation. Start with VerificationRequest and Search types.

​
Next steps