Description
The Payroll Output v1 API is set to be decommissioned as of June 30th 2021. Developers should be aware that in the time leading up to the decommission day, the API may see degraded performance. Developers who already consuming the Payroll Output v1 APIs for ADP Clients on ADP Workforce Now, ADP Vantage and ADP Enterprise HCM should to update integration and leverage the Payroll Output v2 API. This chapter provides change highlights between Payroll Output v1 API and Payroll Output v2 API.
Change Highlights
Compare to Payroll Output v1 API, the Payroll Output v2 API has reduced response payload, which will help improve API response time. In order to reduce impact to payroll output v1 API consumers, the schema between v1 and v2 largely remains the same.
| Item | Description | JSON Sample |
| New Event Notification(EER) |
New status in the event notification to inform consumers that the payroll cannot process. EER = Data in Error (the payroll cannot process because there are data errors) |
N/A |
| New Event Notifications (PVI, NTI) |
Newstatuses (PVI and NTI) in the event notification will be published to Infolink to inform consumers that the Summary Totals are ready (Pay, Acc and Detail still being generated and are not ready for consumption). PVI = The payroll is now in Preview complete status. Payroll Output v2 API for default, edit errors, and payroll summary are available for retrieval, however the pay, acc and detail level APIs are still being generated. PVC = The payroll is in Preview Complete status and all Payroll Output v2 API data is available for retrieval. NTI = The payroll is now in Net Complete status. Payroll Output v2 API for default, edit errors, and payroll summary are available for retrieval, however the pay, acc and detail level APIs are still being generated NTC = The payroll is in Net Complete status and all Payroll Output v2 API data is available for retrieval. |
N/A |
| Pay Date/Start Date |
Pay Date/Start Date will only be populated for PR/OS/QS activities. Pay Date/Start date data is invalid for adjustment type runs. |
N/A |
| Limit associates or use streaming version of Turbo |
For the levels Pay/Details/PayDetails/Acc/Acc-all, if the user does not specify skip/top when using the non-streaming version, and if the payroll has more than 2000 associates, Payroll Output v2 will send the user an error message asking to either use the streaming version of the API or use the skip/top parameters. |
N/A |
| Event Notification API |
With the eventuality of 2 services running on each LPAR (Payroll Output v1 & v2 API), the Event Notification API will be sending notifications from both services. A configuration tag (NotificationSource) is being added to the Event Notification API to distinguish messages between Payroll Output v1 & v2. Partners must determine which notification they will consume based on this tag. |
Event Notification API example |
| Error Level |
The error count at summary level will contain 3 separate counts, one for company level errors one for employee level errors and the other for crossfoot errors. If file numbers are available it will be treated as employee error otherwise will be treated as a company error. Errors in error level will contain both employee and company errors |
Error Counts Sample json |
| Crossfoot Errors |
A configuration tag for Crossfoot error counts will be added to the Summary Level. Tags will only be present if crossfoot errors exist. |
tagCode: "Crossfoot Errors" |
| Dropeed Pay Level | A configuration tag for Dropped Pay counts will be added to the Summary Level. Tags will only be present if dropped pay condition exist. Dropped Pay Level will hold all Dropped Pay employees and will not be present in the associate payment (Details) level. | tagCode: "Dropped pays" |
| Omit itemID | Removing all unnecessary itemIDs - only keeping required itemIDs at payrollOutput, payrollSummary, and associatePayment levels only | Payroll Output v2 Sample |
| Omit countryCode |
Removing countryCode from jurisdiction codes as this is tied to the company. We are currently investigating adding country code to payrollGroupCode node. |
Payroll Output v2 Sample |
| Omit currencyCode | Removing currencyCode on all dollar amounts. We are currently investigating adding currency code to payrollGroupCode node which identifies the company as only one currency is supported for a transaction for a given company. | Payroll Output v2 Sample |
| Omit schemeCode | Removing schemeCode from section IDs (Earnings, Deductions, Memos, Statutory Deductions) as it is self evident by the section the entry is in | Payroll Output v2 Sample |
| Query Updates |
Level=payroll and Level=payDetails can be queried using one of the below 3 combinations: 1. itemID 2. ADPX-RegionCode (header), payrollGroupCode.codeValue, processChronNbr 3. ADPX-RegionCode (header), payrollGroupCode.codeValue, payrollProcessingJobID |
N/A |
| $Select Critera | $skip and $top will be supported | N/A |
| Header Changes |
1. Region should be provided in the ADPX-RegionCode header rather than the filter 2. SORContext header is no longer used |
N/A |
| Changes to Local Taxes in v2 |
1. statutoryJurisdiction/administrativeLevel1 and the state associated with the local code was added to all levels for Local Income Tax, Head Tax, Local Services Tax, MTA Tax, and Other Local Tax 2. Pay and Detail Levels - Head Tax, Local Services Tax, and Other Local Tax, jurisdictionCode/shortName added 3. For Head Tax, statutoryDeductionTypeCode/codeValue is incorrectly set to “LIT”, should be “HEAD” 4. Payroll Level changed SectionCategory name removing the word ‘Taxes’; Local Taxes changed to just ‘Local’ 5. All Levels – changes to short name, removed Local abbreviation; e.g. for LIT – was “LocalityName Income Tax” or blankSpaces Income Tax; now “Local Income Tax” . The same changes were made for HEAD, LST, SDT, MTA and OTH 6. Payroll Level - PA locals impounder logic and Tax Filing Code logic updated. |
|
| Changes to State Taxes in v2 |
1. Payroll Level changed SectionCategory name removing the word ‘Taxes’; State Taxes changed to just ‘State’ 2. Payroll Level no longer valuing worked in/lived in indicators 3. All Levels – changes to short name, removed state abbreviation; e.g. for SIT – was “NJ State Income Tax”; now “State Income Tax” (state is always valued at administrative level 1). The same changes were made for SUI, SDI, FLI, VPDI and WCA 4. All levels - Added new FLI & MLI taxes for DC & MA states. |
|
| Changes to Provincial Taxes (Canadian payrolls only) in v2 |
1. Payroll Level changed SectionCategory name removing the word ‘Taxes’; Provincial Taxes changed to just ‘Provincial’ 2. Payroll Level no longer valuing worked in/lived in indicators 3. For the provincial taxes, statutoryDeductionTypeCode/shortName changes made as follows at all levels:
4. Multi Remittance feature enabled. Will return remittance number for each tax (federal and provincial). |
|
| Federal Taxes in v2 |
Payroll Level changed SectionCategory name removing the word ‘Taxes’; Federal Taxes changed to just ‘Federal’ |
Taxes - StatutoryDeductions |
| Wage Garnishments API |
A separate API call to fetch wage garnishments changes for all the associates is introduced for a payroll run. The response will contain a list of wage garnishments that include details like associate OID, file number, lien changes .The file number is populated as part of configuration tags in response. This API will populate the wage garnishments count as part of meta data. |
Wage Garnishments sample |
| Changes to pay level Data in v2 |
|
|
| Sample for differences |
Payroll Output v1 Sample Payroll Output v2 Sample |
Payroll Output v2 URL Examples
| URL | LEVEL |
| /payroll/v1/payroll-output?level=default&$filter=payrollGroupCode/codeValue eq BL6 and payrollScheduleReference/payrollWeekNumber eq 16 | default |
| /payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=payroll | payroll |
|
/payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=pay&$count=true /payroll/v2/payroll-output-stream?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=pay&$count=true |
pay |
|
/payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=details&$count=true /payroll/v2/payroll-output-stream?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=details&$count=true |
details |
|
/payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=payDetails&$count=true /payroll/v2/payroll-output-stream?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=payDetails&$count=true |
payDetails |
|
/payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=acc&$count=true /payroll/v2/payroll-output-stream?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=acc&$count=true |
acc |
|
/payroll/v1/payroll-output?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=acc-all&$count=true /payroll/v2/payroll-output-stream?$filter=itemID eq NJu0QHg69cxU-axjiZKDwQ%3D%3D&level=acc-all&$count=true |
acc all |
|
/payroll/v1/wage-garnishments |
wgps |
