freshworks Applicants API

openapi: 3.2.0
info:
  title: Freshworks Freshteam Applicants 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: Applicants
  description: Manage job applicants and their application details.
paths:
  /job_postings/{job_posting_id}/applicants:
    get:
      operationId: listApplicants
      summary: List applicants for a job posting
      description: Retrieves a paginated list of all applicants for a specific job posting.
      tags:
      - Applicants
      parameters:
      - $ref: '#/components/parameters/JobPostingIdParam'
      - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Applicant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createApplicant
      summary: Create an applicant for a job posting
      description: Creates a new applicant for a specific job posting. This is used to programmatically submit job applications.
      tags:
      - Applicants
      parameters:
      - $ref: '#/components/parameters/JobPostingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicantCreate'
      responses:
        '201':
          description: Applicant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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.
    Applicant:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the applicant.
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        email:
          type: string
          format: email
          description: Email address.
        phone_number:
          type: string
          description: Phone number.
        job_posting_id:
          type: integer
          description: ID of the associated job posting.
        status:
          type: string
          description: Application status.
        source:
          type: string
          description: Application source.
        resume_url:
          type: string
          format: uri
          description: URL to the applicant resume.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the application was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ApplicantCreate:
      type: object
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        email:
          type: string
          format: email
          description: Email address.
        phone_number:
          type: string
          description: Phone number.
        source:
          type: string
          description: Application source.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
  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
  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/