Oracle EBS Human Resources API

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: [email protected]
    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: [email protected]
                      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: [email protected]
                  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: [email protected]
                    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: [email protected]
                    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: [email protected]
                  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: [email protected]
                    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 A

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oracle-e-business-suite/refs/heads/main/openapi/human-resources-api.yml