List Benefit Years

/benefits/{tenantId}/years

Returns a paginated list of benefit years.

Request parameters

Responses

{
  "items": [
    {
      "id": "019f1297-1b6a-780c-8cd2-8bdfb57c7bb6",
      "status": "INVISIBLE",
      "tenantId": "9488998e-272c-48bd-a753-a61521b2f6d9",
      "year": 2023,
      "isReady": false,
      "contentZoneId": "019f2238-ded9-7ac7-8327-c92939df580e",
      "createdAt": "2026-06-29T09:55:20+00:00",
      "updatedAt": null
    },
    {
      "id": "019f1297-1b69-7d9d-86c4-4dff43dcf01f",
      "status": "VISIBLE",
      "tenantId": "9488998e-272c-48bd-a753-a61521b2f6d9",
      "year": 2026,
      "isReady": true,
      "contentZoneId": "019f2238-f0c7-7ee2-bbce-45b2faae0314",
      "createdAt": "2026-06-29T09:55:20+00:00",
      "updatedAt": "2027-04-18T04:40:51+00:00"
    },
    {
      "id": "019f1297-1b69-7b25-86c4-4dff431b22eb",
      "status": "DEFAULT",
      "tenantId": "9488998e-272c-48bd-a753-a61521b2f6d9",
      "year": 2025,
      "isReady": true,
      "contentZoneId": "019f2239-0f02-7cd6-b4fd-fc0ff6b5037b",
      "createdAt": "2025-06-29T09:55:20+00:00",
      "updatedAt": "2026-07-17T17:10:52+00:00"
    }
  ],
  "page": 1,
  "perPage": 10,
  "total": 19,
  "totalPages": 2
}

{
  "error": "Invalid sort field."
}

Query Behavior Details

Filtering Rules

Four independent filters are available — status, year, isReady, and contentZoneId. They combine with logical AND, and omitting a filter returns all values for that field.

Exact Match: Each filter performs a strict equality check (=). Partial matches, ranges, "starts with", and "not like" are not supported.
Case-Sensitive (status): The value must match the uppercase enum casing exactly.
Single Value Only: One value per filter per request. Arrays (e.g. status[]=VISIBLE&status[]=DEFAULT) and comma-separated lists are not supported.

Sorting Rules

Sortable fields are id, year, createdAt, and updatedAt. Note the asymmetry with filtering: status, isReady, and contentZoneId can be filtered but not sorted, while createdAt and updatedAt can be sorted but not filtered.

Defaults: If you omit both sorting parameters, results are sorted by id DESC.
Dependencies: If you provide sortBy, you must also provide sortOrder (and vice-versa).

01 September 2026