Paystubs and benefit enrollments

These list calls give a Person, or the Account that Person is principal of, a read view of paystubs and benefit enrollments. They return summaries. Follow the ids in each row to the full resource.

Prerequisites

• For the Person calls: a Person session. They're Person-scoped, so don't send X-Wingspan-Account.
• For the Account calls: an Account credential. Use X-Wingspan-Account when you act on a child Account.
• Scope benefits.enrollment:read for GET /v3/platform/benefit-enrollments.

Endpoints

All four take page[size] (1 to 100, default 25) and page[token]. Follow pagination.nextPageToken until it's an empty string.

Paystubs

A paystub row is a Person-scoped view of a PayStatement.

• GET .../persons/{personId}/paystubs returns paystubs where the Person was the principal of the receiving Account on the pay date. It combines every Account the Person was principal of, in chronological order. Filter by pay date with filter[paidAt][gte] and filter[paidAt][lte] (dates).
• GET .../accounts/{accountId}/paystubs lists the paystubs for that Account's principal.

Row fields:

For the full statement, call GET /v3/payments/pay-statements/{payStatementId}. See Pay statements.

curl "https://api.wingspan.app/v3/platform/persons/$PERSON_ID/paystubs?filter[paidAt][gte]=2026-01-01&page[size]=10" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Errors: 400 for a malformed filter or an X-Wingspan-Account header on a Person call, 404 when the Person or Account isn't visible to the caller.

Benefit enrollments

Person view. GET .../persons/{personId}/benefit-enrollments lists enrollments where the Person is the enrolled beneficiary. Row fields: id, benefitEnrollmentId, planId, accountId (the sponsoring Account), personId, status, startDate, endDate. Creating and managing enrollments stays on the Account side.

Account view. GET /v3/platform/benefit-enrollments lists the enrollments held within your Account scope, for every benefit product. Each row is a full BenefitEnrollment: productId (for example MeridioHealth), planId, subscriptionId, status, effectiveDate, terminationDate, beneficiaryPersonId, dependents[], events, and actors.

Filters on the Account list, all of which accept [eq] or [anyOf][]:

Sort with sort on createdAt (default, newest first), updatedAt, effectiveDate, or terminationDate. Prefix - for descending.

curl "https://api.wingspan.app/v3/platform/benefit-enrollments?filter[status][anyOf][]=Active&filter[status][anyOf][]=PendingCancellation" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

An enrollment moves Created, Active, PendingCancellation, Cancelled. To create, read, update, cancel, or reverse a pending cancellation, see Benefit enrollments.

Webhooks

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

Related pages

• Pay statements
• Benefit enrollments
• Forms received