openapi: 3.0.3
info:
  title: Freshteam Applicants Time-off API
  description: 'The Freshteam API is the REST interface to Freshworks'' HR and applicant tracking (ATS) product. It covers the HRIS core (employees, custom fields, and organization structure), time-off (leave), recruiting (job postings), the ATS (applicants and candidate sources), and onboarding (new hires). Requests target an account-specific base, https://{domain}.freshteam.com/api, where {domain} is your Freshteam subdomain, and carry an account API token as a Bearer credential (generated in the UI under API Settings). List endpoints are paginated with page, sort, and sort_type query parameters and return total-objects, total-pages, and link response headers.

    STATUS - Freshworks has announced the end-of-life of Freshteam. New subscriptions and renewals are halted starting March 7, 2026; existing customers retain access, and thus API access, only through the end of their subscription term (reported through approximately April 2027). This document models the publicly documented API as it exists during the sunset window; new customers cannot obtain access.'
  version: '1.0'
  contact:
    name: Freshworks - Freshteam
    url: https://developers.freshteam.com/api/
servers:
- url: https://{domain}.freshteam.com/api
  description: Account-specific Freshteam API base
  variables:
    domain:
      default: your-account
      description: Your Freshteam account subdomain.
security:
- bearerAuth: []
tags:
- name: Time-off
  description: Time-off (leave) requests and types.
paths:
  /time_offs:
    get:
      operationId: listTimeOffs
      tags:
      - Time-off
      summary: List time-off requests
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A list of time-off requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeOff'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTimeOff
      tags:
      - Time-off
      summary: Create a time-off request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOff'
      responses:
        '201':
          description: The created time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time_offs/{id}:
    get:
      operationId: getTimeOff
      tags:
      - Time-off
      summary: Retrieve a time-off request
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The requested time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
        '404':
          $ref: '#/components/responses/NotFound'
  /time_offs/{id}/approve:
    put:
      operationId: approveTimeOff
      tags:
      - Time-off
      summary: Approve a time-off request
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The approved time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time_offs/{id}/cancel:
    put:
      operationId: cancelTimeOff
      tags:
      - Time-off
      summary: Cancel a time-off request
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The cancelled time-off request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
        '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:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Page number for paginated list results (default 1).
      schema:
        type: integer
        default: 1
    IdPath:
      name: id
      in: path
      required: true
      description: The resource identifier.
      schema:
        type: integer
        format: int64
  responses:
    Unauthorized:
      description: Authentication failed or the API token is missing or invalid.
    NotFound:
      description: The requested resource was not found.
  schemas:
    TimeOff:
      type: object
      properties:
        id:
          type: integer
          format: int64
        applicant_id:
          type: integer
          format: int64
        leave_type_id:
          type: integer
          format: int64
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        status:
          type: string
        reason:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Account API token generated in the Freshteam UI under API Settings, passed as Authorization: Bearer YOUR_API_TOKEN.'