freshworks Job Postings API

openapi: 3.2.0
info:
  title: Freshworks Freshteam Job Postings 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: Job Postings
  description: Manage job postings and their associated applicant fields.
paths:
  /job_postings:
    get:
      operationId: listJobPostings
      summary: List all job postings
      description: Retrieves a list of all job postings in the Freshteam system.
      tags:
      - Job Postings
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - name: status
        in: query
        description: Filter by posting status (draft, published, on_hold, closed).
        schema:
          type: string
          enum:
          - draft
          - published
          - on_hold
          - closed
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobPosting'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /job_postings/{job_posting_id}:
    get:
      operationId: getJobPosting
      summary: View a job posting
      description: Retrieves the details of a specific job posting by its ID.
      tags:
      - Job Postings
      parameters:
      - $ref: '#/components/parameters/JobPostingIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPosting'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /job_postings/{job_posting_id}/applicant_fields:
    get:
      operationId: listApplicantFields
      summary: List applicant fields for a job posting
      description: Retrieves the list of applicant form fields for a specific job posting, including required and custom fields.
      tags:
      - Job Postings
      parameters:
      - $ref: '#/components/parameters/JobPostingIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Field'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
    JobPosting:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the job posting.
        title:
          type: string
          description: Title of the job posting.
        description:
          type: string
          description: Full job description.
        status:
          type: string
          description: Status of the posting.
          enum:
          - draft
          - published
          - on_hold
          - closed
        branch_id:
          type: integer
          description: ID of the branch.
        department_id:
          type: integer
          description: ID of the department.
        type:
          type: string
          description: Employment type (full_time, part_time, contract).
        experience:
          type: string
          description: Required experience level.
        remote:
          type: boolean
          description: Whether the position is remote.
        salary:
          type: object
          description: Salary range information.
          properties:
            min:
              type: number
              description: Minimum salary.
            max:
              type: number
              description: Maximum salary.
            currency:
              type: string
              description: Currency code.
        closing_date:
          type: string
          format: date
          description: Closing date for applications.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    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
    JobPostingIdParam:
      name: job_posting_id
      in: path
      required: true
      description: The ID of the job posting.
      schema:
        type: integer
  responses:
    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'
  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/