Employment-verification integration guide

The shape of the integration

Three touchpoints: create a verification (with the candidate's details, the package, and your certifications), listen for status events, and retrieve the report when it completes. Everything else — invitations, source outreach, review — happens inside HVR and surfaces as status.

Statuses are a contract

Every status carries a plain-language label, the responsible party, and the expected next update. Build your UI on those fields rather than hard-coding status strings: when a case is waiting on the candidate, your recruiter should see that, not a generic 'in progress'.

• verification.status_changed — any transition, with responsible party
• verification.action_required — candidate or verifier is blocking
• verification.exception_raised — a discrepancy or unverifiable field
• report.completed — a report version is retrievable
• dispute.opened / dispute.completed — delivered to report recipients

Webhooks over polling

Subscribe rather than poll: payloads are signed, retried with backoff, and replayable from the dashboard. Dispute events matter more than teams expect — a reinvestigation can change a report you already acted on, and your system should surface the corrected version.

Sandbox first

Sandbox keys exercise the same status model and report structure as production, with fictional consumers. Field names are illustrative until the published API version; the versioned reference ships with your sandbox credentials. Do not build against undocumented fields.