Benefit enrollments

A benefit enrollment records that an Account, or a Person on it, holds a benefit product such as health or dental cover. The list includes every benefit product the Account holds, whether or not Wingspan bills for it.

Prerequisites

• benefits.enrollment:read to read and benefits.enrollment:write to create, change or cancel.
• payments.payroll-settings:read to list benefit plans.
• X-Wingspan-Account set to the Account that enrolls.

Endpoints

Benefit plans

A benefit plan has id, name, description, type (Health, Dental, Vision, Life, Disability, Retirement or Other), provider, price, currency and interval (Monthly or Annual). A missing plan returns 404.

Enrollment status

An enrollment moves Created, Active, PendingCancellation, Cancelled.

Create an enrollment

planId is required. effectiveDate, dependents and metadata are optional.

curl -X POST https://api.wingspan.app/v3/platform/benefit-enrollments \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: Nw7kQ2pLx9RtVb3mHc5dZa" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "Bq4nTx7KmW2cLd9vRh6YsE",
    "effectiveDate": "2026-12-01",
    "dependents": [
      { "firstName": "Sam", "lastName": "Rivera", "dateOfBirth": "2019-04-12", "relationship": "Child" }
    ]
  }'

The response is 201 with the enrollment. The values in the example are illustrative. Dependents are personal data: do not log them.

List enrollments

List enrollments returns the enrollments within your account scope. Filters: filter[status] with eq or anyOf, filter[productId] with eq or anyOf, and filter[accountIds] with eq or anyOf. Repeat anyOf[] to match several values. Sort on createdAt (default, newest first), updatedAt, effectiveDate or terminationDate.

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

Update, cancel and restore

Update an enrollment uses JSON Merge Patch on dependents and metadata. It does not cancel.

Cancel an enrollment takes no body. It moves your own Active enrollment to PendingCancellation. The product's own rules decide when cover ends, and the response returns it as terminationDate. Withdraw a cancellation reverses it before that date.

Webhook events

BenefitEnrollment lifecycle events are published as webhooks. See Webhooks and events to subscribe.