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

# Request time-off

> Creates a request and notifies the approvers, or approves it straight away when the policy needs no approval. Rejected when it would take the balance below zero, overlaps another request, misses the policy's notice period, or falls outside the dates the employee may book — call `GET /time-off/preview` first to see the days and balance. `attachments` is optional: images and PDFs, 4 MB in total, sent as `multipart/form-data` with one `attachments[]` part per file. Defaults to the caller; `employee_id` requests for someone else and needs the admin role or being their approver. Requires the `time-off:write` scope.



## OpenAPI

````yaml /openapi.json post /time-off/requests
openapi: 3.1.1
info:
  title: A-Char API
  version: 1.0.0
  description: 'Authenticate with `Authorization: Bearer <api key>`.'
servers:
  - url: https://a-char.com/api/v1
security:
  - bearerAuth: []
paths:
  /time-off/requests:
    post:
      tags:
        - Time off requests
      summary: Request time-off
      description: >-
        Creates a request and notifies the approvers, or approves it straight
        away when the policy needs no approval. Rejected when it would take the
        balance below zero, overlaps another request, misses the policy's notice
        period, or falls outside the dates the employee may book — call `GET
        /time-off/preview` first to see the days and balance. `attachments` is
        optional: images and PDFs, 4 MB in total, sent as `multipart/form-data`
        with one `attachments[]` part per file. Defaults to the caller;
        `employee_id` requests for someone else and needs the admin role or
        being their approver. Requires the `time-off:write` scope.
      operationId: timeOff.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  format: date
                start_date_type:
                  enum:
                    - FULL_DAY
                    - AM
                    - PM
                  type: string
                  default: FULL_DAY
                end_date:
                  type: string
                  format: date
                end_date_type:
                  enum:
                    - FULL_DAY
                    - AM
                    - PM
                  type: string
                  default: FULL_DAY
                note:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
                policy_id:
                  type: string
                  format: uuid
                employee_id:
                  type: string
                  format: uuid
                attachments:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    contentMediaType: '*/*'
                  default: []
              required:
                - start_date
                - end_date
                - policy_id
          multipart/form-data:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  format: date
                start_date_type:
                  enum:
                    - FULL_DAY
                    - AM
                    - PM
                  type: string
                  default: FULL_DAY
                end_date:
                  type: string
                  format: date
                end_date_type:
                  enum:
                    - FULL_DAY
                    - AM
                    - PM
                  type: string
                  default: FULL_DAY
                note:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
                policy_id:
                  type: string
                  format: uuid
                employee_id:
                  type: string
                  format: uuid
                attachments:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    contentMediaType: '*/*'
                  default: []
              required:
                - start_date
                - end_date
                - policy_id
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                required:
                  - id
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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