> ## 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.

# Compensate overtime of an employee with rest

> Compensates overtime of one employee of the company of the token with rest, over the `from`-`to` period, crediting it to an hours compensation absence type available for the employee. The employee must belong to the company of the token and have overtime balance rows in that period. The compensation is spread across every overtime policy of the employee in the period. The employee is notified as when the compensation is made from the app.

Optimistic concurrency: `balanceBeforeSeconds` must equal the current balance of the resolved source, as returned by `GET /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance` for the same `from`/`to` (key `positive_balance` for source `positive_balance`, `negative_balance` for `negative_balance`, `total_balance` otherwise), which is not the balance `GET /overtime-policies/v1/employees/{employeeId}/balance` returns. Otherwise the request is rejected with 409 `compensable_balance_changed`.



## OpenAPI

````yaml POST /overtime-policies/v1/compensations/rest
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/compensations/rest:
    post:
      tags:
        - Overtime Policies
      summary: Compensate overtime of an employee with rest
      description: >-
        Compensates overtime of one employee of the company of the token with
        rest, over the `from`-`to` period, crediting it to an hours compensation
        absence type available for the employee. The employee must belong to the
        company of the token and have overtime balance rows in that period. The
        compensation is spread across every overtime policy of the employee in
        the period. The employee is notified as when the compensation is made
        from the app.


        Optimistic concurrency: `balanceBeforeSeconds` must equal the current
        balance of the resolved source, as returned by `GET
        /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance`
        for the same `from`/`to` (key `positive_balance` for source
        `positive_balance`, `negative_balance` for `negative_balance`,
        `total_balance` otherwise), which is not the balance `GET
        /overtime-policies/v1/employees/{employeeId}/balance` returns. Otherwise
        the request is rejected with 409 `compensable_balance_changed`.
      operationId: CreateOvertimeRestCompensation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - employeeId
                - absenceTypeId
                - from
                - to
                - balanceBeforeSeconds
              properties:
                employeeId:
                  type: string
                  format: uuid
                  description: >-
                    Employee whose overtime is compensated with rest. Must
                    belong to the company of the token.
                absenceTypeId:
                  type: string
                  format: uuid
                  description: >-
                    Hours compensation absence type the rest is credited to.
                    Must be available for the employee (see `GET
                    /schedule/v1/employees/available-hours-compensation-types`).
                from:
                  type: string
                  format: date
                  description: >-
                    First day of the period (Y-m-d). Must not be after `to` (422
                    validation on `from`: `validator.invalid_date`).
                  example: '2026-10-01'
                to:
                  type: string
                  format: date
                  description: Last day of the period (Y-m-d), inclusive.
                  example: '2026-10-31'
                balanceBeforeSeconds:
                  type: integer
                  description: >-
                    Balance the client read before compensating, in seconds, for
                    the resolved source and the same `from`/`to` (see the
                    concurrency note above).
                  example: 114750
                amountSeconds:
                  type: integer
                  description: >-
                    Seconds to compensate. Required unless `compensateAll` is
                    `true`: when it is omitted or not greater than zero the
                    request is rejected with 422
                    `insufficient_compensable_balance`.
                  example: 1200
                compensateAll:
                  type: boolean
                  default: false
                  description: >-
                    When `true`, compensates the whole compensable balance of
                    the period and `amountSeconds` is not needed.
                source:
                  type: string
                  enum:
                    - total_balance
                    - positive_balance
                    - negative_balance
                  description: >-
                    Balance the compensation draws from. Optional: when omitted
                    it defaults to `total_balance`, except when the policy of
                    the employee is hybrid with separated positive/negative
                    balances, where it is mandatory (422
                    `hybrid_independent_policy_required`). Any other value,
                    including the rule sources `multiplier_rule` and
                    `typifying_rule` (the public API does not expose rule
                    compensation), is rejected with 422 validation on `source`
                    (`validator.invalid_choice`).
                note:
                  type: string
                  nullable: true
                  description: >-
                    Free text stored with the compensation and shown in its
                    history
            examples:
              amount:
                summary: Compensate 20 minutes of positive balance
                value:
                  employeeId: 550e8400-e29b-41d4-a716-446655440000
                  absenceTypeId: 199932f8-c295-42b9-8588-b5ec181a3767
                  source: positive_balance
                  from: '2026-10-01'
                  to: '2026-10-31'
                  balanceBeforeSeconds: 114750
                  amountSeconds: 1200
                  note: Ajuste de prueba
              all:
                summary: Compensate the whole balance
                value:
                  employeeId: 550e8400-e29b-41d4-a716-446655440000
                  absenceTypeId: 199932f8-c295-42b9-8588-b5ec181a3767
                  from: '2026-10-01'
                  to: '2026-10-31'
                  balanceBeforeSeconds: 114750
                  compensateAll: true
      responses:
        '200':
          description: >-
            Rest compensation created. The status is 200 (not 201) because the
            controller answers through `fromRawData`; `meta` is the default
            single-object meta.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: object
                    required:
                      - compensationId
                      - employeeId
                      - absenceTypeId
                      - appliedSeconds
                      - balanceBeforeSeconds
                      - balanceAfterSeconds
                    properties:
                      compensationId:
                        type: string
                        format: uuid
                        description: ID of the created rest compensation movement
                        example: 3f2b8c1e-6a0d-4c4e-9b7a-2d1f0e5c9a11
                      employeeId:
                        type: string
                        format: uuid
                        description: The compensated employee
                      absenceTypeId:
                        type: string
                        format: uuid
                        description: >-
                          Hours compensation absence type the rest was credited
                          to
                      appliedSeconds:
                        type: integer
                        minimum: 0
                        description: Seconds actually compensated
                        example: 1200
                      balanceBeforeSeconds:
                        type: integer
                        description: Echo of the `balanceBeforeSeconds` sent in the request
                        example: 114750
                      balanceAfterSeconds:
                        type: integer
                        description: >-
                          `balanceBeforeSeconds - appliedSeconds`. Balances are
                          magnitudes (positive numbers) for every source, as
                          returned by `GET
                          /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance`,
                          so compensating always reduces the balance it draws
                          from.
                        example: 113550
                  meta:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                        example: 1
                      lastPage:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      perPage:
                        type: integer
                        example: 1
              example:
                data:
                  compensationId: 3f2b8c1e-6a0d-4c4e-9b7a-2d1f0e5c9a11
                  employeeId: 550e8400-e29b-41d4-a716-446655440000
                  absenceTypeId: 199932f8-c295-42b9-8588-b5ec181a3767
                  appliedSeconds: 1200
                  balanceBeforeSeconds: 114750
                  balanceAfterSeconds: 113550
                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
        '409':
          description: >-
            Conflict - `balanceBeforeSeconds` does not match the current balance
            of the resolved source for the period, i.e. the balance changed
            since the client read it (CompensableBalanceChangedException).
            Re-read `GET
            /overtime-policies/v1/employees/{employeeId}/rest-compensable-balance`
            and retry with the new value. Replaying the same request after a
            successful compensation is rejected, so the compensation is never
            duplicated: with this 409, or with 422
            `insufficient_compensable_balance` when the remaining balance no
            longer covers the amount (always the case when replaying
            `compensateAll`).
          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
              example:
                error:
                  status: 409
                  message: compensable_balance_changed
                  errors: compensable_balance_changed
        '422':
          description: >-
            Unprocessable Entity - Either the body failed validation
            (CreateRestCompensationForApiValidator: `message` is `Unprocessable
            entity` and `errors` is an object keyed by field), or a domain rule
            rejected the request (`errors` is the error code).


            Validation (`errors` 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.


            - `employeeId` or `absenceTypeId` missing or not a UUID
            (`validator.not_null`, `validator.invalid_uuid`).

            - `balanceBeforeSeconds` missing (`validator.not_null`).

            - `source` not `total_balance`, `positive_balance` or
            `negative_balance` (`validator.invalid_choice`).

            - `from`/`to` missing or not a Y-m-d date; `from` after `to`,
            reported on `from` (`validator.invalid_date`).


            Domain (`errors` is the code):


            - `employee_not_adjustable` - The employee does not belong to the
            company of the token or has no overtime balance in the period
            (EmployeeNotAdjustableException).

            - `hybrid_independent_policy_required` - `source` was omitted and
            the policy of the employee is hybrid with separated
            positive/negative balances, so the source must be explicit
            (HybridIndependentPolicyRequiredException).

            - `compensation_distribution_configuration_not_found` - The overtime
            policy of the employee has no compensation distribution
            configuration
            (CompensationDistributionConfigurationNotFoundException).

            - `hours_compensation_absence_type_not_available` - `absenceTypeId`
            is not an hours compensation absence type available for the
            employee: not assigned, inactive, deleted, of another category or of
            another company (HoursCompensationAbsenceTypeNotAvailableException).
            Use `GET /schedule/v1/employees/available-hours-compensation-types`
            to list the valid ones.

            - `hours_compensation_absence_types_unavailable` - The availability
            of the absence type could not be checked; retry later
            (HoursCompensationAbsenceTypesUnavailableException).

            - `unsupported_movement_source` - `negative_balance` was requested
            on a policy that does not support compensating the negative balance
            (UnsupportedMovementSourceException).

            - `insufficient_compensable_balance` - `amountSeconds` is omitted
            without `compensateAll`, is not greater than zero, or exceeds the
            compensable balance of the period. Checked before the concurrency
            check, so it wins over 409 when both apply
            (InsufficientCompensableBalanceException).

            - `compensation_limit_exceeded` - The compensation exceeds the
            annual rest compensation limit of the policy and the policy does not
            allow going beyond it (CompensationLimitExceededException).
          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:
                validation:
                  summary: Body validation failed
                  value:
                    error:
                      status: 422
                      message: Unprocessable entity
                      errors:
                        absenceTypeId:
                          - validator.not_null
                        balanceBeforeSeconds:
                          - validator.not_null
                invalid_source:
                  summary: '`source` not accepted (unknown value or a rule source)'
                  value:
                    error:
                      status: 422
                      message: Unprocessable entity
                      errors:
                        source:
                          - validator.invalid_choice
                from_after_to:
                  summary: '`from` after `to`'
                  value:
                    error:
                      status: 422
                      message: Unprocessable entity
                      errors:
                        from:
                          - validator.invalid_date
                employee_not_adjustable:
                  summary: >-
                    The employee does not belong to the company of the token or
                    has no overtime balance in the period
                  value:
                    error:
                      status: 422
                      message: employee_not_adjustable
                      errors: employee_not_adjustable
                hybrid_independent_policy_required:
                  summary: >-
                    `source` was omitted and the policy of the employee is
                    hybrid with separated positive/negative balances, so the
                    source must be explicit
                  value:
                    error:
                      status: 422
                      message: hybrid_independent_policy_required
                      errors: hybrid_independent_policy_required
                unsupported_movement_source:
                  summary: >-
                    `negative_balance` was requested on a policy that does not
                    support compensating the negative balance
                  value:
                    error:
                      status: 422
                      message: unsupported_movement_source
                      errors: unsupported_movement_source
                hours_compensation_absence_type_not_available:
                  summary: >-
                    `absenceTypeId` is not an hours compensation absence type
                    available for the employee: not assigned, inactive, deleted,
                    of another category or of another company
                  value:
                    error:
                      status: 422
                      message: hours_compensation_absence_type_not_available
                      errors: hours_compensation_absence_type_not_available
                hours_compensation_absence_types_unavailable:
                  summary: >-
                    The availability of the absence type could not be checked;
                    retry later
                  value:
                    error:
                      status: 422
                      message: hours_compensation_absence_types_unavailable
                      errors: hours_compensation_absence_types_unavailable
                insufficient_compensable_balance:
                  summary: >-
                    `amountSeconds` exceeds the compensable balance of the
                    period
                  value:
                    error:
                      status: 422
                      message: insufficient_compensable_balance
                      errors: insufficient_compensable_balance
                compensation_limit_exceeded:
                  summary: >-
                    The compensation exceeds the annual rest compensation limit
                    of the policy and the policy does not allow going beyond it
                  value:
                    error:
                      status: 422
                      message: compensation_limit_exceeded
                      errors: compensation_limit_exceeded
                compensation_distribution_configuration_not_found:
                  summary: >-
                    The overtime policy of the employee has no compensation
                    distribution configuration
                  value:
                    error:
                      status: 422
                      message: compensation_distribution_configuration_not_found
                      errors: compensation_distribution_configuration_not_found
        '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.