Identity verification checks

This page covers the calls that follow creating and resuming an identity verification: cancel it, and read the result of each check. For creating and resuming a verification and running the embedded session, see Identity verification.

Prerequisites

An identity verification id from createIdentityVerification or listIdentityVerifications.
A Person credential. Cancel and the two check reads are Person-scoped: send no X-Wingspan-Account header, or the API returns 400 AccountScopeNotApplicable.

Endpoints

Method and path	Operation
`POST /v3/onboarding/identity-verifications/{identityVerificationId}/cancel`	`cancelIdentityVerification`
`GET /v3/onboarding/identity-verifications/{identityVerificationId}/checks`	`listIdentityVerificationChecks`
`GET /v3/onboarding/identity-verifications/{identityVerificationId}/checks/{checkId}`	`getIdentityVerificationCheck`

Verification statuses

IdentityVerification.status is one of Created, InProgress, UpdateRequired, Completed, Failed, Cancelled, or Expired. Completed, Failed, Cancelled, and Expired are terminal. When the status is Completed, read the result from decision.outcome.

Cancel a verification

Cancel is a terminal transition. The verification moves to Cancelled and stops processing. It's valid from Created, InProgress, or UpdateRequired. The request takes no body. Send If-Match with the verification's ETag if you want the call to fail when the verification changed since you read it.

curl -X POST https://api.wingspan.app/v3/onboarding/identity-verifications/$VERIFICATION_ID/cancel \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

The 200 response is the IdentityVerification with status: "Cancelled", events.cancelledAt, and actors.cancelledBy set.

Status	When
`404`	No verification with that id is visible to the caller.
`409 InvalidStateTransition`	The verification is already `Completed`, `Failed`, `Cancelled`, or `Expired`.
`412`	`If-Match` doesn't match the current version.

Read the checks

A verification runs one or more checks. The same array is embedded in IdentityVerification.checks[]. The two check endpoints let you address one check directly.

Each IdentityVerificationCheck has:

Field	Meaning
`type`	`TinMatch`, `KybLite`, `KybFull`, `OfacScreening`, `PepScreening`, `AdverseMedia`, `UboCollection`, `DocumentVerification`, `LivenessCheck`, or `BiometricMatch`.
`status`	`Pending`, `Passed`, `Failed`, `UpdateRequired`, `NotApplicable`, or `Skipped`.
`reasons[]`	Reason codes for the result.
`errors[]`	Per-field errors. Present only when `status` is `UpdateRequired`. Same shape as `errors[]` on a `422` problem response.
`evidence`	`dataSources[]` (for example `IRS_TIN`, `OFAC_SDN`). `vaultFileIds` are internal and can't be read through the vault-files endpoints.
`events`	`startedAt`, `passedAt`, `failedAt`, `updateRequiredAt`, `completedAt`.

A check's status is independent of the parent. A verification can complete with decision.outcome: Approved while some checks read Skipped or NotApplicable.

curl https://api.wingspan.app/v3/onboarding/identity-verifications/$VERIFICATION_ID/checks \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Both reads return 404 when the verification or check isn't visible to the caller.

Webhooks

The webhook catalog lists IdentityVerification.* and IdentityVerificationCheck.* events. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.