freshworks Employees API

openapi: 3.2.0
info:
  title: Freshworks Freshteam Employees API
  description: The Freshteam API provides programmatic access to HR and recruiting functionality within the Freshteam platform. It supports operations for managing employees, job postings, candidates, branches, departments, and other HR resources. The API uses OAuth 2.0 authentication and enables developers to automate HR workflows, integrate employee data with other business systems, and build custom applications on top of Freshteam's applicant tracking and HR management capabilities.
  version: '1.0'
  contact:
    name: Freshworks Support
    url: https://support.freshteam.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshteam.com/api
  description: Freshteam Production Server
  variables:
    domain:
      default: yourdomain
      description: Your Freshteam subdomain
security:
- bearerAuth: []
tags:
- name: Employees
  description: Manage employee records including personal information, job details, and employment history.
paths:
  /employees:
    get:
      operationId: listEmployees
      summary: List all employees
      description: Retrieves a paginated list of all employees in the Freshteam system. Supports filtering by status and sort options.
      tags:
      - Employees
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - name: sort
        in: query
        description: Field to sort by.
        schema:
          type: string
      - name: sort_type
        in: query
        description: Sort direction (asc or desc).
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: status
        in: query
        description: Filter by employment status.
        schema:
          type: string
          enum:
          - active
          - inactive
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employee_id}:
    get:
      operationId: getEmployee
      summary: View an employee
      description: Retrieves the full details of a specific employee by their ID.
      tags:
      - Employees
      parameters:
      - $ref: '#/components/parameters/EmployeeIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEmployee
      summary: Update an employee
      description: Updates the properties of an existing employee record.
      tags:
      - Employees
      parameters:
      - $ref: '#/components/parameters/EmployeeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeUpdate'
      responses:
        '200':
          description: Employee updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /employee_fields:
    get:
      operationId: listEmployeeFields
      summary: List all employee fields
      description: Retrieves the list of all employee form fields, including custom fields and their configurations.
      tags:
      - Employees
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Field'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
    Employee:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the employee.
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        official_email:
          type: string
          format: email
          description: Official work email address.
        personal_email:
          type: string
          format: email
          description: Personal email address.
        employee_id:
          type: string
          description: Employee ID number.
        status:
          type: string
          description: Employment status (active, inactive).
        designation:
          type: string
          description: Job designation or title.
        phone_number:
          type: string
          description: Phone number.
        date_of_birth:
          type: string
          format: date
          description: Date of birth.
        joining_date:
          type: string
          format: date
          description: Date of joining the organization.
        branch_id:
          type: integer
          description: ID of the branch.
        department_id:
          type: integer
          description: ID of the department.
        sub_department_id:
          type: integer
          description: ID of the sub-department.
        reporting_to_id:
          type: integer
          description: ID of the reporting manager.
        level_id:
          type: integer
          description: ID of the employee level.
        role_id:
          type: integer
          description: ID of the assigned role.
        gender:
          type: string
          description: Gender.
        address:
          type: object
          description: Address information.
          properties:
            street:
              type: string
              description: Street address.
            city:
              type: string
              description: City.
            state:
              type: string
              description: State or province.
            country:
              type: string
              description: Country.
            zip_code:
              type: string
              description: ZIP or postal code.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    EmployeeUpdate:
      type: object
      properties:
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        official_email:
          type: string
          format: email
          description: Official work email.
        designation:
          type: string
          description: Job designation.
        phone_number:
          type: string
          description: Phone number.
        branch_id:
          type: integer
          description: Branch ID.
        department_id:
          type: integer
          description: Department ID.
        sub_department_id:
          type: integer
          description: Sub-department ID.
        reporting_to_id:
          type: integer
          description: Reporting manager ID.
        level_id:
          type: integer
          description: Level ID.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
    Field:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the field.
        name:
          type: string
          description: Internal name of the field.
        label:
          type: string
          description: Display label.
        field_type:
          type: string
          description: Type of field (text, dropdown, checkbox, etc).
        required:
          type: boolean
          description: Whether the field is required.
        position:
          type: integer
          description: Display position order.
        choices:
          type: array
          description: Available choices for dropdown fields.
          items:
            type: string
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    EmployeeIdParam:
      name: employee_id
      in: path
      required: true
      description: The ID of the employee.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token. Obtain access tokens via the Freshteam OAuth authorization flow.
externalDocs:
  description: Freshteam API Documentation
  url: https://developers.freshteam.com/api/