Requirement definitions

A requirement definition is a reusable template for something a Payee must complete, such as signing a document, uploading a license, or passing a background check. Attach a definition to an Engagement to require it. For the end-to-end flow, see Requirements and eligibility. To bundle definitions, see Requirement definition groups.

Prerequisites

• An Account credential. Use X-Wingspan-Account when you act on a child Account. Definitions belong to the Account that creates them.
• Scopes: payments.requirement-definition:read and payments.requirement-definition:write.
• For types backed by a configuration, the dataSourceId of a template your Account owns, such as a document template.

Endpoints

Send an Idempotency-Key on every POST and PATCH.

Create a definition

name and type are required.

Each Account can have one BiometricIdentityVerification definition and one EmploymentEligibilityVerification definition. A second returns 409.

The fields isBlocking, isPayeeActionRequired, isPayerActionRequired, source, passingValues, and policy are legacy. The V3 API rejects them. Use type, reviewPolicy, and the Engagement's blockingMode.

curl -X POST https://api.wingspan.app/v3/onboarding/requirement-definitions \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sign the 2026 NDA",
    "type": "Signature",
    "dataSourceId": "t1erTOHO7rlJI7nzF8uCpY",
    "reviewPolicy": "NeverRequired",
    "expirationDays": 365,
    "externalId": "REQ-NDA-2026"
  }'

The 201 response is the definition. The values in the example are illustrative.

{
  "id": "oP8lYOzdKQy7H_mNrx9Uf9",
  "name": "Sign the 2026 NDA",
  "type": "Signature",
  "status": "Active",
  "version": 1,
  "dataSourceId": "t1erTOHO7rlJI7nzF8uCpY",
  "reviewPolicy": "NeverRequired",
  "expirationDays": 365
}

Create isn't an upsert. A duplicate externalId returns 409 ResourceConflict. To recover, list with filter[externalId][eq].

List and read

GET /v3/onboarding/requirement-definitions takes page[size] and page[token].

Sort with sort[updatedAt]=asc or desc. pagination.totalSize counts the filtered results, so you can show active and archived counts.

curl -g "https://api.wingspan.app/v3/onboarding/requirement-definitions?filter[status][in][]=Active&filter[type][in][]=Signature" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

GET .../{requirementDefinitionId} returns one definition. Add ?expand[]=DataSource to inline the backing configuration in dataSource. Expansion isn't available on list rows.

A definition also returns these read-only fields: status, version, minVersion, versionScope, versionCreatedAt, versionNote, versionTransitionStrategy, versionTransitionExpiresAt, versionHistory, events, and actors.

Update a definition

PATCH is a JSON Merge Patch. Send only the fields to change: name, description, dataSourceId, manualRenewalAllowed, expirationStrategy, expirationDays, reviewPolicy, metadata, versionNote, and transition. daysUntilEffective and daysUntilExpiration are create-only.

Wingspan decides whether a change is material. A material change, such as pointing dataSourceId at a new template, publishes a new version. transition controls how existing instances pick it up:

An immaterial change doesn't raise version or reopen existing instances. dataSourceId returns 422 for a type that has no data source and 404 for a template your Account doesn't own.

curl -X PATCH https://api.wingspan.app/v3/onboarding/requirement-definitions/$DEFINITION_ID \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceId": "Hq3mVx8TnC5wPd2ZrL7bKe",
    "versionNote": "Updated NDA wording",
    "transition": { "scope": "IncompleteAndNew", "strategy": "Immediate" }
  }'

Deactivate, activate, and delete

• POST .../deactivate archives the definition (status: Inactive). Nothing is deleted.
• POST .../activate restores an archived definition to Active.
• DELETE .../{requirementDefinitionId} removes it permanently and returns 204. A definition attached to active Engagements can't be deleted and returns 409.

Use deactivate when you may want the definition back.

Errors

Related pages

• Requirements and eligibility
• Requirement definition groups
• Requirement monitors
• Engagements