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

# Change a request

> Change the reason, the period or the leave type of a request on behalf of the user who created the API token.

Pending requests are changed in place: a new period or leave type restarts the approval, a reason change never does. Approved requests keep their approved version until a change is decided:

- A new period inside the old one (shortening, same leave type) is applied at once and the days go back to the allowance, unless the leave type turns on `request_shortening_needs_approval`.
- A longer or moved period, or a new leave type, creates a change request with status `pending`. The approved request stays in force everywhere (calendar, allowance, syncs) until the approvers approve it. Declining leaves it untouched. One change can be open per request: a new period or leave type withdraws the open one.
- A reason change is applied at once and never needs approval.
- Leave types without approval, and changes by admins or managers (`admin_approval_option: approve_request_immediately`), apply at once. For a new leave type, the new one decides whether approval is needed.

The leave type must allow changes (`allow_request_changes`), and so must a new one; if one does not, the call is rejected with 403, like a request that has already started or that the caller may not change. A non-admin passing `admin_approval_option: approve_request_immediately` gets 403 too.

A new leave type must be day-based or hour-based like the request: days and half days can be swapped for each other, and so can hours and minute units. Switching between the two is rejected with 400; cancel the request and create a new one instead.

In a recurring series, the dates of a single approved occurrence can be changed, and only that occurrence changes. The dates of an occurrence that still waits for approval and the leave type of any occurrence can't be changed (400).

Send `start` and `end` together to change the period, and `leave_type_id` to change the leave type. Send `reason` to change the reason, or `null` to clear it. The response is the recorded change: its `status` is `applied` when it is in force and `pending` when it waits for approval (also shown as `pending_change` on the request). Approvers decide it with the `/requests/{id}/changes/{changeId}/approve` and `/decline` endpoints; the requester can `/withdraw` it.



## OpenAPI

````yaml https://api.absentify.com/api/v1/openapi.json post /requests/{id}/changes
openapi: 3.1.0
info:
  title: absentify CRUD API
  description: OpenAPI compliant REST API
  version: 1.0.0
servers:
  - url: https://api.absentify.com/api/v1
security: []
tags:
  - name: Departments
  - name: Leave types
  - name: Members
  - name: Requests
  - name: Public holidays
  - name: Workspace
  - name: Absences
  - name: Allowance Management
  - name: Overtime
  - name: Out of office
  - name: Exports
externalDocs:
  url: https://absentify.com/docs/en/api-reference
