Verifications
A verification holds a person and one to fifty claims. Each claim is checked against every primary source that covers it and rolled up to one verdict.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/verifications | Create. 201 with status pending or complete. |
| GET | /v1/verifications/{id} | Read. ?wait=25 long-polls until complete or 25 s. |
| GET | /v1/verifications | List. Filters: status, reference, createdAfter, personLastName. |
| POST | /v1/verifications/{id}/cancel | Cancel pending claims (outreach and async only). Final claims stay. |
| GET | /v1/verifications/{id}/report.pdf | The consumer report PDF with evidence index and Summary of Rights. |
| GET | /v1/verifications/{id}/evidence | Evidence index across every claim and source. |
Request body
| Field | Type | Notes |
|---|---|---|
person | object | firstName, lastName required; middleName, dob, aliases[], email, phone optional. More identifiers mean fewer ambiguous matches. |
claims[] | array | 1–50 claims of any claim type. claimId is echoed back. |
purpose | enum | employment, current_staff_monitoring, network_credentialing. Every purpose runs under full FCRA controls. |
consent | object | {consentId} from hosted consent, or {disclosureVersion, signedAt, signerIp} from your own flow. |
options | object | maxAge (ISO-8601 duration; accept a result we produced within this window, default always live), allowPaidThirdParty (route to The Work Number when an employer redirects), deadline for outreach. |
reference | string | Your identifier (ATS requisition, candidate id). Filterable. |
metadata | object | Up to 20 string key-value pairs, echoed back. |
Hosted consent
Create a consent link, send the candidate to it, and pass the returned consentId on the order. The signed disclosure is stored as evidence.
POST /v1/consents
{ "person": { "firstName": "Amy", "lastName": "Kowalski", "email": "amy@example.com" },
"purpose": "employment", "redirectUrl": "https://ats.example.com/done", "stateAddons": "auto" }
→ { "id": "cons_8f1…", "url": "https://primarycheck.com/consent/…", "status": "pending" }Pending and complete
A verification is complete only when every claim has a final verdict. Live board lookups usually finish within seconds; employer and registrar outreach can take days. Partial results are never reported as complete.