Requirement definition groups

A requirement definition group is a named bundle of requirement definitions. In the API a definition is also called a template. Use a group to keep related definitions together, for example everything a California registered nurse must complete.

A group doesn't make Payees complete anything by itself. To require a definition of a Payee, attach it to an Engagement. See Requirements and eligibility.

Prerequisites

• An Account credential, with X-Wingspan-Account when you act on a child Account. Groups belong to the Account that creates them.
• Scopes: payments.requirement-definition:read and payments.requirement-definition:write.
• Requirement definition ids from GET /v3/onboarding/requirement-definitions. See Requirement definitions.

Endpoints

Create a group

curl -X POST https://api.wingspan.app/v3/onboarding/requirement-definition-groups \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "California RN Onboarding", "description": "Licence, background check, W-9" }'

// 201 Created (trimmed)
{
  "id": "Gr4nTq7LwX2sYb9kMc3dZa",
  "accountId": "Nw7kQ2pLx9RtVb3mHc5dZa",
  "name": "California RN Onboarding",
  "description": "Licence, background check, W-9",
  "requirementCount": 0,
  "metadata": {},
  "events": { "createdAt": "2026-11-02T15:04:05.000Z", "updatedAt": "2026-11-02T15:04:05.000Z" }
}

requirementCount is the number of definitions currently in the group.

Read, update, and delete

• GET the list returns your groups, newest first, with page[size] and page[token]. It has no filter parameters.
• PATCH changes name, description, and metadata. Fields you omit stay as they are. If you send metadata, it replaces the stored map, so send the whole map. An empty body is rejected.
• DELETE returns 204 with no body.

Add and remove definitions

POST .../requirements adds a definition to the group:

The 201 response is the item: id (the membership id, which you pass as itemId to remove it), requirementDefinitionGroupId, requirementDefinitionId, isBlocking, and events.createdAt.

GET .../requirements lists the items, newest first, with page[size] and page[token].

DELETE .../requirements/{itemId} removes the membership and returns 204. It doesn't delete the definition.

Errors

Related pages

• Requirements and eligibility
• Requirement monitors