Payroll systems · UKG
UKG Pro
UKG's own documentation covers employees, pay statements, hours and webhooks through the API. Access: Customer service account.
Integration method grade B · field-level docs publicly readable · last verified 2026-09-11 · UKG Pro — Deductions History Effective Change Dates
What the API lets you do
| Question | Answer | Conf | What the documentation says |
|---|---|---|---|
| How do you get API access? | Customer service account | D | Published APIs are available to customers and third parties; some resources, such as Benefits Integration, are for official partners only. Source |
| Can you read employees and pay rates? | Yes — REST read | D | GET /personnel/v1/employee-employment-details returns employment data including hourlyPayRate, annualSalary, jobTitle and originalHireDate. Source |
| Can you read pay statements? | Yes — Pay Statements API | D | POST /payroll/v1/employees/pay-statements returns earnings, deductions, taxes and net pay distribution for a date range. Source |
| Can you write a deduction? | Unverified — read only found | U | Only deduction read endpoints were found; an earnings import exists but no deduction import. |
| Can you write a direct deposit account? | Unverified — read only found | U | GET /payroll/v1/direct-deposit is documented; no write endpoint was found. |
| Can you read W-2s? | Unverified | U | Only tax configuration endpoints were found; no W-2 document API. |
| Can you read hours worked? | Yes — Time Management OData | D | OData service returns punches, regular and overtime hours and timesheet totals; requires a Time Management web service account. Source |
| Does it push change events? | Yes — UKG Webhooks | D | Subscribe to Pro HCM and WFM events, delivered near real time with HMAC signing; a 'Webhooks Premium' tier is referenced. Source |
| How does an integration authenticate? | Basic auth + API keys | D | Basic authentication with a web service account, a user API key and the US-CUSTOMER-API-KEY header. Source |
Deduction write, in detail
For benefits, HSA/FSA and 401(k) integrations. 3 of 10 fields are unverified — no public source states the answer. Compare every system on the deduction write detail page.
| Field | Value | Conf | Note — and what a correct answer needed |
|---|---|---|---|
| Deduction read | Yes — API | D | A Deduction Code API at /configuration/v1/deductions returns deduction configuration. A separate Open Enrollment Employee Deductions API sits at /personnel/v1/open-enrollment-emp-deductions. Deduction change history is readable at /personnel/v1/deduction-history-effective-change-dates. |
| Deduction write | Import only — does not drive payroll | D | The only documented deduction write is the Third-Party Pay Service, at payroll/v1/thirdpartypay('ID')/Deductions. Its stated purpose is to import payroll summary information into UKG Pro so employees can view a pay summary for payroll that was NOT processed in UKG Pro. It records what another system already did; it does not instruct UKG payroll to take a deduction. Sold in the same column as a real write, these are not the same operation. |
| Pre-tax vs post-tax at write | Unverified | U | Not represented in any endpoint we have read. The deduction-history fieldName enum spans 13 fields — changeReason, benefitStartDate, benefitStopDate, benefitOption, employeeAmount, employeeBenefitAmount, employeeGoalAmount, eoiDesiredAmount, eoiDesiredCalcRateOrPercent, declinedByCarrier, declinedByCarrierReason, waiveReason, deductionStartDate, deductionStopDate — and none carries tax treatment. We have not read the full Deduction Code API schema, so this is an absence in the endpoints we checked rather than a confirmed absence from the product. |
| Amount vs percent | Both — amount and rate-or-percent | D | The deduction-history fieldName enum carries amount fields (employeeAmount, employeeBenefitAmount, employeeGoalAmount) alongside eoiDesiredCalcRateOrPercent, so a rate-or-percent concept exists in the model. The Third-Party Pay write, by contrast, takes only numeric amounts and allows negatives — no percentage notation. |
| Effective dating | Yes — richest model assessed | D | The only system assessed with a dedicated per-field effective-change-date endpoint: /personnel/v1/deduction-history-effective-change-dates returns employeeId, companyId, deductionCode, effectiveDate, fieldValueDataType, fieldValue, fieldValueDate, fieldValueNumber and changeReason. deductionStartDate, deductionStopDate, benefitStartDate and benefitStopDate are separately queryable. You can reconstruct when any tracked field changed and why. |
| Retro adjustment | Unverified | U | The history endpoint reads when a change took effect, including past changes, but no documented operation writes a correction to a period that already ran. Reading history is not amending it. |
| Employer contribution | Amount only, import path | D | The Third-Party Pay Deductions resource carries EmployerDeductionAmount and YtdEmployerDeductionAmount alongside the employee equivalents. So the employer side is expressible as a figure — but only on the import path, and with no match formula, tiers or annual maximum. |
| Code taxonomy shape | Configuration-driven | D | A dedicated Deduction Code configuration endpoint implies per-tenant codes rather than a fixed vendor taxonomy. deductionCode is a string of up to 25 characters on the Third-Party Pay write and accepts list-form queries ([ded1,ded2]) on the history endpoint. |
| Auth model | Basic auth + two API keys | D | Basic authentication with a service account for the core REST APIs, plus both a Customer API key and a User API key. The deduction-history reference shows a US-Customer-Api-Key header with base64-encoded credentials, and requires a service account holding View permission on the Personnel Integration API endpoints. Onboarding and recruiting APIs use an authorization token instead. |
| Data freshness | Unverified | U | No latency, batch cadence or SLA stated on any deduction endpoint we read. |
D vendor-documented · U unverified · — not offered. See every payroll system side by side in the Payroll API Capability Matrix.