| Workday Task | Endpoint |
|---|---|
| View Payroll Input by Worker(s) | GET /payrollInputs |
| Add Payroll Input by Worker | POST /payrollInputs |
| View Payroll Input | GET /payrollInputs/{ID} |
| Delete Payroll Input | DELETE /payrollInputs/{ID} |
| Edit Payroll Input | PATCH /payrollInputs/{ID} |
| Domain | Access |
|---|---|
| Worker Data: Payroll Public API (Payroll Input) | This domain provides the necessary access to view, create, edit, delete payroll input through the REST API. This access is intended for integrations or users, such as Payroll Administrators, who are responsible for managing payroll inputs for the workforce. |
| Self-Service: Payroll Public API (Payroll Input) | This domain is for enabling workers to view, create, and edit their own payroll input through the REST API. It is typically used to support self-service interfaces where employees submit payroll-related information through the API. Note: If you only have access to this domain, additional Pay Component Segment Security configuration is required. |
| Feature | Description |
|---|---|
| Gross-up Calculations | Gross-ups are only possible for pay components with a related calculation type that supports gross-up. If the required calculation type is missing from the pay component, you can’t use this API to gross up the amount. Not all pay components support gross-up. |
| On-Demand Payments | When a pay input you created with the API is active for the relevant period and worker, Workday automatically picks it up when an on-demand payment calculation runs. |
| Pay Components | A worker's eligibility and the pay component's configuration determine if you can process a payroll input. When you add a one-time, override payroll input, Workday considers this an intentional entry and ignores the standard worker eligibility rules configured on the pay component. Example: A "Car Allowance" is configured with an eligibility rule for only Directors. However, a Manager needs extensive one-month travel for a project, and leadership approves a one-time Car Allowance exception. A payroll administrator can add an override payroll input for this period. Workday processes the Car Allowance for the Manager, overriding the standard "Director" eligibility rule, as the manual input is honored as a deliberate exception. |
| Payroll Run Categories | The run category determines which type of payroll run processes a pay input. If you don’t specify the run category when creating a pay input through the API, Workday defaults to the regular run category, excluding it from off-cycle runs. |
| Retroactive Processing | To process retroactive pay, submit a standard pay input with dates corresponding to a prior, completed period. Workday automatically calculates the differences. Since you can't modify the original locked pay input, there is no "retro" endpoint or parameter. A retro calculation requires the creation of a new pay input. |
| Staffing | When you're managing pay inputs through the REST API and a worker is terminated, those ongoing inputs will keep getting picked up by future payroll runs until you explicitly set an end date for them. Note: We highly recommend that an integration using this API actively monitors for terminations and runs PATCH requests to set end dates on all ongoing inputs for terminated workers. |
| Workers with Multiple Positions | The position field is required on inputs for position-based pay components (those configured with the Position worktag). For these components, the API doesn't default to the worker's primary position. Integrations must resolve the applicable position before submitting a pay input. Omitting this field for position-based pay components will throw an error. For worker-based pay components (those without the Position worktag), the position field has no functional effect and can be omitted. |
| Endpoints | Error Code | Cause |
|---|---|---|
PATCH /payrollInputs/{inputId}, DELETE /payrollInputs/{inputId} | A140 | You can't delete or edit an input used in a completed payroll result. You must specify an end date on the existing input and then create a new one, as you can’t delete or edit the original input. |
PATCH /payrollInputs/{inputId}, DELETE /payrollInputs/{inputId} | A553 / A557 | You can only edit the end date. Before attempting a PATCH request, verify the fieldEditability parameter. |
PATCH /payrollInputs/{inputId}, DELETE /payrollInputs/{inputId} | A556 | You can't create, update, or delete inputs that were created as external payroll inputs. |
PATCH /payrollInputs/{inputId}, DELETE /payrollInputs/{inputId} | A121 | The end date corresponds to a completed pay period end date or a locked result period end date. |
POST /payrollInputs | A116 | The pay component is missing required worktags. |
| Feature / Use Case | payrollInputs REST API | Import_Payroll_Input SOAP API | Recommendation |
|---|---|---|---|
| Transaction Type | Synchronous (Real-Time). | Asynchronous (Batch). | REST for single, immediate transactions. |
| Batch ID Support | Not Supported. | Supported and Required. | Use SOAP for any process requiring bulk validation, administration, or deletion with a Batch ID. |
| Payload Flexibility | Supported. | Not Supported. | Use REST when you need to submit detailed input types like Units that are not available in the SOAP service. |
| Error Handling | Per-transaction. | Batch-level. | REST requires record-by-record error handling. SOAP allows for easier management of load errors at the batch level. |
| Error | Error Code | Cause and Solution |
|---|---|---|
| Authorization Error | HTTP 403 Forbidden | Cause: The Integration System User (ISU) making the API call lacks the necessary security permissions. Solution: Grant the ISU Get and Put access to the Worker Data: Payroll Public API (Payroll Input) security domain in the Core Payroll functional area. Ensure the security policy changes are activated. |
| Validation Error on Pay Component | Varies (Application Validation Error) | Cause: The specified pay component (Earning or Deduction) isn’t configured to accept an external input. Solution: In the Workday UI, verify the pay component's configuration. Ensure the Input Amount Allowed? checkbox is selected on the Edit Earning or Edit Deduction task for the pay component you want to add pay input for. Also confirm that the worker meets the eligibility criteria for the pay component for the specified dates. |
| Duplicate Payroll Input Created | N/A (Successful POST) | Cause: An attempt to update an existing record was made using a POST request instead of a PATCH request to the specific record's URL. The API successfully creates a new record as instructed, leading to duplicates. Solution: To update an existing payroll input, you must use a |
fieldEditability | Cause: Attempting to PATCH a field that isn't editable. Solution: Check | |
| Delete Blocked by Completed Result | Cause: You can’t DELETE an input that's been used in a completed result. Solution: You must end date the existing input and create a new pay input. | |
| Off-Cycle Payment Lock | Cause: You can’t update or delete an input tied to an off-cycle payment. Solution: You must set an end date on the existing input and create a new pay input. | |
| Worktags | 422 | Cause: There are missing or invalid worktags. Solution: Specify the missing worktags or update invalid worktags. The pay component has worktag requirements. |
| Worker Country Mismatch | Cause: You run a POST request and the pay component is configured for a different country than the worker's. Solution: Update the pay component with the Country field on the Edit Earning or Edit Deduction task. |