Search engagements

POST /v3/payments/payee-engagements/search finds PayeeEngagements across all your Payees. You send the query in a JSON body instead of in filter[...] query parameters. This page shows you how to build that body and read the results.

Before you start

A Payer Account that has Payees with engagements. See Engagements.
A token with the payments.payee-engagement:read scope.
To search as a child Account, send X-Wingspan-Account. See Acting on behalf of Accounts.

When to use search

You want	Use
Simple filters on `status`, `engagementType`, `engagementId`, or `externalId`	`GET /v3/payments/payee-engagements`
One Payee's engagements	`GET /v3/payments/payees/{payeeId}/engagements`
A body-based query with field-level filters, a sort, and a page limit	`POST /v3/payments/payee-engagements/search`

Both list calls and search return the same PayeeEngagement resource.

The request body

Field	Type	What it does
`query`	string	Free-text query.
`filters`	object	Structured, field-level filters. Each field maps to an operator and a value.
`sort`	string	Comma-separated fields. Prefix a field with `-` for descending, for example `-createdAt`.
`limit`	integer	Page size, 1 to 100. Defaults to 25.

All four fields are optional. The call is a read. It changes nothing, and it accepts an Idempotency-Key like other POST calls.

Worked example

Find activated engagements for one Engagement template, newest first:

curl -X POST https://api.wingspan.app/v3/payments/payee-engagements/search \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "status": { "in": ["Activated"] },
      "engagementId": { "in": ["Fj9ZSOWd3LdiamTunQ5x98"] }
    },
    "sort": "-createdAt",
    "limit": 25
  }'

// (trimmed)
{
  "url": "/v3/payments/payee-engagements/search",
  "data": [
    {
      "id": "ru9zEafz6i4WRlIOA10wAk",
      "engagementId": "Fj9ZSOWd3LdiamTunQ5x98",
      "payeeId": "Pe4tR8nXw2KqLm7vB1cZd5",
      "engagementType": "Contractor",
      "status": "Activated",
      "paymentsEligibility": "Eligible",
      "areAllRequirementsComplete": true
    }
  ],
  "pagination": { "nextPageToken": "" }
}

Filters follow the eq, in, and != operators shown in the schema's example. Field names are the PayeeEngagement fields: status (Created, Activated, Suspended, Terminated), engagementType, engagementId, payeeId, externalId, startDate, endDate, and paymentsEligibility (Eligible or NotEligible).

Read the results

The response is a PayeeEngagementList: a data array of PayeeEngagements and a pagination object.

pagination.nextPageToken is an empty string when there are no more results. That is the only end-of-results signal.
pagination.totalSize is an estimated count and can be missing.
Use limit to set how many engagements come back per page.

See Pagination for how tokens work across V3 lists.

Errors

Status	When
`400`	The request body can't be parsed.
`401`	The token is missing or invalid.
`403`	The token lacks `payments.payee-engagement:read`, or the Account can't read these engagements.
`422`	A filter, sort, or `limit` value is invalid. `limit` must be 1 to 100.