> ## 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. # Adjust the overtime balance of an employee > Adds time to, subtracts time from, or resets the overtime balance of one employee of the company of the token, over the `from`-`to` period. The employee must belong to the company of the token and have overtime balance rows in that period. Optimistic concurrency: for `add` and `subtract`, `balanceBeforeSeconds` must equal the current balance of the resolved source, as returned by `GET /overtime-policies/v1/employees/{employeeId}/balance` for the same `from`/`to` (key `positive_balance` for source `positive_balance`, `negative_balance` for `negative_balance`, `total_balance` for any other source). Otherwise the request is rejected with 409 `compensable_balance_changed`. `reset` brings the positive and negative balances of the period to zero: `source` is ignored (the movement is recorded with source `total_balance`), `amountSeconds` is ignored and `balanceBeforeSeconds` is optional and not checked. When nothing can be applied (amount omitted or not greater than zero, or nothing to allocate) the call still answers 200 with `appliedSeconds: 0` and an empty `adjustmentId`, and no movement is created. ## OpenAPI ````yaml POST /overtime-policies/v1/adjustments 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/adjustments: post: tags: - Overtime Policies summary: Adjust the overtime balance of an employee description: >- Adds time to, subtracts time from, or resets the overtime balance of one employee of the company of the token, over the `from`-`to` period. The employee must belong to the company of the token and have overtime balance rows in that period. Optimistic concurrency: for `add` and `subtract`, `balanceBeforeSeconds` must equal the current balance of the resolved source, as returned by `GET /overtime-policies/v1/employees/{employeeId}/balance` for the same `from`/`to` (key `positive_balance` for source `positive_balance`, `negative_balance` for `negative_balance`, `total_balance` for any other source). Otherwise the request is rejected with 409 `compensable_balance_changed`. `reset` brings the positive and negative balances of the period to zero: `source` is ignored (the movement is recorded with source `total_balance`), `amountSeconds` is ignored and `balanceBeforeSeconds` is optional and not checked. When nothing can be applied (amount omitted or not greater than zero, or nothing to allocate) the call still answers 200 with `appliedSeconds: 0` and an empty `adjustmentId`, and no movement is created. operationId: CreateOvertimeBalanceAdjustment requestBody: required: true content: application/json: schema: type: object required: - employeeId - operation - from - to oneOf: - title: add or subtract required: - balanceBeforeSeconds properties: operation: type: string enum: - add - subtract - title: reset properties: operation: type: string enum: - reset properties: employeeId: type: string format: uuid description: >- Employee whose balance is adjusted. Must belong to the company of the token. operation: type: string enum: - add - subtract - reset description: >- Adjustment operation. The validator only checks it is a non-blank string; an unknown value is rejected with 422 `invalid_adjustment_operation`. from: type: string format: date description: First day of the period (Y-m-d). Must not be after `to`. example: '2026-01-01' to: type: string format: date description: >- Last day of the period (Y-m-d), inclusive. It can be equal to `from`. example: '2026-01-31' balanceBeforeSeconds: type: integer description: >- Balance the client read before adjusting, in seconds. Required unless `operation` is `reset` (then optional and not checked). See the concurrency note above. example: 7200 amountSeconds: type: integer description: >- Seconds to add or subtract. Optional in the validator, but when omitted (or not greater than zero) on `add`/`subtract` nothing is applied. Ignored on `reset`. example: 3600 source: type: string enum: - total_balance - positive_balance - negative_balance - multiplier_rule - typifying_rule description: >- Balance the adjustment applies to. 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`). Ignored on `reset`. Any value outside the enum is rejected with 422 `invalid_movement_source`. note: type: string nullable: true description: >- Free text stored with the adjustment and shown in its history examples: add: summary: Add one hour to the total balance value: employeeId: 550e8400-e29b-41d4-a716-446655440000 operation: add from: '2026-01-01' to: '2026-01-31' balanceBeforeSeconds: 7200 amountSeconds: 3600 note: Correction after audit subtract_positive: summary: Subtract 30 minutes from the positive balance value: employeeId: 550e8400-e29b-41d4-a716-446655440000 operation: subtract source: positive_balance from: '2026-01-01' to: '2026-01-31' balanceBeforeSeconds: 5400 amountSeconds: 1800 reset: summary: Reset the balance of the period value: employeeId: 550e8400-e29b-41d4-a716-446655440000 operation: reset from: '2026-01-01' to: '2026-01-31' responses: '200': description: >- Adjustment processed. 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: - adjustmentId - employeeId - operation - appliedSeconds - balanceBeforeSeconds - balanceAfterSeconds properties: adjustmentId: type: string description: >- ID of the created adjustment movement (UUID). Empty string when nothing was applied (see `appliedSeconds`). example: 3f2b8c1e-6a0d-4c4e-9b7a-2d1f0e5c9a11 employeeId: type: string format: uuid description: The adjusted employee operation: type: string enum: - add - subtract - reset description: The operation sent in the request appliedSeconds: type: integer minimum: 0 description: >- Seconds actually applied. `0` when the adjustment was a no-op (amount omitted or not greater than zero, or no day of the period to allocate it to); in that case no movement is created. example: 3600 balanceBeforeSeconds: type: integer description: >- Echo of the `balanceBeforeSeconds` sent in the request (`0` when it was omitted on a `reset`). example: 7200 balanceAfterSeconds: type: integer description: >- `add`: balanceBeforeSeconds + appliedSeconds. `subtract`: balanceBeforeSeconds - appliedSeconds. `reset`: always `0`. example: 10800 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: adjustmentId: 3f2b8c1e-6a0d-4c4e-9b7a-2d1f0e5c9a11 employeeId: 550e8400-e29b-41d4-a716-446655440000 operation: add appliedSeconds: 3600 balanceBeforeSeconds: 7200 balanceAfterSeconds: 10800 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 '404': description: >- Not Found - The employee does not belong to the company of the token, or has no overtime balance rows in the `from`-`to` period (EmployeeNotAdjustableException, raised by EmployeeAdjustabilityGuard::assertAdjustable). 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: employee_not_adjustable: summary: Employee not adjustable in the period value: error: status: 404 message: employee_not_adjustable errors: employee_not_adjustable '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). Not raised for `reset`. Re-read `GET /overtime-policies/v1/employees/{employeeId}/balance` and retry with the fresh value. 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: compensable_balance_changed: summary: Stale balanceBeforeSeconds value: error: status: 409 message: compensable_balance_changed errors: compensable_balance_changed '422': description: >- Unprocessable Entity - Either the body failed validation (CreateBalanceAdjustmentForApiValidator: `message` is `Unprocessable entity` and `errors` is an object keyed by field), or a domain rule rejected the request (`errors` is the error code): - `invalid_period` - `from` is after `to` (InvalidPeriodException, OPC InvalidPeriodExceptionResolver). - `invalid_adjustment_operation` - `operation` is not `add`, `subtract` or `reset` (InvalidAdjustmentOperationException). - `invalid_movement_source` - `source` is not one of the accepted values (InvalidMovementSourceException). - `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, AdjustmentSourceResolver). - `compensation_distribution_configuration_not_found` - the overtime policy of the employee has no compensation distribution configuration; only reachable when `source` is resolved, i.e. not on `reset` (CompensationDistributionConfigurationNotFoundException). 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: employeeId: - validator.invalid_uuid balanceBeforeSeconds: - validator.not_null invalid_period: summary: '`from` after `to`' value: error: status: 422 message: invalid_period errors: invalid_period invalid_adjustment_operation: summary: Unknown operation value: error: status: 422 message: invalid_adjustment_operation errors: invalid_adjustment_operation invalid_movement_source: summary: Unknown source value: error: status: 422 message: invalid_movement_source errors: invalid_movement_source hybrid_independent_policy_required: summary: Source required for a hybrid policy with separated balances value: error: status: 422 message: hybrid_independent_policy_required errors: hybrid_independent_policy_required compensation_distribution_configuration_not_found: summary: Policy without 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.