openapi: 3.1.0
info:
  title: Oracle EBS Human Resources API
  description: >-
    RESTful APIs for Oracle E-Business Suite Human Resources Management System
    (HRMS) including employee management, payroll processing, workforce
    administration, compensation, and benefits. These PL/SQL APIs are deployed
    as REST services through the Integrated SOA Gateway.
  version: 12.2.0
  contact:
    name: Oracle Support
    email: support@oracle.com
    url: https://support.oracle.com
  license:
    name: Oracle Proprietary
    url: https://www.oracle.com/legal/terms/
  x-logo:
    url: https://www.oracle.com/a/ocom/img/oracle-logo.svg
servers:
- url: https://{instance}.oracle.com/webservices/rest
  description: Oracle EBS ISG REST endpoint
  variables:
    instance:
      default: ebs-host
      description: The Oracle EBS instance hostname
paths:
  /hr/employees:
    get:
      operationId: getEmployees
      summary: Retrieve Employee Records
      description: >-
        Retrieves employee records from Oracle HRMS. Maps to the PER_ALL_PEOPLE_F
        and PER_ALL_ASSIGNMENTS_F tables through the HR_EMPLOYEE_API PL/SQL
        package.
      tags:
      - Employee Management
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: personId
        in: query
        description: Person identifier
        schema:
          type: integer
        example: '500123'
      - name: employeeNumber
        in: query
        description: Employee number
        schema:
          type: string
        example: example_value
      - name: fullName
        in: query
        description: Full name (supports wildcards)
        schema:
          type: string
        example: example_value
      - name: businessGroupId
        in: query
        description: Business group identifier
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date for date-tracked records (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of employees
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getemployees200Example:
                  summary: Default getEmployees 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - personId: '500123'
                      employeeNumber: example_value
                      title: Example Title
                      firstName: example_value
                      middleNames: example_value
                      lastName: example_value
                      fullName: example_value
                      knownAs: example_value
                      emailAddress: user@example.com
                      sex: M
                      dateOfBirth: '2026-01-15'
                      nationalIdentifier: example_value
                      nationality: example_value
                      maritalStatus: example_value
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                      hireDate: '2026-01-15'
                      currentEmployeeFlag: 'Y'
                      businessGroupId: '500123'
                      addresses:
                      - {}
                      phones:
                      - {}
                      creationDate: '2026-01-15T10:30:00Z'
                      lastUpdateDate: '2026-01-15T10:30:00Z'
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEmployee
      summary: Create an Employee Record
      description: >-
        Creates a new employee record using the HR_EMPLOYEE_API.CREATE_EMPLOYEE
        PL/SQL procedure. This creates entries in PER_ALL_PEOPLE_F,
        PER_ALL_ASSIGNMENTS_F, and related tables.
      tags:
      - Employee Management
      security:
      - tokenAuth: []
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeCreate'
            examples:
              CreateemployeeRequestExample:
                summary: Default createEmployee request
                x-microcks-default: true
                value:
                  title: Example Title
                  firstName: example_value
                  middleNames: example_value
                  lastName: example_value
                  knownAs: example_value
                  emailAddress: user@example.com
                  sex: M
                  dateOfBirth: '2026-01-15'
                  nationalIdentifier: example_value
                  nationality: example_value
                  maritalStatus: example_value
                  hireDate: '2026-01-15'
                  businessGroupId: '500123'
                  jobId: '500123'
                  positionId: '500123'
                  organizationId: '500123'
                  gradeId: '500123'
                  locationId: '500123'
                  payrollId: '500123'
      responses:
        '201':
          description: Employee created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
              examples:
                Createemployee201Example:
                  summary: Default createEmployee 201 response
                  x-microcks-default: true
                  value:
                    personId: '500123'
                    employeeNumber: example_value
                    title: Example Title
                    firstName: example_value
                    middleNames: example_value
                    lastName: example_value
                    fullName: example_value
                    knownAs: example_value
                    emailAddress: user@example.com
                    sex: M
                    dateOfBirth: '2026-01-15'
                    nationalIdentifier: example_value
                    nationality: example_value
                    maritalStatus: example_value
                    effectiveStartDate: '2026-01-15'
                    effectiveEndDate: '2026-01-15'
                    hireDate: '2026-01-15'
                    currentEmployeeFlag: 'Y'
                    businessGroupId: '500123'
                    assignment:
                      assignmentId: '500123'
                      assignmentNumber: example_value
                      assignmentType: E
                      primaryFlag: 'Y'
                      jobId: '500123'
                      jobName: example_value
                      positionId: '500123'
                      positionName: example_value
                      gradeId: '500123'
                      gradeName: example_value
                      organizationId: '500123'
                      organizationName: example_value
                      locationId: '500123'
                      locationCode: example_value
                      supervisorId: '500123'
                      payrollId: '500123'
                      employmentCategory: FR
                      normalHours: 42.5
                      frequency: D
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                    addresses:
                    - addressId: '500123'
                      addressType: example_value
                      addressLine1: example_value
                      addressLine2: example_value
                      addressLine3: example_value
                      townOrCity: example_value
                      region1: example_value
                      region2: example_value
                      postalCode: example_value
                      country: example_value
                      primaryFlag: 'Y'
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    phones:
                    - phoneId: '500123'
                      phoneType: W1
                      phoneNumber: example_value
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdateDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /hr/employees/{personId}:
    get:
      operationId: getEmployeeById
      summary: Retrieve an Employee by Person Id
      description: Retrieves a specific employee record by person identifier.
      tags:
      - Employee Management
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: personId
        in: path
        required: true
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date for date-tracked records (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      responses:
        '200':
          description: Employee details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
              examples:
                Getemployeebyid200Example:
                  summary: Default getEmployeeById 200 response
                  x-microcks-default: true
                  value:
                    personId: '500123'
                    employeeNumber: example_value
                    title: Example Title
                    firstName: example_value
                    middleNames: example_value
                    lastName: example_value
                    fullName: example_value
                    knownAs: example_value
                    emailAddress: user@example.com
                    sex: M
                    dateOfBirth: '2026-01-15'
                    nationalIdentifier: example_value
                    nationality: example_value
                    maritalStatus: example_value
                    effectiveStartDate: '2026-01-15'
                    effectiveEndDate: '2026-01-15'
                    hireDate: '2026-01-15'
                    currentEmployeeFlag: 'Y'
                    businessGroupId: '500123'
                    assignment:
                      assignmentId: '500123'
                      assignmentNumber: example_value
                      assignmentType: E
                      primaryFlag: 'Y'
                      jobId: '500123'
                      jobName: example_value
                      positionId: '500123'
                      positionName: example_value
                      gradeId: '500123'
                      gradeName: example_value
                      organizationId: '500123'
                      organizationName: example_value
                      locationId: '500123'
                      locationCode: example_value
                      supervisorId: '500123'
                      payrollId: '500123'
                      employmentCategory: FR
                      normalHours: 42.5
                      frequency: D
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                    addresses:
                    - addressId: '500123'
                      addressType: example_value
                      addressLine1: example_value
                      addressLine2: example_value
                      addressLine3: example_value
                      townOrCity: example_value
                      region1: example_value
                      region2: example_value
                      postalCode: example_value
                      country: example_value
                      primaryFlag: 'Y'
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    phones:
                    - phoneId: '500123'
                      phoneType: W1
                      phoneNumber: example_value
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdateDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateEmployee
      summary: Update an Employee Record
      description: >-
        Updates an existing employee record using the
        HR_PERSON_API.UPDATE_PERSON PL/SQL procedure with date-track support.
      tags:
      - Employee Management
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: personId
        in: path
        required: true
        schema:
          type: integer
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeUpdate'
            examples:
              UpdateemployeeRequestExample:
                summary: Default updateEmployee request
                x-microcks-default: true
                value:
                  effectiveDate: '2026-01-15'
                  dateTrackUpdateMode: CORRECTION
                  title: Example Title
                  firstName: example_value
                  middleNames: example_value
                  lastName: example_value
                  knownAs: example_value
                  emailAddress: user@example.com
                  maritalStatus: example_value
      responses:
        '200':
          description: Employee updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
              examples:
                Updateemployee200Example:
                  summary: Default updateEmployee 200 response
                  x-microcks-default: true
                  value:
                    personId: '500123'
                    employeeNumber: example_value
                    title: Example Title
                    firstName: example_value
                    middleNames: example_value
                    lastName: example_value
                    fullName: example_value
                    knownAs: example_value
                    emailAddress: user@example.com
                    sex: M
                    dateOfBirth: '2026-01-15'
                    nationalIdentifier: example_value
                    nationality: example_value
                    maritalStatus: example_value
                    effectiveStartDate: '2026-01-15'
                    effectiveEndDate: '2026-01-15'
                    hireDate: '2026-01-15'
                    currentEmployeeFlag: 'Y'
                    businessGroupId: '500123'
                    assignment:
                      assignmentId: '500123'
                      assignmentNumber: example_value
                      assignmentType: E
                      primaryFlag: 'Y'
                      jobId: '500123'
                      jobName: example_value
                      positionId: '500123'
                      positionName: example_value
                      gradeId: '500123'
                      gradeName: example_value
                      organizationId: '500123'
                      organizationName: example_value
                      locationId: '500123'
                      locationCode: example_value
                      supervisorId: '500123'
                      payrollId: '500123'
                      employmentCategory: FR
                      normalHours: 42.5
                      frequency: D
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                    addresses:
                    - addressId: '500123'
                      addressType: example_value
                      addressLine1: example_value
                      addressLine2: example_value
                      addressLine3: example_value
                      townOrCity: example_value
                      region1: example_value
                      region2: example_value
                      postalCode: example_value
                      country: example_value
                      primaryFlag: 'Y'
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    phones:
                    - phoneId: '500123'
                      phoneType: W1
                      phoneNumber: example_value
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdateDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /hr/assignments:
    get:
      operationId: getAssignments
      summary: Retrieve Employee Assignments
      description: >-
        Retrieves employee assignment records. Maps to the
        PER_ALL_ASSIGNMENTS_F table through the HR_ASSIGNMENT_API package.
      tags:
      - Employee Management
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: assignmentId
        in: query
        description: Assignment identifier
        schema:
          type: integer
        example: '500123'
      - name: personId
        in: query
        description: Person identifier
        schema:
          type: integer
        example: '500123'
      - name: organizationId
        in: query
        description: HR organization identifier
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Assignment'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getassignments200Example:
                  summary: Default getAssignments 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - assignmentId: '500123'
                      assignmentNumber: example_value
                      assignmentType: E
                      primaryFlag: 'Y'
                      jobId: '500123'
                      jobName: example_value
                      positionId: '500123'
                      positionName: example_value
                      gradeId: '500123'
                      gradeName: example_value
                      organizationId: '500123'
                      organizationName: example_value
                      locationId: '500123'
                      locationCode: example_value
                      supervisorId: '500123'
                      payrollId: '500123'
                      employmentCategory: FR
                      normalHours: 42.5
                      frequency: D
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /hr/organizations:
    get:
      operationId: getOrganizations
      summary: Retrieve Hr Organizations
      description: >-
        Retrieves HR organization records. Maps to the HR_ALL_ORGANIZATION_UNITS
        and HR_ORGANIZATION_INFORMATION tables.
      tags:
      - Organization
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: organizationId
        in: query
        description: Organization identifier
        schema:
          type: integer
        example: '500123'
      - name: name
        in: query
        description: Organization name (supports wildcards)
        schema:
          type: string
        example: Example Title
      - name: businessGroupId
        in: query
        description: Business group identifier
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getorganizations200Example:
                  summary: Default getOrganizations 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - organizationId: '500123'
                      name: Example Title
                      businessGroupId: '500123'
                      dateFrom: '2026-01-15'
                      dateTo: '2026-01-15'
                      locationId: '500123'
                      type: example_value
                      internalExternalFlag: INT
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /hr/positions:
    get:
      operationId: getPositions
      summary: Retrieve Hr Positions
      description: >-
        Retrieves position records. Maps to the HR_ALL_POSITIONS_F table
        through the HR_POSITION_API package.
      tags:
      - Organization
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: positionId
        in: query
        description: Position identifier
        schema:
          type: integer
        example: '500123'
      - name: name
        in: query
        description: Position name (supports wildcards)
        schema:
          type: string
        example: Example Title
      - name: organizationId
        in: query
        description: Organization identifier
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Position'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getpositions200Example:
                  summary: Default getPositions 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - positionId: '500123'
                      name: Example Title
                      jobId: '500123'
                      organizationId: '500123'
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                      status: example_value
                      availabilityStatusId: '500123'
                      businessGroupId: '500123'
                      locationId: '500123'
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pay/payrolls:
    get:
      operationId: getPayrolls
      summary: Retrieve Payroll Definitions
      description: >-
        Retrieves payroll definitions from Oracle Payroll. Maps to the
        PAY_ALL_PAYROLLS_F table.
      tags:
      - Payroll
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: payrollId
        in: query
        description: Payroll identifier
        schema:
          type: integer
        example: '500123'
      - name: payrollName
        in: query
        description: Payroll name
        schema:
          type: string
        example: example_value
      - name: businessGroupId
        in: query
        description: Business group identifier
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of payroll definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payroll'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getpayrolls200Example:
                  summary: Default getPayrolls 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - payrollId: '500123'
                      payrollName: example_value
                      periodType: Calendar Month
                      numberOfYears: 10
                      firstPeriodEndDate: '2026-01-15'
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                      businessGroupId: '500123'
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pay/payrollRuns:
    get:
      operationId: getPayrollRuns
      summary: Retrieve Payroll Run Results
      description: >-
        Retrieves payroll run and action results. Maps to the
        PAY_PAYROLL_ACTIONS, PAY_ASSIGNMENT_ACTIONS, and PAY_RUN_RESULTS tables.
      tags:
      - Payroll
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: payrollActionId
        in: query
        description: Payroll action identifier
        schema:
          type: integer
        example: '500123'
      - name: payrollId
        in: query
        description: Payroll identifier
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of payroll runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayrollRun'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getpayrollruns200Example:
                  summary: Default getPayrollRuns 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - payrollActionId: '500123'
                      payrollId: '500123'
                      actionType: example_value
                      actionStatus: C
                      effectiveDate: '2026-01-15'
                      dateEarned: '2026-01-15'
                      periodOfServiceId: '500123'
                      businessGroupId: '500123'
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ben/benefits:
    get:
      operationId: getBenefitEnrollments
      summary: Retrieve Benefit Enrollments
      description: >-
        Retrieves employee benefit enrollment records. Maps to the
        BEN_PRTT_ENRT_RSLT_F table through the Benefits API.
      tags:
      - Benefits
      security:
      - tokenAuth: []
      - basicAuth: []
      parameters:
      - name: personId
        in: query
        description: Person identifier
        schema:
          type: integer
        example: '500123'
      - name: planId
        in: query
        description: Benefit plan identifier
        schema:
          type: integer
        example: '500123'
      - name: effectiveDate
        in: query
        description: Effective date (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of benefit enrollments
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/BenefitEnrollment'
                  totalCount:
                    type: integer
                  hasMore:
                    type: boolean
              examples:
                Getbenefitenrollments200Example:
                  summary: Default getBenefitEnrollments 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - enrollmentResultId: '500123'
                      personId: '500123'
                      planId: '500123'
                      planName: example_value
                      optionId: '500123'
                      optionName: example_value
                      coverageLevelCode: example_value
                      effectiveStartDate: '2026-01-15'
                      effectiveEndDate: '2026-01-15'
                      enrollmentStartDate: '2026-01-15'
                      enrollmentEndDate: '2026-01-15'
                      benefitAmount: 42.5
                    totalCount: 10
                    hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with Oracle EBS username and password
    tokenAuth:
      type: apiKey
      in: cookie
      name: accessToken
      description: Token-based authentication using the ISG login access token
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return
      schema:
        type: integer
        default: 25
        maximum: 500
    Offset:
      name: offset
      in: query
      description: Number of records to skip for pagination
      schema:
        type: integer
        default: 0
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Employee:
      type: object
      properties:
        personId:
          type: integer
          description: Person identifier
          example: '500123'
        employeeNumber:
          type: string
          description: Employee number
          example: example_value
        title:
          type: string
          description: Title (Mr., Mrs., etc.)
          example: Example Title
        firstName:
          type: string
          description: First name
          example: example_value
        middleNames:
          type: string
          description: Middle name(s)
          example: example_value
        lastName:
          type: string
          description: Last name
          example: example_value
        fullName:
          type: string
          description: Full name (derived)
          example: example_value
        knownAs:
          type: string
          description: Preferred name
          example: example_value
        emailAddress:
          type: string
          format: email
          description: Email address
          example: user@example.com
        sex:
          type: string
          description: Gender
          enum:
          - M
          - F
          example: M
        dateOfBirth:
          type: string
          format: date
          description: Date of birth
          example: '2026-01-15'
        nationalIdentifier:
          type: string
          description: National identifier (e.g., SSN)
          example: example_value
        nationality:
          type: string
          description: Nationality code
          example: example_value
        maritalStatus:
          type: string
          description: Marital status
          example: example_value
        effectiveStartDate:
          type: string
          format: date
          description: Record effective start date (date-tracked)
          example: '2026-01-15'
        effectiveEndDate:
          type: string
          format: date
          description: Record effective end date (date-tracked)
          example: '2026-01-15'
        hireDate:
          type: string
          format: date
          description: Original hire date
          example: '2026-01-15'
        currentEmployeeFlag:
          type: string
          enum:
          - 'Y'
          - 'N'
          example: 'Y'
        businessGroupId:
          type: integer
          description: Business group identifier
          example: '500123'
        assignment:
          $ref: '#/components/schemas/Assignment'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          example: []
        phones:
          type: array
          items:
            $ref: '#/components/schemas/Phone'
          example: []
        creationDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        lastUpdateDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    EmployeeCreate:
      type: object
      required:
      - firstName
      - lastName
      - hireDate
      - businessGroupId
      properties:
        title:
          type: string
          example: Example Title
        firstName:
          type: string
          example: example_value
        middleNames:
          type: string
          example: example_value
        lastName:
          type: string
          example: example_value
        knownAs:
          type: string
          example: example_value
        emailAddress:
          type: string
          format: email
          example: user@example.com
        sex:
          type: string
          enum:
          - M
          - F
          example: M
        dateOfBirth:
          type: string
          format: date
          example: '2026-01-15'
        nationalIdentifier:
          type: string
          example: example_value
        nationality:
          type: string
          example: example_value
        maritalStatus:
          type: string
          example: example_value
        hireDate:
          type: string
          format: date
          example: '2026-01-15'
        businessGroupId:
          type: integer
          example: '500123'
        jobId:
          type: integer
          example: '500123'
        positionId:
          type: integer
          example: '500123'
        organizationId:
          type: integer
          example: '500123'
        gradeId:
          type: integer
          example: '500123'
        locationId:
          type: integer
          example: '500123'
        payrollId:
          type: integer
          example: '500123'
    EmployeeUpdate:
      type: object
      required:
      - effectiveDate
      properties:
        effectiveDate:
          type: string
          format: date
          description: Date-track effective date for the update
          example: '2026-01-15'
        dateTrackUpdateMode:
          type: string
          description: Date-track update mode
          enum:
          - CORRECTION
          - UPDATE
          - UPDATE_CHANGE_INSERT
          - UPDATE_OVERRIDE
          default: CORRECTION
          example: CORRECTION
        title:
          type: string
          example: Example Title
        firstName:
          type: string
          example: example_value
        middleNames:
          type: string
          example: example_value
        lastName:
          type: string
          example: example_value
        knownAs:
          type: string
          example: example_value
        emailAddress:
          type: string
          format: email
          example: user@example.com
        maritalStatus:
          type: string
          example: example_value
    Assignment:
      type: object
      properties:
        assignmentId:
          type: integer
          description: Assignment identifier
          example: '500123'
        assignmentNumber:
          type: string
          description: Assignment number
          example: example_value
        assignmentType:
          type: string
          description: Assignment type
          enum:
          - E
          - C
          - A
          example: E
        primaryFlag:
          type: string
          description: Whether this is the primary assignment
          enum:
          - 'Y'
          - 'N'
          example: 'Y'
        jobId:
          type: integer
          description: Job identifier
          example: '500123'
        jobName:
          type: string
          description: Job name
          example: example_value
        positionId:
          type: integer
          description: Position identifier
          example: '500123'
        positionName:
          type: string
          description: Position name
          example: example_value
        gradeId:
          type: integer
          description: Grade identifier
          example: '500123'
        gradeName:
          type: string
          description: Grade name
          example: example_value
        organizationId:
          type: integer
          description: Organization identifier
          example: '500123'
        organizationName:
          type: string
          description: Organization name
          example: example_value
        locationId:
          type: integer
          description: Location identifier
          example: '500123'
        locationCode:
          type: string
          description: Location code
          example: example_value
        supervisorId:
          type: integer
          description: Supervisor person identifier
          example: '500123'
        payrollId:
          type: integer
          description: Payroll identifier
          example: '500123'
        employmentCategory:
          type: string
          description: Employment category
          enum:
          - FR
          - FT
          - PR
          - PT
          example: FR
        normalHours:
          type: number
          format: double
          description: Normal working hours
          example: 42.5
        frequency:
          type: string
          description: Hours frequency
          enum:
          - D
          - W
          - M
          - Y
          example: D
        effectiveStartDate:
          type: string
          format: date
          example: '2026-01-15'
        effectiveEndDate:
          type: string
          format: date
          example: '2026-01-15'
    Address:
      type: object
      properties:
        addressId:
          type: integer
          description: Address identifier
          example: '500123'
        addressType:
          type: string
          description: Address type
          example: example_value
        addressLine1:
          type: string
          example: example_value
        addressLine2:
          type: string
          example: example_value
        addressLine3:
          type: string
          example: example_value
        townOrCity:
          type: string
          example: example_value
        region1:
          type: string
          description: County/province
          example: example_value
        region2:
          type: string
          description: State
          example: example_value
        postalCode:
          type: string
          example: example_value
        country:
          type: string
          description: Country code
          example: example_value
        primaryFlag:
          type: string
          enum:
          - 'Y'
          - 'N'
          example: 'Y'
        dateFrom:
          type: string
          format: date
          example: '2026-01-15'
        dateTo:
          type: string
          format: date
          example: '2026-01-15'
    Phone:
      type: object
      properties:
        phoneId:
          type: integer
          example: '500123'
        phoneType:
          type: string
          description: Phone type
          enum:
          - W1
          - H1
          - M
          - WF
          - HF
          example: W1
        phoneNumber:
          type: string
          example: example_value
        dateFrom:
          type: string
          format: date
          example: '2026-01-15'
        dateTo:
          type: string
          format: date
          example: '2026-01-15'
    Organization:
      type: object
      properties:
        organizationId:
          type: integer
          description: Organization identifier
          example: '500123'
        name:
          type: string
          description: Organization name
          example: Example Title
        businessGroupId:
          type: integer
          description: Business group identifier
          example: '500123'
        dateFrom:
          type: string
          format: date
          description: Organization start date
          example: '2026-01-15'
        dateTo:
          type: string
          format: date
          description: Organization end date
          example: '2026-01-15'
        locationId:
          type: integer
          description: Location identifier
          example: '500123'
        type:
          type: string
          description: Organization type
          example: example_value
        internalExternalFlag:
          type: string
          enum:
          - INT
          - EXT
          example: INT
    Position:
      type: object
      properties:
        positionId:
          type: integer
          description: Position identifier
          example: '500123'
        name:
          type: string
          description: Position name
          example: Example Title
        jobId:
          type: integer
          description: Job identifier
          example: '500123'
        organizationId:
          type: integer
          description: Organization identifier
          example: '500123'
        effectiveStartDate:
          type: string
          format: date
          example: '2026-01-15'
        effectiveEndDate:
          type: string
          format: date
          example: '2026-01-15'
        status:
          type: string
          description: Position status
          example: example_value
        availabilityStatusId:
          type: integer
          example: '500123'
        businessGroupId:
          type: integer
          example: '500123'
        locationId:
          type: integer
          example: '500123'
    Payroll:
      type: object
      properties:
        payrollId:
          type: integer
          description: Payroll identifier
          example: '500123'
        payrollName:
          type: string
          description: Payroll name
          example: example_value
        periodType:
          type: string
          description: Payroll period type
          enum:
          - Calendar Month
          - Semi-Month
          - Bi-Week
          - Week
          - Lunar Month
          example: Calendar Month
        numberOfYears:
          type: integer
          description: Number of years defined
          example: 10
        firstPeriodEndDate:
          type: string
          format: date
          example: '2026-01-15'
        effectiveStartDate:
          type: string
          format: date
          example: '2026-01-15'
        effectiveEndDate:
          type: string
          format: date
          example: '2026-01-15'
        businessGroupId:
          type: integer
          example: '500123'
    PayrollRun:
      type: object
      properties:
        payrollActionId:
          type: integer
          description: Payroll action identifier
          example: '500123'
        payrollId:
          type: integer
          description: Payroll identifier
          example: '500123'
        actionType:
          type: string
          description: Action type (R=Run, Q=QuickPay, etc.)
          example: example_value
        actionStatus:
          type: string
          description: Action status
          enum:
          - C
          - E
          - M
          - P
          - U
          example: C
        effectiveDate:
          type: string
          format: date
          example: '2026-01-15'
        dateEarned:
          type: string
          format: date
          example: '2026-01-15'
        periodOfServiceId:
          type: integer
          example: '500123'
        businessGroupId:
          type: integer
          example: '500123'
    BenefitEnrollment:
      type: object
      properties:
        enrollmentResultId:
          type: integer
          description: Enrollment result identifier
          example: '500123'
        personId:
          type: integer
          description: Person identifier
          example: '500123'
        planId:
          type: integer
          description: Benefit plan identifier
          example: '500123'
        planName:
          type: string
          description: Plan name
          example: example_value
        optionId:
          type: integer
          description: Option identifier
          example: '500123'
        optionName:
          type: string
          description: Option name
          example: example_value
        coverageLevelCode:
          type: string
          description: Coverage level
          example: example_value
        effectiveStartDate:
          type: string
          format: date
          example: '2026-01-15'
        effectiveEndDate:
          type: string
          format: date
          example: '2026-01-15'
        enrollmentStartDate:
          type: string
          format: date
          example: '2026-01-15'
        enrollmentEndDate:
          type: string
          format: date
          example: '2026-01-15'
        benefitAmount:
          type: number
          format: double
          description: Benefit coverage amount
          example: 42.5
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            detail:
              type: string
          example: example_value
tags:
- name: Employee Management
  description: Employee and assignment management operations
- name: Organization
  description: HR organization and position management
- name: Payroll
  description: Payroll processing and run results
- name: Benefits
  description: Benefit enrollment management