> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.sesametime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the rest-compensable balance of an employee

> Returns the balance of the employee `employeeId` that can be compensated with rest over the `from`-`to` period, per source, in seconds. It is the value `POST /overtime-policies/v1/compensations/rest` checks `balanceBeforeSeconds` against: read it right before that request, with the same `from`/`to`, and send the value of the key matching the source (`positive_balance` for `positive_balance`, `negative_balance` for `negative_balance`, `total_balance` otherwise). Only closed days count (up to yesterday), and time to be remunerated, time already compensated and expired time are excluded, so it drops after every compensation and a replayed request is rejected with 409 `compensable_balance_changed`. A `reset` adjustment zeroes it as of the moment it is made, except that time expired before the reset still reduces it afterwards. It differs from `GET /overtime-policies/v1/employees/{employeeId}/balance`, which is the balance adjustments are checked against. The employee must belong to the company of the token. The read permission is checked over the employee before the lookup: an employee the API consumer has no role over answers 403. When the permission passes, as it does for a company-wide API consumer, an id that is not an employee of the company of the token (including an unknown id) answers 422 `employee_not_adjustable`.



## OpenAPI

````yaml GET /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance
openapi: 3.0.0
info:
  description: ''
  version: 3.0.0
  title: Sesame Public API
servers:
  - url: https://api-{region}.sesametime.com
    variables:
      region:
        default: eu1
