openapi: 3.0.3
info:
  title: Kenjo API
  description: >-
    The Kenjo API is a documented REST API for the Kenjo all-in-one HR (HRIS)
    platform. It exposes employees, attendance and time tracking, time off /
    absences, company documents, compensation and payroll data, organizational
    structure, and recruiting over HTTPS. Access is gated: the API is available
    on Kenjo's top-tier Connect plan and must first be activated for your account
    (sandbox or production) by the Kenjo Customer Success team. You then generate
    an API key in the Kenjo web app (Settings > Integrations > API), exchange it
    for a bearer token via POST /auth/login, and send that token in the
    Authorization header on every request. A missing, invalid, or expired token
    returns 401 UNAUTHORIZED.

    Paths and HTTP methods in this document reflect Kenjo's published API
    reference (kenjo.readme.io). Request and response bodies are modeled from the
    documented endpoint descriptions where full field-level schemas are not
    published; treat the schema components as representative rather than
    exhaustive, and confirm exact fields against the live reference.
  version: '1.0'
  contact:
    name: Kenjo Support
    url: https://www.kenjo.io/legal/api
    email: support@kenjo.io
servers:
  - url: https://api.kenjo.io/api/v1
    description: Production
  - url: https://sandbox-api.kenjo.io/api/v1
    description: Sandbox (test environment)
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Exchange an API key for a bearer token and invalidate tokens.
  - name: Employees
    description: Employee records and their profile sections.
  - name: Attendance
    description: Attendance and time-tracking entries.
  - name: Time Off
    description: Absences, time-off requests, types, statuses, and balances.
  - name: Documents
    description: Company documents.
  - name: Compensation
    description: Contracts, salaries, and additional payments.
  - name: Organization
    description: Companies, offices, departments, teams, areas, and calendars.
  - name: Recruiting
    description: Positions, candidates, and applications.
