vocabulary: "1.0.0" info: provider: "Workday Payroll" description: >- Unified vocabulary and taxonomy for the Workday Payroll API surface. Covers the operational dimension (resources, actions, schemas, parameters, enums, and authentication exposed by the four Workday Payroll OpenAPI specs) and the capability dimension (Naftiko workflows, personas, business domains, namespaces, and binds that compose those APIs into customer-facing payroll workflows). created: "2026-05-03" modified: "2026-05-03" tags: - Workday - Payroll - Compensation - Human Resources - Tax - Compliance # --------------------------------------------------------------------------- # OPERATIONAL DIMENSION (extracted from openapi/*.yml) # --------------------------------------------------------------------------- operational: apis: - name: Workday Payroll API namespace: payroll version: v1 baseUrl: https://api.workday.com/payroll/v1 status: active spec: openapi/workday-payroll-payroll-openapi.yml description: >- Core API for managing payroll processes including pay run lifecycle, pay groups, worker payroll details, earnings, and deductions. tags: - Compensation - Deductions - Earnings - Pay Runs - Payroll - name: Workday Payroll Results API namespace: payroll-results version: v1 baseUrl: https://api.workday.com/payroll-results/v1 status: active spec: openapi/workday-payroll-payroll-results-openapi.yml description: >- Read-only API for retrieving payroll calculation results, payments, payment elections, and worker payslips. tags: - History - Payments - Payroll Results - Reporting - name: Workday Payroll Input API namespace: payroll-input version: v1 baseUrl: https://api.workday.com/payroll-input/v1 status: active spec: openapi/workday-payroll-payroll-input-openapi.yml description: >- API for submitting payroll input data including one-time payments, retroactive adjustments, supplemental earnings, batch input, and time off. tags: - Adjustments - One-Time Payments - Payroll Input - Supplemental Earnings - name: Workday Payroll Tax API namespace: tax version: v1 baseUrl: https://api.workday.com/tax/v1 status: active spec: openapi/workday-payroll-tax-openapi.yml description: >- API for managing tax withholdings, W-4 and state tax elections, tax jurisdictions, tax filings, and pay-run tax results. tags: - Compliance - Tax - Tax Filing - Withholdings resources: # Workday Payroll API - name: pay-runs api: payroll description: Payroll processing run for a pay group covering a defined pay period. actions: [list, get, create, update, calculate, complete] - name: pay-groups api: payroll description: Organizational unit grouping workers for payroll processing. actions: [list, get] - name: pay-group-workers api: payroll description: Workers belonging to a pay group. actions: [list] - name: worker-payroll-details api: payroll description: Worker-level payroll configuration and pay setup. actions: [get] - name: earnings api: payroll description: Worker earnings records associated with pay periods. actions: [list, get] - name: deductions api: payroll description: Worker deduction records associated with pay periods. actions: [list, get] - name: earning-codes api: payroll description: Configuration codes classifying earning types. actions: [list] - name: deduction-codes api: payroll description: Configuration codes classifying deduction types. actions: [list] # Workday Payroll Results API - name: payslips api: payroll-results description: Worker pay statements with itemized earnings, deductions, taxes, and net pay. actions: [list, get] - name: payments api: payroll-results description: Payment transactions generated by a pay run. actions: [list, get] - name: payment-elections api: payroll-results description: Worker direct-deposit and payment-method designations. actions: [list] - name: payroll-results api: payroll-results description: Aggregated calculation results for a pay run. actions: [get] - name: worker-results api: payroll-results description: Per-worker payroll calculation results within a pay run. actions: [list, get] # Workday Payroll Input API - name: one-time-payments api: payroll-input description: Non-recurring payments such as spot bonuses or relocation allowances. actions: [list, get, create, update, delete] - name: adjustments api: payroll-input description: Corrections, retroactive pay, reversals, and reclassifications. actions: [list, get, create] - name: supplemental-earnings api: payroll-input description: Bonuses, commissions, stipends, and allowances submitted outside the regular cycle. actions: [list, get, create, delete] - name: input-batches api: payroll-input description: Bulk payroll input submissions containing multiple input records. actions: [list, get, create] - name: time-off-inputs api: payroll-input description: Leave and absence records submitted to payroll processing. actions: [list, create] # Workday Payroll Tax API - name: tax-withholdings api: tax description: Worker tax withholding configurations across jurisdictions. actions: [list, get, update] - name: tax-elections api: tax description: Worker filing status and withholding instructions (W-4 and equivalents). actions: [list, get, create] - name: tax-jurisdictions api: tax description: Federal, state, local, and other authorities that levy payroll taxes. actions: [list, get] - name: tax-filings api: tax description: Periodic statutory tax filings and compliance reports. actions: [list, get] - name: tax-results api: tax description: Tax calculation results computed for a pay run. actions: [list] - name: tax-summaries api: tax description: Worker year-to-date tax summaries. actions: [get] actions: - verb: list method: GET pattern: query description: Retrieve a paginated collection of a resource. - verb: get method: GET pattern: read description: Retrieve a single resource by identifier. - verb: create method: POST pattern: write description: Create a new resource. - verb: update method: PATCH pattern: write description: Partially update an existing resource. - verb: delete method: DELETE pattern: destructive description: Remove a resource. - verb: calculate method: POST pattern: write description: Trigger payroll calculations for a pay run. - verb: complete method: POST pattern: write description: Finalize a pay run after calculations succeed. schemas: core: - PayRun - PayGroup - PayPeriod - WorkerPayrollDetails - Earning - EarningCode - EarningCodeRef - Deduction - DeductionCode - DeductionCodeRef - CalculationStatus results: - Payslip - PayslipEarningLine - PayslipDeductionLine - PayslipTaxLine - Payment - PaymentElection - PayRunResult - WorkerResult input: - OneTimePayment - Adjustment - SupplementalEarning - InputBatch - InputRecord - TimeOffInput - CreateOneTimePaymentRequest - CreateAdjustmentRequest - CreateSupplementalEarningRequest - CreateInputBatchRequest - CreateTimeOffInputRequest tax: - TaxWithholding - TaxElection - TaxJurisdiction - TaxJurisdictionRef - TaxFiling - TaxResult - WorkerTaxSummary - CreateTaxElectionRequest - UpdateTaxWithholdingRequest references: - WorkerRef - TaxJurisdictionRef - EarningCodeRef - DeductionCodeRef collections: - PayRunCollection - PayGroupCollection - WorkerCollection - EarningCollection - DeductionCollection - EarningCodeCollection - DeductionCodeCollection - PayslipCollection - PaymentCollection - PaymentElectionCollection - WorkerResultCollection - OneTimePaymentCollection - AdjustmentCollection - SupplementalEarningCollection - InputBatchCollection - TimeOffInputCollection - TaxWithholdingCollection - TaxElectionCollection - TaxJurisdictionCollection - TaxFilingCollection - TaxResultCollection errors: - Error parameters: pagination: - name: limit in: query description: Maximum items per page (1-100, default 20). - name: offset in: query description: Zero-based offset into the collection (default 0). identifiers: - payRunId - payGroupId - workerId - paymentId - payslipId - adjustmentId - earningId - batchId - withholdingId - electionId - jurisdictionId - filingId filters: - name: status description: Filter by lifecycle state (e.g., Draft, InProgress, Completed). - name: fromDate description: Inclusive lower bound (ISO 8601 date). - name: toDate description: Inclusive upper bound (ISO 8601 date). - name: adjustmentType description: Filter adjustments by Correction, Retroactive, Reversal, or Reclass. - name: level description: Tax jurisdiction level (Federal, State, Local, Other). - name: country description: ISO country code for jurisdiction or filing scope. - name: taxYear description: Calendar year of tax data. - name: filingType description: Quarterly, Annual, or Amendment filing type. - name: jurisdiction description: Filter results by tax jurisdiction identifier. enums: pay_run_states: schema: PayRun.status values: [Draft, InProgress, Completed, Cancelled] run_categories: schema: PayRun.runCategory values: [Regular, OffCycle, OnDemand] calculation_states: schema: CalculationStatus.status values: [Queued, Processing, Completed, Failed] earning_types: schema: EarningCode.type values: [Regular, Overtime, Bonus, Commission, Holiday, PTO, Supplemental, Other] deduction_types: schema: DeductionCode.type values: [Benefit, Retirement, Garnishment, Tax, Voluntary, Other] deduction_frequencies: schema: Deduction.frequency values: [PerPayPeriod, Monthly, Annual, OneTime] payment_methods: schema: WorkerPayrollDetails.paymentMethod values: [DirectDeposit, Check, Wire] payment_states: schema: Payment.status values: [Pending, Processed, Settled, Failed, Voided] account_types: schema: PaymentElection.accountType values: [Checking, Savings] distribution_types: schema: PaymentElection.distributionType values: [Amount, Percentage, Remainder] one_time_payment_states: schema: OneTimePayment.status values: [Pending, Approved, Processed, Rejected] adjustment_types: schema: Adjustment.adjustmentType values: [Correction, Retroactive, Reversal, Reclass] supplemental_earning_types: schema: SupplementalEarning.type values: [Bonus, Commission, Stipend, Allowance, Other] input_batch_states: schema: InputBatch.status values: [Pending, Validating, Validated, Processing, Completed, Failed] input_record_types: schema: InputRecord.inputType values: [Earning, Deduction, TimeOff] time_off_states: schema: TimeOffInput.status values: [Pending, Approved, Processed] tax_types: schema: TaxWithholding.taxType values: [FederalIncome, StateIncome, LocalIncome, SocialSecurity, Medicare, FUTA, SUTA, Other] filing_statuses: schema: TaxElection.filingStatus values: [Single, MarriedFilingJointly, MarriedFilingSeparately, HeadOfHousehold, QualifyingWidower] tax_form_types: schema: TaxElection.formType values: [W4, StateWithholding, LocalWithholding] tax_jurisdiction_levels: schema: TaxJurisdiction.level values: [Federal, State, Local, Other] tax_filing_types: schema: TaxFiling.filingType values: [Quarterly, Annual, Amendment] tax_filing_states: schema: TaxFiling.status values: [Draft, Pending, Filed, Accepted, Rejected] tax_election_states: schema: TaxElection.status values: [Active, Superseded, Voided] authentication: schemes: - name: bearerAuth type: http scheme: bearer bearerFormat: JWT description: >- OAuth 2.0 bearer token issued by Workday authentication. Sent via the Authorization header as `Bearer {token}`. appliesTo: - payroll - payroll-results - payroll-input - tax scopes: - note: >- The OpenAPI specs declare bearerAuth without enumerating scopes. Workday provisions per-API security scopes via the Workday tenant's Integration System User and OAuth client configuration. # --------------------------------------------------------------------------- # CAPABILITY DIMENSION (extracted from capabilities/*.yaml) # --------------------------------------------------------------------------- capability: workflows: - name: Workday Payroll Processing file: capabilities/payroll-processing.yaml description: >- Top-level orchestration capability composing the four shared payroll sub-capabilities into a unified surface for end-to-end payroll cycles. consumes: - payroll - payroll-results - payroll-input - payroll-tax toolCount: 94 personas: - hr-administrator - payroll-specialist - finance-manager - compliance-officer domains: - Payroll Processing - Compensation - Tax Compliance - Reporting - name: Workday Payroll API file: capabilities/shared/payroll.yaml description: >- Core payroll capability exposing pay run lifecycle, pay groups, worker payroll details, earnings, and deductions. consumes: - payroll toolCount: 14 personas: - hr-administrator - payroll-specialist domains: - Payroll Processing - Compensation - Human Resources - name: Workday Payroll Results API file: capabilities/shared/payroll-results.yaml description: >- Read-only capability surfacing payslips, payments, payment elections, and aggregated pay run results. consumes: - payroll-results toolCount: 8 personas: - payroll-specialist - finance-manager - worker domains: - Payroll Results - Payments - Reporting - name: Workday Payroll Input API file: capabilities/shared/payroll-input.yaml description: >- Capability for submitting one-time payments, adjustments, supplemental earnings, input batches, and time off into payroll processing. consumes: - payroll-input toolCount: 16 personas: - hr-administrator - payroll-specialist domains: - Payroll Input - Compensation - name: Workday Payroll Tax API file: capabilities/shared/payroll-tax.yaml description: >- Capability for managing tax withholdings, W-4 and state elections, jurisdictions, filings, and pay-run tax results. consumes: - payroll-tax toolCount: 11 personas: - payroll-specialist - compliance-officer - worker domains: - Tax Compliance - Withholdings - Reporting personas: - id: hr-administrator name: HR Administrator description: >- Owns worker data, pay group setup, and end-to-end payroll cycle execution. workflows: - Workday Payroll Processing - Workday Payroll API - Workday Payroll Input API - id: payroll-specialist name: Payroll Specialist description: >- Operates payroll runs, submits adjustments and supplemental earnings, and reconciles results before payments are released. workflows: - Workday Payroll Processing - Workday Payroll API - Workday Payroll Results API - Workday Payroll Input API - Workday Payroll Tax API - id: finance-manager name: Finance Manager description: >- Reviews payroll results, payment runs, and downstream postings to the general ledger. workflows: - Workday Payroll Processing - Workday Payroll Results API - id: compliance-officer name: Compliance Officer description: >- Manages tax elections, monitors withholdings, and coordinates statutory tax filings. workflows: - Workday Payroll Processing - Workday Payroll Tax API - id: worker name: Worker description: >- Employee accessing their own payslips, payment elections, and tax summaries via self-service surfaces. workflows: - Workday Payroll Results API - Workday Payroll Tax API domains: - name: Payroll Processing description: Pay run lifecycle, pay groups, calculations, completion. resources: [pay-runs, pay-groups, pay-group-workers, worker-payroll-details] workflows: [Workday Payroll Processing, Workday Payroll API] - name: Compensation description: Earnings, deductions, supplemental pay, and one-time payments. resources: - earnings - deductions - earning-codes - deduction-codes - one-time-payments - supplemental-earnings - adjustments workflows: - Workday Payroll API - Workday Payroll Input API - name: Payroll Input description: Bulk and discrete inputs feeding payroll calculations. resources: [input-batches, time-off-inputs, one-time-payments, supplemental-earnings, adjustments] workflows: [Workday Payroll Input API] - name: Payroll Results description: Aggregated and per-worker calculation outputs from pay runs. resources: [payroll-results, worker-results] workflows: [Workday Payroll Results API] - name: Payments description: Payment transactions and worker payment elections. resources: [payments, payment-elections] workflows: [Workday Payroll Results API] - name: Tax Compliance description: Tax withholdings, elections, jurisdictions, and filings. resources: [tax-withholdings, tax-elections, tax-jurisdictions, tax-filings, tax-results, tax-summaries] workflows: [Workday Payroll Tax API, Workday Payroll Processing] - name: Withholdings description: Worker-level federal, state, and local tax withholding setup. resources: [tax-withholdings, tax-elections] workflows: [Workday Payroll Tax API] - name: Reporting description: Payslips and historical pay-data surfaces for workers and finance. resources: [payslips, worker-results, tax-summaries] workflows: [Workday Payroll Results API, Workday Payroll Tax API] - name: Human Resources description: Worker-centric payroll setup data shared with HCM systems. resources: [worker-payroll-details, pay-group-workers] workflows: [Workday Payroll API] namespaces: consumed: - name: payroll baseUri: https://api.workday.com/payroll/v1 api: Workday Payroll API - name: payroll-results baseUri: https://api.workday.com/payroll-results/v1 api: Workday Payroll Results API - name: payroll-input baseUri: https://api.workday.com/payroll-input/v1 api: Workday Payroll Input API - name: payroll-tax baseUri: https://api.workday.com/tax/v1 api: Workday Payroll Tax API rest: - name: payroll-processing-api port: 8080 workflow: Workday Payroll Processing - name: payroll-rest port: 8100 workflow: Workday Payroll API - name: payroll-results-rest port: 8101 workflow: Workday Payroll Results API - name: payroll-input-rest port: 8102 workflow: Workday Payroll Input API - name: payroll-tax-rest port: 8103 workflow: Workday Payroll Tax API mcp: - name: payroll-processing-mcp port: 9090 transport: http workflow: Workday Payroll Processing - name: payroll-mcp port: 9100 transport: http workflow: Workday Payroll API - name: payroll-results-mcp port: 9101 transport: http workflow: Workday Payroll Results API - name: payroll-input-mcp port: 9102 transport: http workflow: Workday Payroll Input API - name: payroll-tax-mcp port: 9103 transport: http workflow: Workday Payroll Tax API binds: - variable: WORKDAY_PAYROLL_TOKEN namespace: env description: >- OAuth 2.0 bearer token used by every Workday Payroll consumer to authenticate against the Workday tenant. requiredBy: - Workday Payroll Processing - Workday Payroll API - Workday Payroll Results API - Workday Payroll Input API - Workday Payroll Tax API # --------------------------------------------------------------------------- # CROSS-REFERENCE — operational resource → operations → workflows → personas # --------------------------------------------------------------------------- crossReference: - resource: pay-runs api: payroll operations: [list, get, create, update, calculate, complete] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Processing] - resource: pay-groups api: payroll operations: [list, get] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Processing] - resource: pay-group-workers api: payroll operations: [list] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Processing, Human Resources] - resource: worker-payroll-details api: payroll operations: [get] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Processing, Human Resources] - resource: earnings api: payroll operations: [list, get] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [payroll-specialist] domains: [Compensation] - resource: deductions api: payroll operations: [list, get] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [payroll-specialist] domains: [Compensation] - resource: earning-codes api: payroll operations: [list] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Compensation] - resource: deduction-codes api: payroll operations: [list] workflows: [Workday Payroll API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Compensation] - resource: payslips api: payroll-results operations: [list, get] workflows: [Workday Payroll Results API, Workday Payroll Processing] personas: [payroll-specialist, worker] domains: [Reporting] - resource: payments api: payroll-results operations: [list, get] workflows: [Workday Payroll Results API, Workday Payroll Processing] personas: [payroll-specialist, finance-manager] domains: [Payments] - resource: payment-elections api: payroll-results operations: [list] workflows: [Workday Payroll Results API, Workday Payroll Processing] personas: [worker, payroll-specialist] domains: [Payments] - resource: payroll-results api: payroll-results operations: [get] workflows: [Workday Payroll Results API, Workday Payroll Processing] personas: [payroll-specialist, finance-manager] domains: [Payroll Results] - resource: worker-results api: payroll-results operations: [list, get] workflows: [Workday Payroll Results API, Workday Payroll Processing] personas: [payroll-specialist, finance-manager] domains: [Payroll Results, Reporting] - resource: one-time-payments api: payroll-input operations: [list, get, create, update, delete] workflows: [Workday Payroll Input API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Input, Compensation] - resource: adjustments api: payroll-input operations: [list, get, create] workflows: [Workday Payroll Input API, Workday Payroll Processing] personas: [payroll-specialist] domains: [Payroll Input, Compensation] - resource: supplemental-earnings api: payroll-input operations: [list, get, create, delete] workflows: [Workday Payroll Input API, Workday Payroll Processing] personas: [payroll-specialist, hr-administrator] domains: [Payroll Input, Compensation] - resource: input-batches api: payroll-input operations: [list, get, create] workflows: [Workday Payroll Input API, Workday Payroll Processing] personas: [payroll-specialist] domains: [Payroll Input] - resource: time-off-inputs api: payroll-input operations: [list, create] workflows: [Workday Payroll Input API, Workday Payroll Processing] personas: [hr-administrator, payroll-specialist] domains: [Payroll Input] - resource: tax-withholdings api: tax operations: [list, get, update] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [payroll-specialist, compliance-officer] domains: [Tax Compliance, Withholdings] - resource: tax-elections api: tax operations: [list, get, create] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [worker, payroll-specialist, compliance-officer] domains: [Tax Compliance, Withholdings] - resource: tax-jurisdictions api: tax operations: [list, get] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [compliance-officer, payroll-specialist] domains: [Tax Compliance] - resource: tax-filings api: tax operations: [list, get] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [compliance-officer] domains: [Tax Compliance] - resource: tax-results api: tax operations: [list] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [payroll-specialist, compliance-officer, finance-manager] domains: [Tax Compliance, Reporting] - resource: tax-summaries api: tax operations: [get] workflows: [Workday Payroll Tax API, Workday Payroll Processing] personas: [worker, payroll-specialist] domains: [Tax Compliance, Reporting]