security: []
tags: []
paths:
  /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance:
    get:
      tags:
        - Overtime Policies
      summary: Get the rest-compensable balance of an employee
      description: >-
        Returns the balance of the employee `employeeId` that can be compensated
        with rest over the `from`-`to` period, per source, in seconds. It is the
        value `POST /overtime-policies/v1/compensations/rest` checks
        `balanceBeforeSeconds` against: read it right before that request, with
        the same `from`/`to`, and send the value of the key matching the source
        (`positive_balance` for `positive_balance`, `negative_balance` for
        `negative_balance`, `total_balance` otherwise). Only closed days count
        (up to yesterday), and time to be remunerated, time already compensated
        and expired time are excluded, so it drops after every compensation and
        a replayed request is rejected with 409 `compensable_balance_changed`. A
        `reset` adjustment zeroes it as of the moment it is made, except that
        time expired before the reset still reduces it afterwards. It differs
        from `GET /overtime-policies/v1/employees/{employeeId}/balance`, which
        is the balance adjustments are checked against. The employee must belong
        to the company of the token. The read permission is checked over the
        employee before the lookup: an employee the API consumer has no role
        over answers 403. When the permission passes, as it does for a
        company-wide API consumer, an id that is not an employee of the company
        of the token (including an unknown id) answers 422
        `employee_not_adjustable`.
      operationId: GetEmployeeRestCompensableBalance
      parameters:
        - name: employeeId
          in: path
          required: true
          description: The employee ID. It must belong to the company of the token.
          schema:
            type: string
            format: uuid
        - name: from
          in: query
          required: true
          description: >-
            First day of the period (Y-m-d). Must not be after `to`. Use the
            same value as in `POST /overtime-policies/v1/compensations/rest`.
          schema:
            type: string
            format: date
            example: '2026-01-01'
        - name: to
          in: query
          required: true
          description: >-
            Last day of the period (Y-m-d), inclusive. It can be equal to
            `from`. Use the same value as in `POST
            /overtime-policies/v1/compensations/rest`.
          schema:
            type: string
            format: date
            example: '2026-01-31'
      responses:
        '200':
          description: >-
            Rest-compensable balance of the employee for the period. The status
            is 200; `meta` is the default single-object meta.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: object
                    description: >-
                      Balance of the employee that can be compensated with rest
                      over the requested period, in seconds, per source
                      (RestCompensableBalanceForApiView). Only closed days
                      count; the rest and shared buckets, margins, adjustments
                      and transfers are included; time to be remunerated, time
                      already compensated and expired time are not. Every number
                      is clamped at 0.
                    required:
                      - total_balance
                      - positive_balance
                      - negative_balance
                    properties:
                      total_balance:
                        type: integer
                        minimum: 0
                        description: >-
                          Net rest-compensable balance. Value to send as
                          `balanceBeforeSeconds` for source `total_balance` (or
                          when `source` is omitted).
                        example: 5400
                      positive_balance:
                        type: integer
                        minimum: 0
                        description: >-
                          Rest-compensable positive balance. Value to send as
                          `balanceBeforeSeconds` for source `positive_balance`.
                        example: 7200
                      negative_balance:
                        type: integer
                        nullable: true
                        minimum: 0
                        description: >-
                          Rest-compensable magnitude of the negative balance (a
                          positive number). Value to send as
                          `balanceBeforeSeconds` for source `negative_balance`.
                          `null` when the overtime policy of the employee does
                          not allow compensating from the negative balance (only
                          independent policies with separate positive and
                          negative balances do); a request with that source is
                          then rejected with 422.
                        example: 1800
                  meta:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                        example: 1
                      lastPage:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      perPage:
                        type: integer
                        example: 1
              examples:
                negative_source_available:
                  summary: >-
                    Independent policy with separate positive and negative
                    balances
                  value:
                    data:
                      total_balance: 5400
                      positive_balance: 7200
                      negative_balance: 1800
                    meta:
                      currentPage: 1
                      lastPage: 1
                      total: 1
                      perPage: 1
                negative_source_unavailable:
                  summary: Policy that does not compensate from the negative balance
                  value:
                    data:
                      total_balance: 7200
                      positive_balance: 7200
                      negative_balance: null
                    meta:
                      currentPage: 1
                      lastPage: 1
                      total: 1
                      perPage: 1
        '401':
          description: >-
            Unauthorized - The `Authorization: Bearer` token is missing, unknown
            or disabled (`unauthorized`, UnauthorizedHttpException), or the API
            token has expired (`api_token_expired`,
            ApiConsumerSessionExpiredException).
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope produced by JsonApiResponseFactory for every
                  non-2xx response.
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - status
                      - message
                      - errors
                    properties:
                      status:
                        type: integer
                        description: HTTP status code, repeated in the body
                        example: 422
                      message:
                        type: string
                        description: >-
                          Error message. For domain and authentication errors it
                          is a stable error code; for request validation errors
                          it is `Unprocessable entity`.
                        example: employee_not_adjustable
                      errors:
                        description: >-
                          For domain and authentication errors, a stable error
                          code (string) to branch on. For request validation
                          errors, an object keyed by field name whose value is
                          the list of messages for that field (translated into
                          the request locale).
                        oneOf:
                          - type: string
                            example: employee_not_adjustable
                          - type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                            example:
                              employeeId:
                                - validator.invalid_uuid
              examples:
                unauthorized:
                  summary: Missing, unknown or disabled token
                  value:
                    error:
                      status: 401
                      message: Unauthorized
                      errors: unauthorized
                api_token_expired:
                  summary: Expired API token
                  value:
                    error:
                      status: 401
                      message: api_token_expired
                      errors: api_token_expired
        '402':
          description: >-
            Payment Required - The subscription of the company of the token is
            cancelled (SubscriptionPseudoCancelledException).
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope produced by JsonApiResponseFactory for every
                  non-2xx response.
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - status
                      - message
                      - errors
                    properties:
                      status:
                        type: integer
                        description: HTTP status code, repeated in the body
                        example: 422
                      message:
                        type: string
                        description: >-
                          Error message. For domain and authentication errors it
                          is a stable error code; for request validation errors
                          it is `Unprocessable entity`.
                        example: employee_not_adjustable
                      errors:
                        description: >-
                          For domain and authentication errors, a stable error
                          code (string) to branch on. For request validation
                          errors, an object keyed by field name whose value is
                          the list of messages for that field (translated into
                          the request locale).
                        oneOf:
                          - type: string
                            example: employee_not_adjustable
                          - type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                            example:
                              employeeId:
                                - validator.invalid_uuid
              examples:
                subscription_expired:
                  summary: Cancelled subscription
                  value:
                    error:
                      status: 402
                      message: subscription_expired
                      errors: subscription_expired
        '403':
          description: >-
            Forbidden - The token is not an API consumer token, the company has
            no access to the Public API, or the API consumer has no role over
            the affected entity (ForbiddenAccessPermissionException, raised by
            VerifyPublicAPIAddonIsEnabledMiddleware or by the permission check
            of the command / query).
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope produced by JsonApiResponseFactory for every
                  non-2xx response.
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - status
                      - message
                      - errors
                    properties:
                      status:
                        type: integer
                        description: HTTP status code, repeated in the body
                        example: 422
                      message:
                        type: string
                        description: >-
                          Error message. For domain and authentication errors it
                          is a stable error code; for request validation errors
                          it is `Unprocessable entity`.
                        example: employee_not_adjustable
                      errors:
                        description: >-
                          For domain and authentication errors, a stable error
                          code (string) to branch on. For request validation
                          errors, an object keyed by field name whose value is
                          the list of messages for that field (translated into
                          the request locale).
                        oneOf:
                          - type: string
                            example: employee_not_adjustable
                          - type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                            example:
                              employeeId:
                                - validator.invalid_uuid
              examples:
                forbidden_access_permission:
                  summary: No access
                  value:
                    error:
                      status: 403
                      message: Forbidden Access Permission
                      errors: forbidden_access_permission
        '422':
          description: >-
            Unprocessable Entity - Either the path or query string failed
            validation (FindEmployeeBalanceForApiValidator, shared with `GET
            /overtime-policies/v1/employees/{employeeId}/balance`): `employeeId`
            not a UUID (`validator.invalid_uuid`); `from` or `to` missing or
            blank (`validator.not_null`, `validator.not_blank`) or not a Y-m-d
            date (`validator.invalid_type`); `from` after `to`, reported on
            `from` (`validator.invalid_date`). `message` is `Unprocessable
            entity` and `errors` is an object keyed by field. The field messages
            listed are translation keys: the response carries their text in the
            request locale (the key itself when there is no translation), so
            branch on the field name, not on the message. Or
            `employee_not_adjustable`: the employee does not belong to the
            company of the token (EmployeeNotAdjustableException,
            EmployeeAdjustabilityGuard::assertReadable).
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope produced by JsonApiResponseFactory for every
                  non-2xx response.
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - status
                      - message
                      - errors
                    properties:
                      status:
                        type: integer
                        description: HTTP status code, repeated in the body
                        example: 422
                      message:
                        type: string
                        description: >-
                          Error message. For domain and authentication errors it
                          is a stable error code; for request validation errors
                          it is `Unprocessable entity`.
                        example: employee_not_adjustable
                      errors:
                        description: >-
                          For domain and authentication errors, a stable error
                          code (string) to branch on. For request validation
                          errors, an object keyed by field name whose value is
                          the list of messages for that field (translated into
                          the request locale).
                        oneOf:
                          - type: string
                            example: employee_not_adjustable
                          - type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                            example:
                              employeeId:
                                - validator.invalid_uuid
              examples:
                missing_dates:
                  summary: '`from`/`to` missing'
                  value:
                    error:
                      status: 422
                      message: Unprocessable entity
                      errors:
                        from:
                          - validator.not_null
                          - validator.not_blank
                        to:
                          - validator.not_null
                          - validator.not_blank
                from_after_to:
                  summary: '`from` after `to`'
                  value:
                    error:
                      status: 422
                      message: Unprocessable entity
                      errors:
                        from:
                          - validator.invalid_date
                employee_not_adjustable:
                  summary: Employee not in the company of the token
                  value:
                    error:
                      status: 422
                      message: employee_not_adjustable
                      errors: employee_not_adjustable
        '429':
          description: >-
            Too Many Requests - The company of the token exceeded the API
            consumer call limit (1000 calls per minute)
            (ApiConsumerSessionCallMaxExceededException).
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope produced by JsonApiResponseFactory for every
                  non-2xx response.
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - status
                      - message
                      - errors
                    properties:
                      status:
                        type: integer
                        description: HTTP status code, repeated in the body
                        example: 422
                      message:
                        type: string
                        description: >-
                          Error message. For domain and authentication errors it
                          is a stable error code; for request validation errors
                          it is `Unprocessable entity`.
                        example: employee_not_adjustable
                      errors:
                        description: >-
                          For domain and authentication errors, a stable error
                          code (string) to branch on. For request validation
                          errors, an object keyed by field name whose value is
                          the list of messages for that field (translated into
                          the request locale).
                        oneOf:
                          - type: string
                            example: employee_not_adjustable
                          - type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                            example:
                              employeeId:
                                - validator.invalid_uuid
              examples:
                api_consumer_rate_limit_exceeded:
                  summary: Rate limit exceeded
                  value:
                    error:
                      status: 429
                      message: Api consumer rate limit exceeded
                      errors: api_consumer_rate_limit_exceeded
      security:
        - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.