paths:
  /auth/login:
    post:
      operationId: login
      tags:
        - Authentication
      summary: Log in an API token
      description: Exchanges a Kenjo API key for a bearer token used to authorize subsequent requests.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: A bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/logout:
    post:
      operationId: logout
      tags:
        - Authentication
      summary: Log out an API token
      description: Invalidates the current bearer token.
      responses:
        '200':
          description: Token invalidated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user-accounts:
    get:
      operationId: listUserAccounts
      tags:
        - Employees
      summary: List user accounts
      description: Returns a list of user accounts in the organization.
      responses:
        '200':
          description: A list of user accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAccountList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees:
    get:
      operationId: listEmployees
      tags:
        - Employees
      summary: List employees
      description: Returns a paginated list of employees.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of employees.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEmployee
      tags:
        - Employees
      summary: Create a new employee
      description: Creates a new employee. New employees are created deactivated by default and can be activated with the activate endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeInput'
      responses:
        '201':
          description: The created employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}:
    get:
      operationId: getEmployee
      tags:
        - Employees
      summary: Get an employee
      description: Returns all sections for a given employee id.
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: The employee with all sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /employees/accounts:
    get:
      operationId: listEmployeeAccounts
      tags:
        - Employees
      summary: List employee accounts
      description: Returns a list of employee accounts containing email, external id, language, and activation status.
      responses:
        '200':
          description: A list of employee accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeAccountList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/personals:
    get:
      operationId: listEmployeePersonals
      tags:
        - Employees
      summary: List employee personal information
      description: Returns personal information for employees.
      responses:
        '200':
          description: A list of personal information sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/works:
    get:
      operationId: listEmployeeWorks
      tags:
        - Employees
      summary: List employee work information
      description: Returns work information for employees.
      responses:
        '200':
          description: A list of work information sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/work-schedules:
    get:
      operationId: listEmployeeWorkSchedules
      tags:
        - Employees
      summary: List employee work schedules
      description: Returns work schedules for employees.
      responses:
        '200':
          description: A list of work schedules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/addresses:
    get:
      operationId: listEmployeeAddresses
      tags:
        - Employees
      summary: List employee addresses
      description: Returns addresses for employees.
      responses:
        '200':
          description: A list of address sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/financials:
    get:
      operationId: listEmployeeFinancials
      tags:
        - Employees
      summary: List employee financial data
      description: Returns financial data sections for employees.
      responses:
        '200':
          description: A list of financial sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/homes:
    get:
      operationId: listEmployeeHomes
      tags:
        - Employees
      summary: List employee home information
      description: Returns home information sections for employees.
      responses:
        '200':
          description: A list of home sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/emergencies:
    get:
      operationId: listEmployeeEmergencies
      tags:
        - Employees
      summary: List employee emergency contacts
      description: Returns emergency contact sections for employees.
      responses:
        '200':
          description: A list of emergency contact sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/accounts:
    put:
      operationId: updateEmployeeAccount
      tags:
        - Employees
      summary: Update employee account section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/personals:
    put:
      operationId: updateEmployeePersonal
      tags:
        - Employees
      summary: Update employee personal section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/works:
    put:
      operationId: updateEmployeeWork
      tags:
        - Employees
      summary: Update employee work section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/work-schedules:
    put:
      operationId: updateEmployeeWorkSchedule
      tags:
        - Employees
      summary: Update employee work schedule section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/addresses:
    put:
      operationId: updateEmployeeAddress
      tags:
        - Employees
      summary: Update employee address section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/financials:
    put:
      operationId: updateEmployeeFinancial
      tags:
        - Employees
      summary: Update employee financial section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/homes:
    put:
      operationId: updateEmployeeHome
      tags:
        - Employees
      summary: Update employee home section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/emergencies:
    put:
      operationId: updateEmployeeEmergency
      tags:
        - Employees
      summary: Update employee emergency section
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Section'
      responses:
        '200':
          description: The updated section.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/activate:
    put:
      operationId: activateEmployee
      tags:
        - Employees
      summary: Activate an employee
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: The employee was activated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}/deactivate:
    put:
      operationId: deactivateEmployee
      tags:
        - Employees
      summary: Deactivate an employee
      parameters:
        - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: The employee was deactivated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attendances:
    get:
      operationId: listAttendances
      tags:
        - Attendance
      summary: List attendances
      description: Returns a list of attendance entries.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of attendance entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttendanceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAttendance
      tags:
        - Attendance
      summary: Create an attendance
      description: Creates a new attendance entry, identifying the employee by userId, email, or externalId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttendanceInput'
      responses:
        '201':
          description: The created attendance entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attendance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attendances/{attendanceId}:
    get:
      operationId: getAttendance
      tags:
        - Attendance
      summary: Get an attendance
      parameters:
        - $ref: '#/components/parameters/AttendanceId'
      responses:
        '200':
          description: The attendance entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attendance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAttendance
      tags:
        - Attendance
      summary: Update an attendance
      parameters:
        - $ref: '#/components/parameters/AttendanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttendanceInput'
      responses:
        '200':
          description: The updated attendance entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attendance'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAttendance
      tags:
        - Attendance
      summary: Delete an attendance
      parameters:
        - $ref: '#/components/parameters/AttendanceId'
      responses:
        '204':
          description: The attendance entry was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attendances/track-time:
    post:
      operationId: trackTime
      tags:
        - Attendance
      summary: Track an attendance entry
      description: Tracks a clock-in / clock-out by sending an employee identifier and a dateTime.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackTimeInput'
      responses:
        '200':
          description: The tracked attendance entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attendance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attendances/categories:
    get:
      operationId: listAttendanceCategories
      tags:
        - Attendance
      summary: List attendance categories
      responses:
        '200':
          description: A list of attendance categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /attendances/expected-time:
    get:
      operationId: listExpectedTime
      tags:
        - Attendance
      summary: List expected time per user
      description: Returns a paginated list of expected working time by user for a given date range.
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
        - name: to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A list of expected times.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time-off-requests:
    get:
      operationId: listTimeOffRequests
      tags:
        - Time Off
      summary: List time-off requests
      responses:
        '200':
          description: A list of time-off requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequestList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTimeOffRequest
      tags:
        - Time Off
      summary: Create a time-off request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffRequestInput'
      responses:
        '201':
          description: The created time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time-off-requests/processed:
    post:
      operationId: createProcessedTimeOffRequest
      tags:
        - Time Off
      summary: Create a pre-approved time-off request
      description: Creates a time-off request that is already approved (processed).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffRequestInput'
      responses:
        '201':
          description: The created pre-approved time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time-off-types:
    get:
      operationId: listTimeOffTypes
      tags:
        - Time Off
      summary: List time-off types
      responses:
        '200':
          description: A list of time-off types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time-off-status:
    get:
      operationId: listTimeOffStatus
      tags:
        - Time Off
      summary: List time-off statuses
      responses:
        '200':
          description: A list of time-off statuses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time-off/set-balance/{timeOffTypeId}/{employeeId}:
    put:
      operationId: setTimeOffBalance
      tags:
        - Time Off
      summary: Set a time-off balance
      description: Sets an employee's balance for a given time-off type.
      parameters:
        - name: timeOffTypeId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/EmployeeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceInput'
      responses:
        '200':
          description: The balance was set.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /documents/company:
    get:
      operationId: listCompanyDocuments
      tags:
        - Documents
      summary: List company documents
      description: Returns a paginated list of company documents.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of company documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /compensation/contracts:
    get:
      operationId: listContracts
      tags:
        - Compensation
      summary: List contracts
      responses:
        '200':
          description: A list of contracts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /compensation/contract-types:
    get:
      operationId: listContractTypes
      tags:
        - Compensation
      summary: List contract types
      responses:
        '200':
          description: A list of contract types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /compensation/salaries:
    get:
      operationId: listSalaries
      tags:
        - Compensation
      summary: List salaries
      responses:
        '200':
          description: A list of salaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /compensation/additional-payments:
    get:
      operationId: listAdditionalPayments
      tags:
        - Compensation
      summary: List additional payments
      responses:
        '200':
          description: A list of additional payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /compensation/additional-payment-types:
    get:
      operationId: listAdditionalPaymentTypes
      tags:
        - Compensation
      summary: List additional payment types
      responses:
        '200':
          description: A list of additional payment types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /companies:
    get:
      operationId: listCompanies
      tags:
        - Organization
      summary: List companies
      responses:
        '200':
          description: A list of companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /offices:
    get:
      operationId: listOffices
      tags:
        - Organization
      summary: List offices
      responses:
        '200':
          description: A list of offices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOffice
      tags:
        - Organization
      summary: Create an office
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '201':
          description: The created office.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /offices/{id}:
    get:
      operationId: getOffice
      tags:
        - Organization
      summary: Get an office
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The office.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateOffice
      tags:
        - Organization
      summary: Update an office
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '200':
          description: The updated office.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteOffice
      tags:
        - Organization
      summary: Delete an office
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: The office was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /departments:
    get:
      operationId: listDepartments
      tags:
        - Organization
      summary: List departments
      responses:
        '200':
          description: A list of departments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDepartment
      tags:
        - Organization
      summary: Create a department
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '201':
          description: The created department.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /departments/{id}:
    get:
      operationId: getDepartment
      tags:
        - Organization
      summary: Get a department
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The department.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDepartment
      tags:
        - Organization
      summary: Update a department
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '200':
          description: The updated department.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteDepartment
      tags:
        - Organization
      summary: Delete a department
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: The department was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /teams:
    get:
      operationId: listTeams
      tags:
        - Organization
      summary: List teams
      responses:
        '200':
          description: A list of teams.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTeam
      tags:
        - Organization
      summary: Create a team
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '201':
          description: The created team.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /teams/{id}:
    get:
      operationId: getTeam
      tags:
        - Organization
      summary: Get a team
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The team.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTeam
      tags:
        - Organization
      summary: Update a team
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '200':
          description: The updated team.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteTeam
      tags:
        - Organization
      summary: Delete a team
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: The team was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /areas:
    get:
      operationId: listAreas
      tags:
        - Organization
      summary: List areas
      responses:
        '200':
          description: A list of areas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createArea
      tags:
        - Organization
      summary: Create an area
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '201':
          description: The created area.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /areas/{id}:
    get:
      operationId: getArea
      tags:
        - Organization
      summary: Get an area
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The area.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateArea
      tags:
        - Organization
      summary: Update an area
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedResourceInput'
      responses:
        '200':
          description: The updated area.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteArea
      tags:
        - Organization
      summary: Delete an area
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: The area was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calendars:
    get:
      operationId: listCalendars
      tags:
        - Organization
      summary: List calendars
      responses:
        '200':
          description: A list of calendars.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calendars/{id}:
    get:
      operationId: getCalendar
      tags:
        - Organization
      summary: Get a calendar
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The calendar.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /custom-fields:
    get:
      operationId: listCustomFields
      tags:
        - Organization
      summary: List custom fields
      responses:
        '200':
          description: A list of custom fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /work-schedules/contracted-weekly-minutes:
    get:
      operationId: listContractedWeeklyMinutes
      tags:
        - Organization
      summary: List contracted weekly minutes
      description: Returns contracted weekly minutes per employee.
      responses:
        '200':
          description: A list of contracted weekly minutes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/positions:
    get:
      operationId: listPositions
      tags:
        - Recruiting
      summary: List job positions
      description: Returns a list of job openings, including public positions usable to build a custom career site.
      responses:
        '200':
          description: A list of positions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/candidates:
    get:
      operationId: listCandidates
      tags:
        - Recruiting
      summary: List candidates
      responses:
        '200':
          description: A list of candidates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCandidate
      tags:
        - Recruiting
      summary: Create a candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateInput'
      responses:
        '201':
          description: The created candidate.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/candidates/{candidateId}:
    get:
      operationId: getCandidate
      tags:
        - Recruiting
      summary: Get a candidate
      parameters:
        - $ref: '#/components/parameters/CandidateId'
      responses:
        '200':
          description: The candidate.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCandidate
      tags:
        - Recruiting
      summary: Update a candidate
      parameters:
        - $ref: '#/components/parameters/CandidateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateInput'
      responses:
        '200':
          description: The updated candidate.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/candidates/{candidateId}/attachment:
    post:
      operationId: addCandidateAttachment
      tags:
        - Recruiting
      summary: Add a candidate attachment
      parameters:
        - $ref: '#/components/parameters/CandidateId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: The attachment was added.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/candidates/{candidateId}/documents:
    get:
      operationId: getCandidateDocuments
      tags:
        - Recruiting
      summary: Get candidate documents
      parameters:
        - $ref: '#/components/parameters/CandidateId'
      responses:
        '200':
          description: A list of candidate documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/applications:
    get:
      operationId: listApplications
      tags:
        - Recruiting
      summary: List applications
      responses:
        '200':
          description: A list of applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/applications/position/{positionId}/candidate/{candidateId}:
    post:
      operationId: createApplication
      tags:
        - Recruiting
      summary: Create an application
      description: Creates an application tying a candidate to a position.
      parameters:
        - $ref: '#/components/parameters/PositionId'
        - $ref: '#/components/parameters/CandidateId'
      responses:
        '201':
          description: The created application.
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateApplication
      tags:
        - Recruiting
      summary: Update an application
      parameters:
        - $ref: '#/components/parameters/PositionId'
        - $ref: '#/components/parameters/CandidateId'
      responses:
        '200':
          description: The updated application.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recruiting/applications/position/{positionId}/candidate/{candidateId}/attachment:
    post:
      operationId: addApplicationAttachment
      tags:
        - Recruiting
      summary: Add an application attachment
      parameters:
        - $ref: '#/components/parameters/PositionId'
        - $ref: '#/components/parameters/CandidateId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: The attachment was added.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /auth/login by exchanging a Kenjo API key.
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
      description: Zero-based page index for paginated results.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Number of items to return per page.
    EmployeeId:
      name: employeeId
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the employee.
    AttendanceId:
      name: attendanceId
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the attendance entry.
    CandidateId:
      name: candidateId
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the candidate.
    PositionId:
      name: positionId
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the position.
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the resource.
  responses:
    Unauthorized:
      description: The bearer token is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    LoginRequest:
      type: object
      required:
        - apiKey
      properties:
        apiKey:
          type: string
          description: The API key generated in Settings > Integrations > API.
    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: Bearer token to send in the Authorization header.
    GenericList:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
    SectionList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    Section:
      type: object
      additionalProperties: true
      description: A profile section payload. Field set varies by section (account, personal, work, etc.).
    UserAccount:
      type: object
      properties:
        _id:
          type: string
        email:
          type: string
          format: email
        externalId:
          type: string
        language:
          type: string
        active:
          type: boolean
    UserAccountList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    EmployeeAccountList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    EmployeeInput:
      type: object
      properties:
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        externalId:
          type: string
        language:
          type: string
      required:
        - email
    Employee:
      allOf:
        - $ref: '#/components/schemas/EmployeeInput'
        - type: object
          properties:
            _id:
              type: string
            active:
              type: boolean
    EmployeeList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    AttendanceInput:
      type: object
      properties:
        userId:
          type: string
        email:
          type: string
          format: email
        externalId:
          type: string
        date:
          type: string
          format: date
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        category:
          type: string
    Attendance:
      allOf:
        - $ref: '#/components/schemas/AttendanceInput'
        - type: object
          properties:
            _id:
              type: string
    AttendanceList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    TrackTimeInput:
      type: object
      properties:
        userId:
          type: string
        email:
          type: string
          format: email
        externalId:
          type: string
        dateTime:
          type: string
          format: date-time
      required:
        - dateTime
    TimeOffRequestInput:
      type: object
      properties:
        employeeId:
          type: string
        timeOffTypeId:
          type: string
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        description:
          type: string
      required:
        - timeOffTypeId
        - from
        - to
    TimeOffRequest:
      allOf:
        - $ref: '#/components/schemas/TimeOffRequestInput'
        - type: object
          properties:
            _id:
              type: string
            status:
              type: string
    TimeOffRequestList:
      allOf:
        - $ref: '#/components/schemas/GenericList'
    BalanceInput:
      type: object
      properties:
        balance:
          type: number
          description: The balance value to set for the time-off type.
      required:
        - balance
    NamedResourceInput:
      type: object
      properties:
        name:
          type: string
      required:
        - name
    CandidateInput:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string