> For the complete documentation index, see [llms.txt](https://docs.samesystem.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samesystem.dev/business-guides/absence/absence-balances/fetch-absence-balances-for-current-next-period.md). # Fetch absence balances for current/next period {% hint style="info" %} Only available in API v2. {% endhint %} ### Absence balance timelines The absence balance timelines endpoint returns a user's absence balances for the **current** absence period and the next (future) absence period. {% hint style="info" %} **Reconciling with payroll** Some customers use this endpoint to fetch absence balances and compare them with the balances in their payroll system. If a balance differs, you can send a correction to the affected absence period to bring the two systems back in line. {% endhint %} Each timeline in the response represents one combination of user and absence type. Its `periodBalances` array holds one balance per period, current period first. ### Endpoint [POST /api/v2/{clientToken}/absence\_balance\_timelines](/api-v2-reference/absence-balance-timelines.md) #### Request body | Field | Type | Required | Description | | ---------------------------- | ---------------- | -------- | ------------------------------------------------- | | `data.attributes.userIds` | array of integer | Yes | Internal IDs of the users to return balances for. | | `data.attributes.absenceIds` | array of integer | Yes | IDs of the absence types to return balances for. | The response contains one timeline for every combination of the user IDs and absence type IDs you send. Requesting 2 users and 3 absence types returns up to 6 timelines. #### Example request ```http POST /api/v2/{clientToken}/absence_balance_timelines Content-Type: application/json ``` ```json { "data": { "attributes": { "userIds": [758494], "absenceIds": [104993, 106196] } } } ``` ### Response The response `data` array contains one `AbsenceBalanceTimeline` object per user and absence type combination. #### Timeline object | Field | Type | Description | | --------------------------- | ------ | ------------------------------------------------------------------------------------------ | | `type` | string | Always `AbsenceBalanceTimeline`. | | `id` | string | Timeline identifier in the format `{userId}-{absenceTypeId}`, for example `758494-106196`. | | `attributes.id` | string | Same value as `id`. | | `attributes.periodBalances` | array | Balances for the current period and the next period, in chronological order. See below. | #### Period balance object | Field | Type | Description | | ------------------- | ----------------------- | -------------------------------------------------------------------------- | | `userId` | string | ID of the user the balance belongs to. | | `absenceType.id` | string | ID of the absence type the balance belongs to. | | `absenceStartDate` | string (date) | First day of the absence period this balance covers (`YYYY-MM-DD`). | | `absenceEndDate` | string (date) | Last day of the absence period this balance covers (`YYYY-MM-DD`). | | `startDate` | string (date) | Start date of the balance record. | | `endDate` | string (date) or `null` | End date of the balance record. `null` when open-ended. | | `available` | number | Balance available to the user in the period. | | `accrued` | number | Amount accrued in the period. | | `correction` | number | Total of manual corrections applied in the period. | | `expired` | number | Amount that has expired in the period. | | `units` | string | Unit of all balance values, for example `days`. | | `corrections` | array | Individual corrections. Each item can include an `expirationDate`. | | `transfers` | array | Transfers affecting the balance. Each item can include an `absenceTypeId`. | | `calendarTransfers` | array | Calendar transfers affecting the balance. | {% hint style="info" %} IDs are sent as integers in the request but returned as strings in the response. {% endhint %} ### Period date fields To see exactly which absence period each balance belongs to, add these fields to the field filter of your request: * `periodBalances.absenceStartDate` * `periodBalances.absenceEndDate` These fields describe the absence period itself. They are the most reliable way to tell the current period from the next one, especially when absence periods don't follow the calendar year. #### Example response with period dates The example below shows absence periods running from 1 September to 31 August. ```json { "data": [ { "type": "AbsenceBalanceTimeline", "id": "759178-1860", "attributes": { "id": "759178-1860", "periodBalances": [ { "userId": "759178", "absenceStartDate": "2026-09-01", "absenceEndDate": "2027-08-31", "startDate": "2026-01-05", "endDate": null, "available": 2.47727, "accrued": 0.0, "correction": 0.0, "expired": 0.0, "units": "days", "absenceType": { "id": "1860" }, "calendarTransfers": [], "corrections": [], "transfers": [ { "absenceTypeId": "1860" } ] }, { "userId": "759178", "absenceStartDate": "2027-09-01", "absenceEndDate": "2028-08-31", "startDate": "2026-01-05", "endDate": null, "available": 25.0, "accrued": 0.0, "correction": 0.0, "expired": 0.0, "units": "days", "absenceType": { "id": "1860" }, "calendarTransfers": [], "corrections": [], "transfers": [] } ] } }, { "type": "AbsenceBalanceTimeline", "id": "759178-88093", "attributes": { "id": "759178-88093", "periodBalances": [ { "userId": "759178", "absenceStartDate": "2026-09-01", "absenceEndDate": "2027-08-31", "startDate": "2026-01-05", "endDate": null, "available": 5.0, "accrued": 5.0, "correction": 0.0, "expired": 0.0, "units": "days", "absenceType": { "id": "88093" }, "calendarTransfers": [], "corrections": [], "transfers": [] }, { "userId": "759178", "absenceStartDate": "2027-09-01", "absenceEndDate": "2028-08-31", "startDate": "2026-01-05", "endDate": null, "available": 5.0, "accrued": 5.0, "correction": 0.0, "expired": 0.0, "units": "days", "absenceType": { "id": "88093" }, "calendarTransfers": [], "corrections": [], "transfers": [] } ] } } ] } ``` Here user `759178` has two timelines, one for absence type `1860` and one for `88093`. For type `1860`, the current period (1 Sep 2026 to 31 Aug 2027) has 2.47727 days available, and the next period (1 Sep 2027 to 31 Aug 2028) has 25 days. {% hint style="warning" %} `startDate` and `endDate` do not always match the absence period. In the example above, both periods share `startDate` `2026-01-05` and an open-ended `endDate`. Use `absenceStartDate` and `absenceEndDate` to identify the period. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.samesystem.dev/business-guides/absence/absence-balances/fetch-absence-balances-for-current-next-period.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.