paths:
  /requests/{id}/changes:
    post:
      tags:
        - Requests
      summary: Change a request
      description: >-
        Change the reason, the period or the leave type of a request on behalf
        of the user who created the API token.


        Pending requests are changed in place: a new period or leave type
        restarts the approval, a reason change never does. Approved requests
        keep their approved version until a change is decided:


        - A new period inside the old one (shortening, same leave type) is
        applied at once and the days go back to the allowance, unless the leave
        type turns on `request_shortening_needs_approval`.

        - A longer or moved period, or a new leave type, creates a change
        request with status `pending`. The approved request stays in force
        everywhere (calendar, allowance, syncs) until the approvers approve it.
        Declining leaves it untouched. One change can be open per request: a new
        period or leave type withdraws the open one.

        - A reason change is applied at once and never needs approval.

        - Leave types without approval, and changes by admins or managers
        (`admin_approval_option: approve_request_immediately`), apply at once.
        For a new leave type, the new one decides whether approval is needed.


        The leave type must allow changes (`allow_request_changes`), and so must
        a new one; if one does not, the call is rejected with 403, like a
        request that has already started or that the caller may not change. A
        non-admin passing `admin_approval_option: approve_request_immediately`
        gets 403 too.


        A new leave type must be day-based or hour-based like the request: days
        and half days can be swapped for each other, and so can hours and minute
        units. Switching between the two is rejected with 400; cancel the
        request and create a new one instead.


        In a recurring series, the dates of a single approved occurrence can be
        changed, and only that occurrence changes. The dates of an occurrence
        that still waits for approval and the leave type of any occurrence can't
        be changed (400).


        Send `start` and `end` together to change the period, and
        `leave_type_id` to change the leave type. Send `reason` to change the
        reason, or `null` to clear it. The response is the recorded change: its
        `status` is `applied` when it is in force and `pending` when it waits
        for approval (also shown as `pending_change` on the request). Approvers
        decide it with the `/requests/{id}/changes/{changeId}/approve` and
        `/decline` endpoints; the requester can `/withdraw` it.
      operationId: request-changeRequest
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type:
                    - string
                    - 'null'
                start:
                  description: >-
                    Start/end of the request in ISO 8601. For day-based leave
                    types (`leave_unit: days`) send the date at midnight UTC
                    (e.g. `2026-06-01T00:00:00Z`) and use `start_at` / `end_at`
                    to set half-days. For hour-based leave types include the
                    exact time of day (e.g. `2026-06-01T09:00:00Z`); `start_at`
                    / `end_at` are then ignored.
                  type: string
                end:
                  description: >-
                    Start/end of the request in ISO 8601. For day-based leave
                    types (`leave_unit: days`) send the date at midnight UTC
                    (e.g. `2026-06-01T00:00:00Z`) and use `start_at` / `end_at`
                    to set half-days. For hour-based leave types include the
                    exact time of day (e.g. `2026-06-01T09:00:00Z`); `start_at`
                    / `end_at` are then ignored.
                  type: string
                start_at:
                  type: string
                  enum:
                    - morning
                    - afternoon
                  description: >-
                    For day-based leave types: whether the absence starts in the
                    `morning` (the whole first day counts) or `afternoon` (only
                    the second half of the first day). Ignored for hour-based
                    leave types.
                end_at:
                  type: string
                  enum:
                    - lunchtime
                    - end_of_day
                  description: >-
                    For day-based leave types: whether the absence ends at
                    `lunchtime` (only the first half of the last day) or
                    `end_of_day` (the whole last day counts). Ignored for
                    hour-based leave types.
                leave_type_id:
                  description: >-
                    The new leave type, which must allow changes and be
                    day-based or hour-based like the request.
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                admin_approval_option:
                  description: >-
                    Whether the change is applied at once (admins only) or goes
                    through the normal approval process.
                  type: string
                  enum:
                    - approve_request_immediately
                    - go_through_the_normal_approval_process
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  revision:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                    description: >-
                      The revision the request gets when this change is applied.
                      Null while the change is pending, declined or withdrawn.
                  kind:
                    type: string
                    enum:
                      - reason
                      - shortened
                      - extended
                      - moved
                      - leave_type
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - declined
                      - withdrawn
                      - applied
                    description: >-
                      `pending` waits for approvers, `applied` is in force,
                      `declined` and `withdrawn` never changed the request.
                  previous:
                    type: object
                    properties:
                      start:
                        type: string
                      end:
                        type: string
                      start_at:
                        type: string
                        enum:
                          - morning
                          - afternoon
                        description: >-
                          For day-based leave types: whether the absence starts
                          in the `morning` (the whole first day counts) or
                          `afternoon` (only the second half of the first day).
                          Ignored for hour-based leave types.
                      end_at:
                        type: string
                        enum:
                          - lunchtime
                          - end_of_day
                        description: >-
                          For day-based leave types: whether the absence ends at
                          `lunchtime` (only the first half of the last day) or
                          `end_of_day` (the whole last day counts). Ignored for
                          hour-based leave types.
                      leave_type:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - name
                        additionalProperties: false
                      duration:
                        type: number
                        description: >-
                          Calendar duration, including non-working days and
                          non-working time: calendar days for day and half-day
                          leave units, elapsed minutes from start to end for
                          hour and minute units. Use `workday_absence_duration`
                          for the counted duration.
                      workday_absence_duration:
                        type: number
                        description: >-
                          Counted duration, the value absentify shows: the
                          working time the absence takes, based on the work
                          schedule and public holidays, unless the leave type
                          also counts days off or public holidays. Days for day
                          and half-day leave units, minutes for hour and minute
                          units. If the leave type deducts from an allowance,
                          this is the amount the absence takes from it, or for a
                          proposed change, would take once the change applies.
                          Canceled and declined requests keep the value but take
                          nothing from the allowance.
                      reason:
                        type:
                          - string
                          - 'null'
                    required:
                      - start
                      - end
                      - start_at
                      - end_at
                      - leave_type
                      - duration
                      - workday_absence_duration
                      - reason
                    additionalProperties: false
                    description: The request as it was before this change.
                  proposed:
                    type: object
                    properties:
                      start:
                        type: string
                      end:
                        type: string
                      start_at:
                        type: string
                        enum:
                          - morning
                          - afternoon
                        description: >-
                          For day-based leave types: whether the absence starts
                          in the `morning` (the whole first day counts) or
                          `afternoon` (only the second half of the first day).
                          Ignored for hour-based leave types.
                      end_at:
                        type: string
                        enum:
                          - lunchtime
                          - end_of_day
                        description: >-
                          For day-based leave types: whether the absence ends at
                          `lunchtime` (only the first half of the last day) or
                          `end_of_day` (the whole last day counts). Ignored for
                          hour-based leave types.
                      leave_type:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - name
                        additionalProperties: false
                      duration:
                        type: number
                        description: >-
                          Calendar duration, including non-working days and
                          non-working time: calendar days for day and half-day
                          leave units, elapsed minutes from start to end for
                          hour and minute units. Use `workday_absence_duration`
                          for the counted duration.
                      workday_absence_duration:
                        type: number
                        description: >-
                          Counted duration, the value absentify shows: the
                          working time the absence takes, based on the work
                          schedule and public holidays, unless the leave type
                          also counts days off or public holidays. Days for day
                          and half-day leave units, minutes for hour and minute
                          units. If the leave type deducts from an allowance,
                          this is the amount the absence takes from it, or for a
                          proposed change, would take once the change applies.
                          Canceled and declined requests keep the value but take
                          nothing from the allowance.
                      reason:
                        type:
                          - string
                          - 'null'
                    required:
                      - start
                      - end
                      - start_at
                      - end_at
                      - leave_type
                      - duration
                      - workday_absence_duration
                      - reason
                    additionalProperties: false
                    description: >-
                      The request as this change wants it. Only for `applied`
                      changes is this what is in force.
                  changed_by:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - name
                        additionalProperties: false
                      - type: 'null'
                  decided_by:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          name:
                            type:
                              - string
                              - 'null'
                        required:
                          - id
                          - name
                        additionalProperties: false
                      - type: 'null'
                  created_at:
                    type: string
                  decided_at:
                    type:
                      - string
                      - 'null'
                  decision_reason:
                    type:
                      - string
                      - 'null'
                required:
                  - id
                  - revision
                  - kind
                  - status
                  - previous
                  - proposed
                  - changed_by
                  - decided_by
                  - created_at
                  - decided_at
                  - decision_reason
                additionalProperties: false
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      security:
        - ApiKey: []
components:
  schemas:
    error.BAD_REQUEST:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Invalid input data
        code:
          type: string
          description: The error code
          example: BAD_REQUEST
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
      title: Invalid input data error (400)
      description: The error information
      example:
        code: BAD_REQUEST
        message: Invalid input data
        issues: []
    error.UNAUTHORIZED:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Authorization not provided
        code:
          type: string
          description: The error code
          example: UNAUTHORIZED
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
      title: Authorization not provided error (401)
      description: The error information
      example:
        code: UNAUTHORIZED
        message: Authorization not provided
        issues: []
    error.FORBIDDEN:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Insufficient access
        code:
          type: string
          description: The error code
          example: FORBIDDEN
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
      title: Insufficient access error (403)
      description: The error information
      example:
        code: FORBIDDEN
        message: Insufficient access
        issues: []
    error.INTERNAL_SERVER_ERROR:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Internal server error
        code:
          type: string
          description: The error code
          example: INTERNAL_SERVER_ERROR
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
      title: Internal server error error (500)
      description: The error information
      example:
        code: INTERNAL_SERVER_ERROR
        message: Internal server error
        issues: []
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````

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