FAfactorialhr
Timeoff > AllowanceStat

Reads all Allowance stats

Changed on

Retrieves the employee time off counters for a specific allowance with a reference date. Read without employee_ids it pages by employee with a cursor: limit and meta.total count employees rather than stats, so a page carries every stat those employees have, and the page parameter is not supported there - follow meta.end_cursor instead.

get/api/2026-10-01/resources/timeoff/allowance_stats

Request

  • Base URL
    https://api.factorialhr.com
  • URL
    https://api.factorialhr.com/api/2026-10-01/resources/timeoff/allowance_stats
  • Auth
    • OAuth 2
      Authorization code: https://id.factorialhr.com/oauth/authorize
      Token URL: https://id.factorialhr.com/api/oauth/token scopes: time_off
    • or API key in header x-api-key

Query parameters

ids[]string[]

A virtual ID for the allowance stat, composed of employee_id/allowance_id/reference_date. Cannot be used to fetch this resource.

employee_ids[]string[]

IDs of the employees to read allowance stats for, at most 25 per request. Leave it empty to read every employee you have access to. Naming an employee you cannot access returns an empty page rather than the stats for the others.

[
  "1"
]
allowance_ids[]string[]

Filter the stats by these allowance IDs

[
  "1",
  "2"
]
reference_datestring

The reference date to calculate the allowance stats. If not provided, it will use today's date.

Example:2023-10-01
simulate_policy_change_to_idstring

When provided, computes the stats as if the employee were moved to this target time off policy effective the day AFTER reference_date, so pass the day before the change date - for a change effective on 2026-08-03, send reference_date=2026-08-02. This truncates the source policy's current cycle at that boundary so available_days reflects the prorated balance that would actually transfer or be discarded on the change, rather than the full entitlement. Purely a read - nothing is persisted. Requires the policy timeline feature; without it the result is identical to an un-simulated read. Can only be used together with employee_ids, because a simulation needs every employee in the read to belong to the target policy's company - which a company-wide read cannot guarantee.

Example:1

Response

OK

Example response

{
  "data": [
    {
      "id": "1/2/2023-10-01",
      "allowance_id": "10",
      "employee_id": "42",
      "year": 2025,
      "cycles": [
        {
          "id": "10/2025-01-01/2025-12-31",
          "start_at": "2025-01-01",
          "end_at": "2025-12-31",
          "regular_start_at": "2025-01-01",
          "regular_end_at": "2025-12-31",
          "allowance_id": 10
        }
      ],
      "cycle_carry_overs": [
        {
          "from_cycle_ending_on": "2024-12-31",
          "expire_in_months": 3,
          "non_expire": false,
          "total": "5.0",
          "used": [
            {
              "date": "2024-06-15",
              "amount": "1.0"
            }
          ],
          "accumulated": "5.0",
          "expired": "0.0",
          "taken": "2.0"
        }
      ],
      "accumulated_carry_over": "3.5",
      "available_days": "8.0",
      "total_accrued_units": "15.0",
      "total": "19.0",
      "incidences": "1.0",
      "accrued_incidences": "0.5",
      "available_incidences": "0.5",
      "max_balance_cap": "25.0",
      "policy_allowance": "20.0",
      "prorated_allowance_days": "18.5",
      "total_in_decimal": "20.0",
      "used_carry_over": "1.5",
      "used_days": "7.0",
      "used_units_until_reference_date": "6.5",
      "outstanding_units": "2.0"
    }
  ]
}

Changes