UKG Payroll API

openapi: 3.0.3
info:
  title: UKG Pro HCM Accruals Payroll API
  description: The UKG Pro HCM API provides programmatic access to human capital management data including employees, personnel actions, benefits, payroll, performance, and organizational structure. Supports REST-based web services with Basic Authentication and API key authorization, enabling integrations with HR systems, payroll processors, benefits administrators, and analytics platforms. Base URL for US tenants is https://service.ultipro.com.
  version: '2.0'
  contact:
    name: UKG Developer Support
    url: https://developer.ukg.com
  termsOfService: https://www.ukg.com/legal/terms
  x-generated-from: documentation
servers:
- url: https://service.ultipro.com
  description: UKG Pro HCM API (US)
- url: https://service.ultipro.ca
  description: UKG Pro HCM API (Canada)
security:
- basicAuth: []
tags:
- name: Payroll
  description: Payroll data and check history
paths:
  /personnel/v2/employees/{employeeId}/pay-rates:
    get:
      operationId: getEmployeePayRates
      summary: UKG Pro HCM Get Employee Pay Rates
      description: Retrieve current and historical pay rates for an employee.
      tags:
      - Payroll
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
        description: Employee identifier
        example: EMP001
      responses:
        '200':
          description: Pay rate information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayRate'
              examples:
                getEmployeePayRates200Example:
                  summary: Default getEmployeePayRates 200 response
                  x-microcks-default: true
                  value:
                    employeeId: example-value
                    payType: Salary
                    basePay: 1.0
                    payCurrency: example-value
                    payFrequency: Weekly
                    effectiveDate: '2026-01-15'
        '404':
          description: Employee not found
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /personnel/v2/employees/{employeeId}/direct-deposits:
    get:
      operationId: getEmployeeDirectDeposits
      summary: UKG Pro HCM Get Employee Direct Deposits
      description: Retrieve direct deposit banking information for an employee.
      tags:
      - Payroll
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
        description: Employee identifier
        example: EMP001
      responses:
        '200':
          description: Direct deposit accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DirectDeposit'
              examples:
                getEmployeeDirectDeposits200Example:
                  summary: Default getEmployeeDirectDeposits 200 response
                  x-microcks-default: true
                  value:
                  - accountId: example-value
                    bankName: example-value
                    accountType: Checking
                    depositType: Amount
                    depositAmount: 1.0
                    priority: 1
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payroll/v1/pay-statements:
    get:
      operationId: listPayStatements
      summary: UKG Pro HCM List Pay Statements
      description: Retrieve pay statement history for employees.
      tags:
      - Payroll
      parameters:
      - name: employeeId
        in: query
        schema:
          type: string
        description: Filter by employee ID
        example: EMP001
      - name: startDate
        in: query
        schema:
          type: string
          format: date
        description: Start date for pay statement range
        example: '2026-01-01'
      - name: endDate
        in: query
        schema:
          type: string
          format: date
        description: End date for pay statement range
        example: '2026-03-31'
      responses:
        '200':
          description: List of pay statements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayStatement'
              examples:
                listPayStatements200Example:
                  summary: Default listPayStatements 200 response
                  x-microcks-default: true
                  value:
                  - statementId: example-value
                    employeeId: example-value
                    payPeriodStart: '2026-01-15'
                    payPeriodEnd: '2026-01-15'
                    payDate: '2026-01-15'
                    grossPay: 1.0
                    netPay: 1.0
                    federalTaxWithheld: 1.0
                    stateTaxWithheld: 1.0
                    socialSecurityTax: 1.0
                    medicareTax: 1.0
                    currency: example-value
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PayStatement:
      type: object
      description: Employee pay statement for a single pay period
      properties:
        statementId:
          type: string
          description: Pay statement identifier
          example: EMP001
        employeeId:
          type: string
          description: Employee identifier
          example: EMP001
        payPeriodStart:
          type: string
          format: date
          description: Pay period start date
          example: '2026-01-15'
        payPeriodEnd:
          type: string
          format: date
          description: Pay period end date
          example: '2026-01-15'
        payDate:
          type: string
          format: date
          description: Check or deposit date
          example: '2026-01-15'
        grossPay:
          type: number
          format: double
          description: Gross pay amount
          example: 1.0
        netPay:
          type: number
          format: double
          description: Net pay amount
          example: 1.0
        federalTaxWithheld:
          type: number
          format: double
          description: Federal income tax withheld
          example: 1.0
        stateTaxWithheld:
          type: number
          format: double
          description: State income tax withheld
          example: 1.0
        socialSecurityTax:
          type: number
          format: double
          description: Social Security tax withheld
          example: 1.0
        medicareTax:
          type: number
          format: double
          description: Medicare tax withheld
          example: 1.0
        currency:
          type: string
          description: Currency code
          example: USD
    PayRate:
      type: object
      description: Employee pay rate information
      properties:
        employeeId:
          type: string
          description: Employee identifier
          example: EMP001
        payType:
          type: string
          description: Pay type
          example: Salary
          enum:
          - Salary
          - Hourly
          - Commission
        basePay:
          type: number
          format: double
          description: Base pay amount
          example: 75000.0
        payCurrency:
          type: string
          description: Currency code
          example: USD
        payFrequency:
          type: string
          description: Pay frequency
          example: Bi-Weekly
          enum:
          - Weekly
          - Bi-Weekly
          - Semi-Monthly
          - Monthly
        effectiveDate:
          type: string
          format: date
          description: Effective date of pay rate
          example: '2026-01-15'
    DirectDeposit:
      type: object
      description: Employee direct deposit banking information
      properties:
        accountId:
          type: string
          description: Account identifier
          example: EMP001
        bankName:
          type: string
          description: Bank name
          example: First National Bank
        accountType:
          type: string
          description: Account type
          example: Checking
          enum:
          - Checking
          - Savings
        depositType:
          type: string
          description: Deposit distribution type
          example: Remainder
          enum:
          - Amount
          - Percentage
          - Remainder
        depositAmount:
          type: number
          format: double
          description: Deposit amount or percentage
          example: 1.0
        priority:
          type: integer
          description: Processing priority order
          example: 1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with service account credentials plus US-API-Key header