Wex Health and Benefits APIs

Get Election History

Retrieve enrolled election history for a consumer, filtered by election start_date within a lookback window.

Required: consumer_id must be provided.

Filtering:

lookback_years — each unit is 365 days (not calendar years); only elections where start_date >= (UTC_NOW - lookback_years * 365 days) are returned (default 5, range 1–10)
plan_type and plan_year_id — independently optional filters; when both are provided they are combined with AND logic. Multiple plan_type values match any listed type (OR). Invalid plan_type values return 400. plan_type=HSA (or filters that only match HSA) returns 200 with an empty items array because HSA elections are excluded from this endpoint
include_future_plans — when true, also include future elections with start_date <= (UTC_NOW + 1 year) (default false)

Sorting: Results are ordered by start_date descending (most recent first). No custom sort parameters are supported.

Pagination: Supports page and page_size (same defaults/limits as other list endpoints).

Response: Paginated items + pagination. Each item is a slim election with identity, status, plan_id, start_date, and optional elected_contribution.spending_account_detail (string amounts). Does not include claims total-used amounts. HSA elections are excluded (closed-ended HSA handling is tracked in BEX-15221).

Errors: Uses application/problem+json Problem Details (same as other Benefits endpoints); see 400 response examples for this operation.

Header Parameters

X-Request-Idstring

Optional correlation ID associated with the request, comprised of alphanumeric or hyphen characters up to 36 characters in length.

Query Parameters

consumer_idstring Required

Consumer identifier (required).

plan_typearray

Optional filter for one or more plan types. Can be used alone or combined with plan_year_id.

Filter behavior:

If provided alone: returns elections for any of the listed plan types across all plan years (within the lookback / future window); multiple values are ORed
If combined with plan_year_id: returns elections matching the plan year AND any of the listed plan types (AND + OR)
Invalid values (not a supported PlanType) return 400 Bad Request
HSA is a valid `PlanType...

Show child attributes

plan_year_idstring

Optional filter for a specific plan year. Can be used alone or combined with plan_type.

Filter behavior:

If provided alone: returns all elections for this plan year across all plan types (within the lookback / future window)
If combined with plan_type: returns elections matching both filters (AND logic)

include_future_plansboolean

When true, include elections with start_date in the future, in addition to the lookback history window.

Future elections are limited to those with start_date <= (UTC_NOW + 1 year).

When false (default), only elections within the lookback window are returned.

lookback_yearsinteger

Number of 365-day periods to look back from UTC today. Only elections where start_date >= (UTC_NOW - lookback_years * 365 days) are returned. This is fixed 365-day math, not calendar-year subtraction (large values can differ slightly from calendar-year boundaries due to leap days).

Examples (UTC_NOW = 2026-08-21T00:00:00Z):

lookback_years: 5 → threshold 2021-08-21T00:00:00Z (UTC_NOW minus 1,825 days)
lookback_years: 1 → threshold 2025-08-21T00:00:00Z (UTC_NOW minus 365 days)

Wh...

Minimum

Maximum

pageinteger

Zero-based page index.

page_sizeinteger

Maximum number of rows to return per page (1-100).

Minimum

Maximum

100

Response

titlestring

statusinteger

detailstring

instancestring

errorsobject

Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.

validation_errorsobject

Field-level validation errors keyed by field name. Each key maps to one or more structured error details.

Production:

Sandbox:

Sections