Use Case Description
The Turbo API provides information related to a client's payrolls. This use case gets the details of a payroll.
API Usage
Application Scope
The canonical URI corresponding to the API needs to be added in the Consumer Application Registry (CAR) for the subscription following which a user can access this API and make successful API calls.
The following canonicals need to be added to your application scope to enable this use case:
/payroll/payrollManagement/payrollProcessingResults/payrollOutputManagement/
payrollOutput.read
/payroll/payrollManagement/payrollProcessingResults/employmentVerificationManagement/
payrollOutput.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentSummary/
earningSummary.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentSummary/
statutoryDeductionSummary.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentSummary/
nonStatutoryDeductionSummary.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentSummary/
reportableEarningBenefitSummary.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentAllocations/
earningAllocations.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentAllocations/
statutoryDeductionAllocations.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentAllocations/
nonStatutoryDeductionAllocations.read
/payroll/payrollManagement/payrollProcessingResults/payrollOutputPaymentAllocations/
reportableEarningBenefitAllocations.read
Supported Actors
|
Request Parameter roleCode Value
|
Usage
|
| Practitioner |
Practitioners can retrieve or make updates to a worker's payroll details. |
Headers and Filters
|
Attribute
|
Parameter
|
Description
|
| URL |
|
"payrollOutputService/v1/payroll-output" |
| Header Param |
{Content-Type} |
application/json (required) |
| Header Param |
{adp-userid} |
{user id/email address} |
| Header Param |
{orgoid} |
Organization OID (required) |
| Header Param |
{associateoid} |
Associate OID (required) |
| Header Param |
{sm_serversessionid} |
Session ID (required) |
| Header Param |
{SOR} |
AutoPay (required) |
| Header Param |
{SORContext} |
For checkmate format is {region}:{company}:{Chron NB}:{CUI Edit ID}:{RTP Job ID}:{CUI Jln Dt}, for all others {region}:{company}:{RTP Job ID} |
| Header Param |
{realm} |
ISI (required) |
| Header Param |
roleCode (required) |
The role the user is playing during the transaction. Possible values are as follows:
- employee
- manager
- practitioner
- administrator
- supervisor
When coming from Myself capabilities rolecode=employee the roleCode header will be passed in all calls.
When coming from Team capabilities, the roleCode=manager.
When coming from Practitioner capabilities, the roleCode=practitioner.
The API will only accept the rolecode of practitioner or employee.
|
| Header Param |
ConsumerAppOID |
Specifies the identifier for the service consumer application.
Identifies if the API consumer is an external application or internal to ADP.
|
| Query Param |
level |
Specifies the payroll output level.
Valid entries are as follows:
- blank - List of basic information on matching payroll runs.
- payroll - Payroll Summary totals for a specific payroll run.
- pay - Payment Summary at the employee and associate level for a specific payroll run.
- acc - Payment summary with accumulation totals at the associate and employee level.
- acc-all - Accumulation for all employees and associates even if they have no activity during this payroll run.
- Details - Associate Payment details for a specific payroll.
- run - Returns detail level information for CheckMate runs.
|
| Query Param |
$count |
Include meta node with total record count? Valid entries are true or false. |
| Query Param |
$skip |
Number of records to be skipped when generating output.
When the level is blank it indicates the number of payroll runs to skip, for all other levels indicates number of associates to be skipped.
|
| Query Param |
$top |
Maximum number of records to be returned. When the level is blank it indicates the number of payroll runs to include. All other levels indicate the number of associates to be included. |
| Query Param |
$select |
List of payroll output sections to include in returned output. If $select is not specified, all output sections relevant to the selected level will be returned. See the list in the following table for currently supported select fields. |
| Query Param |
$filter |
List of filter conditions to use when selecting payroll runs. See the list in the following table for currently supported filter fields. |
Supported Filter Fields
|
Field Name
|
Description
|
| payrollRegionCode/codeValue |
Specifies the Payroll Region. |
| payrollGroupCode/codeValue |
Specifies the company code or payroll group. |
| itemID |
Specifies the payroll run item ID. |
| payrollProcessingJobID |
Specifies the payroll run RTP Payroll ID. |
| payrollScheduleReference/scheduleEntryID |
Specifies the Payroll Schedule Entry item ID. |
| payrollScheduleReference/payrollScheduleID |
Specifies the Payroll Schedule item ID. |
| payrollScheduleReference/payrollYear |
Specifies the Payroll Year (4 digits). |
| payrollScheduleReference/payrollWeekNumber |
Specifies the Payroll Week Number (2 digits). |
| payrollScheduleReference/payrollRunNumber |
Specifies the payroll run number. |
| associatePayments/associateOID |
Specifies the associateOID (25 max). |
| level |
Specifies the level of data (see Level Matrix). |
When filtering on associateOID (AOID), due to the 2000 character URL limitation, we recommend not exceeding 25 AOIDs per call.
There are several levels that can be requested, specified through the level=parameter, and explained in the following table. Parameters and filters can be specified within the request for any level and to provide information on a specific company, payroll, or associate.
Understanding Level Filter
The Turbo API provides information related to a client's payrolls. There are several levels that can be requested, specified through level=parameter, and explained in the following table.
Parameters and filters can be specified within the request for any level, in order to provide information on a specific company, payroll, or associate.
Level Matrix
|
Level
|
Name
|
Quick Description
|
Long Description
|
|
(default, no level= parameter specified)
|
Payroll Run List
|
List of payroll runs with default level information for the requested client.
|
The default level provides a list of payroll runs for the requested client. Each occurrence of a payroll within this list includes default level information, such as basic payroll run parameters, status, and schedule reference information.
Default level data can be called either by Year or from a Beginning Date by using the payrollHistDate filter with the format YYYMMDD:
/payroll/v1/payroll-output?$filter=payrollGroupCode/codeValue eq RR1&payrollHistDate=20181228&level=default
Default level data will not include any data elements occurring prior to region activation data of payroll output (typically 10/2017).
Data returned includes the following Default Level Information for each payroll in the list:
- Processing Job ID
- AutoPay Region Code
- Group Code (AutoPay Company Code)
Schedule Reference Information includes Schedule ID, Schedule Entry ID (prefaced by the run date/time), and the payroll's Year, Week, and Run Number.
|
|
payroll
|
Payroll Summary
|
For the selected payroll, there is the following:
- Default level information
- Payroll summary totals
|
The payroll level provides the default level information for the selected payroll, followed by payroll summary totals across all associates in that payroll.
Returned data includes the following Default Level Information for each payroll in the list:
- Default Level Information
- Earnings Summary
- Reportable Earnings and Benefits Summary
- Reimbursements Summary
- Statutory Deductions Summary
- Non-Statutory Deductions Summary
- Memos Summary
- Payments Distribution Summary
- Payroll Adjustments
- Third Party Payments
Schema location: /payrollOutput/payrollSummary/
|
|
pay
|
Associate Payment Summary
|
For the selected payroll default level information and payment information for each pay and each associate. This includes the following:
- High level payment information
- Payment summary
- Payment distributions
|
The pay level provides the default level information for the selected payroll, followed by a summary of the associate payment information for the associates that had activity in the selected payroll.
Returned data includes the following items for each associate:
- Default Level Information
- Associate's AOID (Associate Object Identifier)
- Payment Information (this is an array of pays for each AutoPay file number within the AOID)
- Pay Date, Period Start Date, Period End Date
- Payment Amount (also known as Take Home Pay)
- Payment Summary
- Earnings (array)
- Reportable Earnings and Benefits (array)
- Reimbursements (array)
- Statutory Deductions (array)
- Non-Statutory Deductions (array)
- Memos (array)
- Payment Distributions
- Payment Document ID (such as a voucher or check)
- Check Amount
- Direct Deposits (array)
Schema location: /payrollOutput/associatePayments
|
|
details
|
Associate Payment Detail
|
For the selected payroll, default level information and payment information for each pay and each associate. This includes the following:
- High level payment information
- Payment details
|
The details level provides the default level information for the selected payroll, followed by the details of the associate payment information for the associates that had activity in the selected payroll.
Returned data includes the following items for each associate:
- Default Level Information
- Associate's AOID
- Payment Details (this is an array of pays for each AutoPay file number within the AOID)
- Pay Date, Period Start Date, Period End Date
- Payment Amount (also known as Take Home Pay)
- Payment Allocations
- Pay Allocation ID
- Earnings (array)
- Reportable Earnings and Benefits (array)
- Reimbursements (array)
- Statutory Deductions (array)
- Non-Statutory Deductions (array)
- Memos (array)
Schema location: /payrollOutput/associatePayments
|
|
payDetails
|
Associate Payment Summary and Details
|
For the selected payroll, default level information and payment information for each pay and each associate. This includes the following:
- High level payment information
- Payment summary
- Payment distributions
- Payment details
|
The payDetails level provides the default level information for the selected payroll, followed by a summary of the associate payment information for the associates having activity in the selected payroll and details of the associate payment information.
Returned data includes the following items for each associate:
- Default Level Information
- Associate's AOID
- Payment Information (this is an array of pays for each AutoPay file number within the AOID)
- Pay Date, Period Start Date, Period End Date
- Payment Amount (also known as Take Home Pay)
- Payment Summary
- Earnings (array)
- Reportable Earnings and Benefits (array)
- Reimbursements (array)
- Statutory Deductions (array)
- Non-Statutory Deductions (array)
- Memos (array)
- Payment Distributions
- Payment Document ID (such as voucher or check)
- Check Amount
- Direct Deposits (array)
- Payment Details (this is an array of pays for each AutoPay file number within the AOID)
- Pay Date, Period Start Date, Period End Date
- Payment Amount (also known as Take Home Pay)
- Payment Allocations
- Pay Allocation ID
- Earnings (array)
- Reportable Earnings and Benefits (array)
- Reimbursements (array)
- Statutory Deductions (array)
- Non-Statutory Deductions (array)
- Memos (array)
|
|
acc
|
Associate Payment Summary with YTD & Other Accumulations
|
For the selected payroll ...
Default level information and payment information for each pay and each associate.
This includes the following:
- High level payment information
- Payment summary
- Payment distributions
- Payroll accumulations for associates who had activity
|
The acc level provides the same information as the pay level, with the addition of payroll accumulations information for the following:
- Gross, Earnings
- Reportable Earnings and Benefits Reimbursements
- Statutory Deductions
- Non-Statutory Deductions
- Memos
The accumulations information for each AutoPay file number will be included within the last pay number in which that accumulation was impacted. If a specific accumulation was not impacted during this payroll, it will be included within pay number 0 (zero).
Note: Accumulations information will only be provided for associates who had activity in the selected payroll.
|
|
acc-all
|
Associate Payment Summary with YTD & Other Accumulations(all associates)
|
For the selected payroll ...
Default level information and payment information for each pay and each associate.
This includes the following:
- High level payment information
- Payment summary
- Payment distributions
- Payroll accumulations for all associates in the company
|
The acc-all level is the same as the acc level, except that payroll accumulations information will be included for all associates in the company.
For unpaid/inactive employees in the acc-all response, any untaken deduction amounts or benefit accrual amounts will be included for each employee will be added to the response. The payment date will be available for all employees. The payment start and end dates will be available only for employees who are paid in the payroll.
|
| error |
Error Correction |
For the selected payroll:
- corrected errors allowing activity to progress to preview complete
- crossfoot errors
|
For error level, all errors as would be listed on the error correction green screen which indicate errors corrected on input to allow the payroll activity to progress.
Crossfoot errors (negative pay) are also included.
Note: Counts of error messages are listed in the confirmMessage section on the payroll (payroll summary) level.
|
| dropped pay |
Dropped Pays |
For the selected payroll:
- listing of all dropped pay file numbers and associated messages
|
For dropped pay level, a simple list of selected payroll output runs retrieved from AutoPay history for dropped pays is provided. Default associate payments information and configuration tags details will be included |
| wage garnishements |
Wage Garnishments |
For the selected payroll isting of all lien numbers and lien change codes.
|
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. /payroll/v1/wage-garnishments |
