openapi: 3.0.4
info:
  title: Flo Recruit API
  description: |
    API to fetch job applications with filtering options based on status and status update dates.
  version: 1.0.0
servers:
- url: https://virtserver.swaggerhub.com/florecruit/FloApi/1.0.0
  description: SwaggerHub API Auto Mocking
paths:
  /v1/job-applications:
    get:
      tags:
      - HRIS API
      summary: Retrieve job applications with optional filters
      description: |
        Fetch job applications filtered by last status update date range and/or pipeline stage.
        - `job_application_status_start` and `job_application_status_end` filter by last status update date (UTC).
        - `job_application_status` filters by a specific pipeline stage.
        If `job_application_status` is omitted, all statuses within the date range are returned.
      operationId: fetchHRISJobApplications
      parameters:
      - name: job_application_status_start
        in: query
        description: Filter candidates by last status update start date (UTC). Default is 30 days in the past.
        required: false
        schema:
          type: string
          format: date-time
      - name: job_application_status_end
        in: query
        description: Filter candidates by last status update end date (UTC).
        required: false
        schema:
          type: string
          format: date-time
      - name: job_application_status
        in: query
        description: "Filter by pipeline stage (e.g., Application Extended, Offer Accepted). Must be a step in an Active Pipeline Template."
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK - Successfully retrieved job applications matching the filter criteria.
          content:
            application/json:
              schema:
                type: array
                example:
                - firstName: Jane
                  lastName: Doe
                  candidateId: fge25ghn-4mh7-4kli-c9sz-e436ht34jt09
                  email: jane.doe@example.com
                  phone: +1-555-123-4567
                  applicationId: f18fc41a-4357-4520-a9ce-e477ef947b36
                  jobTitle: Entry Level Associate
                  department: Litigation
                  officeLocation: New York
                  employmentType: Full-time
                  jobApplicationStatuses:
                  - statusName: Hired
                    statusUpdatedAt: 2025-10-06T22:07:44Z
                  position: Associate
                  requisitionId: req-12345
                  startDate: 2025-10-10
                  salary: 175000
                  jobApplicationLastStatusUpdate: 2025-09-15T12:30:00Z
                items:
                  $ref: "#/components/schemas/JobApplicationHRISResponse"
        "400":
          description: Bad Request - Incorrect request format or invalid status filter value. Check query parameters for correct date-time format and valid pipeline stage names.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_400"
        "401":
          description: Unauthorized Access - Authentication failed or missing credentials. Reach out to Flo Recruit Support for access issues.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
        "429":
          description: Rate Limit Error - Too many requests in a given amount of time. Please retry after some time.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_429"
        "500":
          description: Internal Server Error - An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_500"
components:
  schemas:
    JobApplicationHRISResponse:
      type: object
      properties:
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Doe
        candidateId:
          type: string
          format: uuid
        email:
          type: string
          format: email
          example: jane.doe@example.com
        phone:
          type: string
          example: +1-555-123-4567
        applicationId:
          type: string
          format: uuid
          example: f18fc41a-4357-4520-a9ce-e477ef947b36
        jobTitle:
          type: string
          example: Entry Level Associate
        jobId:
          type: string
          format: uuid
        department:
          type: string
          example: Litigation
        officeLocation:
          type: string
          example: New York
        employmentType:
          type: string
          example: Full-time
        jobApplicationStatuses:
          type: array
          items:
            $ref: "#/components/schemas/JobApplicationStatus"
        position:
          type: string
          example: Associate
        requisitionId:
          type: string
          example: req-12345
        startDate:
          type: string
          format: date
          example: 2025-10-10
        salary:
          type: integer
          example: 175000
        jobApplicationLastStatusUpdate:
          type: string
          format: date-time
          example: 2025-09-15T12:30:00Z
    JobApplicationStatus:
      type: object
      properties:
        statusName:
          type: string
          example: Hired
        statusUpdatedAt:
          type: string
          format: date-time
          example: 2025-10-06T22:07:44Z
    inline_response_400:
      type: object
      properties:
        error:
          type: string
          example: Invalid job_application_status value provided.
    inline_response_401:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized access. Please provide valid authentication credentials.
    inline_response_429:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please try again later.
    inline_response_500:
      type: object
      properties:
        error:
          type: string
          example: An internal server error occurred. Please try again later.
