Create a biometric identity verification request

post

https://api.wingspan.app/v3/compliance/biometric-identity-verification-requests

Asks a payee to verify their identity with a government ID and a live selfie. The payee's underlying verification is found or created as part of this call. A request that fulfills a RequirementType: BiometricIdentityVerification requirement is provisioned by the platform when the requirement instance is created; this endpoint is the standalone path for a request that is not tied to one.

Supplying an externalId already in use for this payer account returns 409 ResourceConflict — create is not an upsert. Recover by listing with ?filter[externalId][eq]= to retrieve the existing request.

When the payee's account has no accepted principal person, the verification cannot be started, so the call returns 422 with detailCode users.BiometricIdentityVerificationPrincipalRequired. Once a principal is bound, retry with a new Idempotency-Key; a repeated key replays the earlier 422.

When the payee account's principal person already passed a verification they started themselves on another account, that result is reused, so the request can already be Complete. forceCreate skips this reuse.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Open an identity verification ask inside a payer-payee relationship. The payee's verification is found or created as part of this call — there is no separate step, and no endpoint that creates a verification on its own.

The body names the relationship and never an Account. Both parties are resolved from payerPayeeId, so either side of the relationship can call this: a payer asking their contractor to verify, or a contractor opening their own verification against a requirement their payer assigned.

The seats are not symmetric, and the two refusals are ordered. A payee must cite the requirementId their verification satisfies; without it the answer is 400 regardless of what else the body carries. With it, a payee who also sends externalId or a non-empty metadata gets 422 — both annotation columns belong to the payer. So a payee copying a payer's example body gets 400 for the missing requirementId first, not 422 for the externalId beside it. A payer may omit requirementId entirely; that is the direct ask, and no requirement's state can refuse it.

Repeat calls citing the same requirementId inside the same relationship return the request already open rather than a second one. externalId and forceCreate both opt out of that.

payerPayeeId

string

required

The PayerPayee record this verification is asked for. Accepts canonical Wingspan ids and legacy composite relationship ids returned by V3 payer/payee read/list endpoints. A relationship that does not resolve, or one the calling Account holds no seat on, returns 404.

requirementId

string

The Requirement this verification satisfies. Required when the payee opens the request — 400 without it — and optional for the payer, whose direct ask needs no requirement to justify it. The id is a gate, not a binding: it authorises the create and is not stored on the request. Attaching the result to the Requirement is a separate call.

externalId

string

Caller-supplied reconciliation id, unique per payer account. A duplicate returns 409 ResourceConflict. Payer-only: 422 from the payee seat, when a requirementId is present — without one the missing requirementId is answered first, with 400.

forceCreate

boolean

Mint a brand-new verification rather than reuse the payee's current one, and open this request against the new verification. Defaults to false.

Only reaches for a new verification when the payee's current one has already finished (Passed or Failed); an in-flight verification is reused either way. Setting it also opts this call out of the repeat handling above, so a second request is opened rather than the first one returned.

One side effect to know about: a new verification created this way skips the legacy auto-resolve backfill. A payee who completed identity verification through an older Wingspan integration is normally auto-resolved against that result; with forceCreate they are asked to verify again.

metadata

object

Payer-only, like externalId: a payee sending a non-empty map is refused 422, when a requirementId is present — without one the missing requirementId is answered first, with 400. The PATCH that maintains this column is payer-scoped too, so a payee who set it here could never correct it afterwards.

Headers

Idempotency-Key

string

length between 1 and 255

^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

X-Wingspan-Account

string

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201Biometric identity verification request created

400Malformed request syntax

401Unauthenticated

403Forbidden

404Resource not found

409Conflict

422Validation error