U.S. Federal Tax Withholding API Guide for ADP Workforce Now
Transcript of U.S. Federal Tax Withholding API Guide for ADP Workforce Now
ADP Copyright Information
ADP, the ADP logo, Always Designing for People, ADP TotalSource, and ADP Workforce Now are
trademarks of ADP, LLC.
All other trademarks are the property of their respective owners.
Copyright © 2019 ADP, LLC. ADP Proprietary and Confidential - All Rights Reserved. These materials
may not be reproduced in any format without the express written permission of ADP, LLC.
ADP provides this publication “as is” without warranty of any kind, either expressed or implied, including,
but not limited to, the implied warranties of merchantability or fitness for a particular purpose. ADP is not
responsible for any technical inaccuracies or typographical errors which may be contained in this
publication. Changes are periodically made to the information herein, and such changes will be
incorporated in new editions of this publication. ADP may make improvements and/or changes in the
product and/or the programs described in this publication.
Publication Date: 12/24/2019 1:59 PM
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Contents
About the U.S. Federal Tax Withholding API ............................................................................................ 1
Tax Withholding Tasks ............................................................................................................................. 1
About Federal Taxes ................................................................................................................................ 1
Supported Product Version and Customer Base ...................................................................................... 2
Required Setup Steps .............................................................................................................................. 2
Postman Collection .................................................................................................................................. 2
Use Cases ............................................................................................................................................... 3
Use Case 1: Retrieving a U.S. Federal Tax Profile ............................................................................... 3
Use Case Description ....................................................................................................................... 3
UI Fields not Supported in the API Schema ...................................................................................... 3
API Fields Not Used.......................................................................................................................... 3
API Usage ........................................................................................................................................ 4
Application Scope ............................................................................................................................. 4
Supported Actors .............................................................................................................................. 4
Request Header Parameters ............................................................................................................ 4
Other Supported Parameters ............................................................................................................ 5
Sequence of Interactions .................................................................................................................. 5
Data Dictionary ................................................................................................................................. 5
Responses ...................................................................................................................................... 10
Use Case 2: Posting U.S. Tax Profile Changes .................................................................................. 12
Use Case Description ..................................................................................................................... 12
Data Dictionary ............................................................................................................................... 12
API Usage ...................................................................................................................................... 18
Application Scope ........................................................................................................................... 18
Supported Actors ............................................................................................................................ 18
Request Header Parameters .......................................................................................................... 19
Other Supported Parameters .......................................................................................................... 19
Sequence of Interactions ................................................................................................................ 19
Responses ...................................................................................................................................... 19
Known Issues and Limitations ................................................................................................................ 23
US1341873: Federal Tax Event Notification ....................................................................................... 23
Impacted APIs ................................................................................................................................ 23
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Issue Description ............................................................................................................................ 23
Suggested Workaround .................................................................................................................. 24
US140416: The Following ADP Workforce Now Fields are Currently Not Handled by the API ........... 24
Impacted APIs ................................................................................................................................ 24
Issue Description ............................................................................................................................ 24
Appendix – Adding or Changing an Employee’s Federal Tax Information .............................................. 25
About the U.S. Federal Tax Withholding API 1
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
About the U.S. Federal Tax Withholding API
The U.S. Federal Tax Withholding Application Programming Interface (API) enables users to add or
change a worker’s tax withholding information.
Tax Withholding Tasks
The following are the tax withholding tasks:
• Federal tax tasks
• State tax tasks
• State Unemployment Insurance (SUI)/State Disability Insurance (SDI) tax tasks
• Local tax tasks
About Federal Taxes
For tax purposes, the federal government withholds an amount from an employee's earnings. The
amount of tax varies with the following:
• Amount of earnings
• Pay frequency
• Number of exemptions claimed
• Marital status
Federal taxes can be adjusted for each individual employee.
Supported Product Version and Customer Base 2
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
The law requires an employer to deduct a portion of an employee's wages each pay period and deposit
that amount in a government account, so that it may be applied against the employee's annual income
tax.
• If you enter an employee's Federal tax information incorrectly, you may be required to
file an amendment with the appropriate tax agency. Contact your ADP service team if
you have any questions about making these changes.
• You cannot change the effective date of the current Tax record for a new hire, or if no
other Tax record exists for the employee. Also, you cannot change the effective date
of any current record to a future date if the record was already sent to ADP as part of
the employee data in your payroll file.
• It is expected that tax details should be entered while hiring a new employee. The
Federal Tax API is not used for adding a new federal tax profile. It retrieves the
existing tax details using the GET API and updates the existing tax details using the
POST API.
Supported Product Version and Customer Base
This is available for workers in the United States (U.S.).
Required Setup Steps
In ADP Workforce Now, select People > pay > pay Profile > Tax WithHoldings > Federal. In the
Additional Tax Type field, make sure both Dollar and Percentage options are available.
If the Percentage option is not available in the drop-down list, follow these steps:
1. Go to Setup > Tools > System Options > Payroll. 2. Select Allow Percentages for Additional Withholding Tax Amounts (Extra Tax Amounts). 3. Click Save.
Postman Collection
Postman allows you to import a collection of APIs, created by others, so you can try them out. For more
information on Postman, see Making Your First API Call Using Postman.
To download API collections for the U.S. Federal Tax Withholdings API from the ADP GitHub library and
import them to Postman, go to Postman Collection.
The U.S. Federal Tax Withholding API is currently being piloted. Check the
Marketplace API Release Notes for ADP Workforce Now and Marketplace API Release
Plan for ADP Workforce Now for updates.
Use Cases 3
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Use Cases
The following are use cases covered in this section:
• Use Case 1: Retrieving a U.S. Federal Tax Profile
• Use Case 2: Posting U.S. Tax Profile Changes
The following are use cases to be supported in future releases of this guide:
• State tax tasks
• SUI/SDI tax tasks
• Local tax tasks
Use Case 1: Retrieving a U.S. Federal Tax Profile
Use Case Description
This use case retrieves a worker’s U.S. federal tax profile.
UI Fields not Supported in the API Schema
The following are the ADP Workforce Now user interface (UI) fields which are not currently handled as
part of API:
• Reverse the company default for Taxable Fringe Benefits - Not in release
• Number of Hours Per Meal - Not in release
• Average Tip Amount Per Hour
• Block the employee from updating the Form W-4 federal tax exemptions
• Do not calculate Federal Taxable
• W-2 Box 13 Retirement Plan/Qualified Pension
• Non-Resident Alien
API Fields Not Used
The following are the API schema fields which are not mapped with the UI:
• overrideTaxPercentage
• overrideTaxAmount
Use Cases 4
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
API Usage
Method URI Description Sample Request
Payload
GET /payroll/v1/workers/{aoid}/us-tax-
profiles
Retrieves a worker’s U.S.
tax profile up to the
current date.
federal-usTaxProfile-
200.response.json
GET /payroll/v1/workers/{aoid}/us-tax-
profiles?asOfDate={effectiveDate}
Retrieves a worker’s U.S.
tax profile based on the
date passed in the
request end point.
federal-usTaxProfile-
Future-asOfDate-
200.response.json
Application Scope
The canonical uniform resource identifier (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 canonical needs to be added to your application scope to enable this use case:
/payroll/payrollManagement/payrollInstructionManagement/taxProfileManagement/
usTaxProfile.read
Supported Actors
Request Parameter roleCode
Value:
practitioner
Usage: Practitioners can retrieve or make updates to a workers U.S. tax
profile.
Request Header Parameters
Parameter Name: asOfDate
Required (Y/N): N
Usage: Used to retrieve as of a specified date.
Value: effectiveDate
Use Cases 5
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Other Supported Parameters
There are no other supported parameters.
Sequence of Interactions
The following are the steps shown in the previous diagram:
1. Your consumer application makes a request to the ADP API Endpoint to GET us-tax-profiles for the worker.
2. The ADP API Endpoint responds to your consumer application with single worker federal tax information.
Data Dictionary
Resources listed in the following table can be accessed through ADP Workforce Now by selecting
People > Pay Profile > Tax Withholdings.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfiles/payrollFileNumber Payroll File Number Y
/usTaxProfiles/payrollGroupCode Not Displayed N
/usTaxProfiles/payrollGroupCode/
codeValue
Company Code Y
/usTaxProfiles/payrollGroupCode/
longName
N
/usTaxProfiles/itemID Not Displayed Y
/usTaxProfile/usFederalTaxInstruction Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus
Not Displayed N
Use Cases 6
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus/statusCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus/statusCode/
codeValue
Do not calculate
Federal Income Tax
Do not calculate
Federal Taxable
Y
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus/statusCode/
shortName
N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus/reasonCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingStatus/effectiveDate
Effective N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxFilingStatusCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxFilingStatusCode/codeValue
Marital Status Y
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxFilingStatusCode/longName
N Only the codeValue
required.
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingAllowanceQuantity
Exemptions N
Use Cases 7
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
additionalTaxPercentage
Additional Tax
Amount
Y
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
additionalTaxAmount
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
additionalTaxAmount/amountValue
Additional Tax
Amount
Y
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
overrideTaxPercentage
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
overrideTaxAmount
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/
taxWithholdingStatus
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/
taxWithholdingStatus/statusCode
Not Displayed Y
/usTaxProfile/usFederalTaxInstruction/soci
alSecurityTaxInstruction/
taxWithholdingStatus/statusCode/
codeValue/usTaxProfile/
usFederalTaxInstruction/
socialSecurityTaxInstruction/
taxWithholdingStatus/statusCode/
shortName
Do not Calculate
Social Security
N Only codeValue
required.
Use Cases 8
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/
taxWithholdingStatus/reasonCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/
taxWithholdingStatus/effectiveDate
Effective N
/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/
taxWithholdingStatus
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/
taxWithholdingStatus/statusCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/
taxWithholdingStatus/statusCode/
codeValue
Do not calculate
Medicare
Y
/usTaxProfile/usFederalTaxInstruction/me
dicareTaxInstruction/taxWithholdingStatus
/statusCode/shortName
N Only codeValue
required.
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode
Not Displayed N
Use Cases 9
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode/
codeValue
Do not Calculate
F.U.T.A Taxable
Y
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode/
shortName
N Only codeValue
required.
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/reasonCode
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/effectiveDate
Effective N
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction
Not Displayed N
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/distributionCodes
N
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/distributionCodes/
codeValue
Box 7 for Distribution
Code 1
Box 7 for Distribution
Code 2
Y
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/
totalDistributionIndicator
Box 2B for Total
Distribution
N
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/
individualRetirementAccountIndicator
Box 7 for IRA/SEP
Distribution
N
Use Cases 10
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/
simplifiedEmployeePensionAccount
Indicator
Box 7 for IRA/SEP
Distribution
N
/usTaxProfile/usFederalTaxInstruction/
interimW2IssuesIndicator
Reissue W-2 for
terminated employee
[Check Box]
N
/usTaxProfile/usFederalTaxInstruction/
statutoryWorkerIndicator
Statutory employee
[Check Box]
N
/usTaxProfile/usFederalTaxInstruction/
qualifiedPensionPlanCoverageIndicator
Household employee N
Responses
You may encounter exceptions outside your common success scenarios. You must account for these
exceptions during your initial development.
For more information, see API Common Exceptions and Tips for Handling.
Response
Code Condition message txt
GitHub Sample
Response Payload Tips to Handle
200 OK
When making a request
without passing asOfDate in
the end point.
federal-usTaxProfile-
200.response.json
Passing asOfDate as the
past date when making a
request.
federal-usTaxProfile-
PAST-asOfDate-
200.response.json
When making a request with
asOfDate as future date.
federal-usTaxProfile-
Future-asOfDate-
200.response.json
Use Cases 11
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code Condition message txt
GitHub Sample
Response Payload Tips to Handle
400 Bad
Request
When making a request with
asOfDate, but there is no
record previous to the
asOfDate passed in the end
point.
"userMessage": {
"messageTxt": "As
Of Date is invalid."
}
federal-usTaxProfile-
Invalid-asOfDate-
400.response.json
When making a request with
an invalid associate ID.
"userMessage": {
"messageTxt":
"AOID is invalid."
}
federal-usTaxProfile-
InvalidAssociate-
400.response.json
For a list of other use cases, see Use Cases on page 3.
Use Cases 12
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Use Case 2: Posting U.S. Tax Profile Changes
Use Case Description
This use case allows a practitioner to make updates to a worker’s U.S. federal tax withholdings.
1. To POST a federal tax profile change, the user first needs to do a GET
call to retrieve the itemID, payrollFileNumber, and
payrollGroupCode for the employee position.
2. In the ADP Workforce Now user interface (UI), we have two W4 forms
(PRE2020 and 2020). The user needs to enable the W4 2020 in the
Client Wizard settings. Using the U.S. Federal Tax Withholdings API to
manage both PRE2020 and 2020, the Format Code field in the request
payload is updated.
Also:
1. When Non-Resident Alien is set to TRUE, then Dependents,
Deductions, and other Income fields will be disabled and only the
Exemptions field is enabled. Therefore, through the U.S. Federal Tax
Withholdings API, if you pass those fields when Non-Resident Alien
field is set to TRUE, it does not reflect in the ADP Workforce Now UI.
2. To update the Exemptions value, the payload Non-Resident Alien
value should be set as TRUE.
Data Dictionary
Resources listed in the following table can be accessed through ADP Workforce Now by selecting
People > Pay Profile > Tax Withholdings.
Schema Location Field Name Is
Required
(Y/N)
Note
/events Not Displayed Y
/events/data Not Displayed Y
/events/data/eventContext Not Displayed Y
/events/data/eventContext/contextExpressionID Not Displayed N
/events/data/eventContext/worker Not Displayed Y
Use Cases 13
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/events/data/eventContext/worker/associateOID AssociateOID Y
/events/data/eventContext/usTaxProfiles Not Displayed Y
/events/data/eventContext/usTaxProfiles/itemID Not Displayed Y
/events/data/eventContext/usTaxProfiles/
payrollAgreementID
Not Displayed N
/events/data/eventContext/usTaxProfiles/
payrollFileNumber
Y
/events/data/eventContext/usTaxProfiles/payrollGr
oupCode
Not Displayed Y
/events/data/eventContext/usTaxProfiles/
payrollGroupCode/codeValue
Company Code Y
/events/data/transform Not Displayed Y
/events/data/transform/usTaxProfile/
usFederalTaxInstruction/multipleJobIndicator
Multiple Jobs
Indicator
N
/usTaxProfile/usFederalTaxInstruction/
additionalStatutoryInputs/FormatCode
Non Resident
Alien
This field also
enables the
form 2020 or
PRE2020
based on the
FormatCode.
Y
/usTaxProfile/usFederalTaxInstruction/
additionalStatutoryInputs/TagCode
/usTaxProfile/usFederalTaxInstruction/
additionalStatutoryInputs/TagValues
/usTaxProfile/usFederalTaxInstruction/
additionalStatutoryInputs/DataTypeCode
Use Cases 14
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxAllowances/
allowanceTypeCode/codeValue
Dependents |
Deductions
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxAllowances/
taxAllowanceAmount/amountValue
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
additionalIncomeAmount/amountValue
Other Income
/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/additionalTaxAmount/
amountValue
Additional Tax
Amount
/events/data/transform/effectiveDateTime Effective Date Y
/events/data/transform/usTaxProfile/ Not Displayed Y
/events/data/transform/usTaxProfile/
usFederalTaxInstruction
Not Displayed Y
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction
Not Displayed Y
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxWithholdingStatus
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxWithholdingStatus/
statusCode
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxWithholdingStatus/
statusCode/codeValue
Do not calculate
Federal Income
Tax
N
Use Cases 15
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxWithholdingStatus/
statusCode/shortName
Do not calculate
Federal Taxable
N Only codeValue is
required for updates.
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxFilingStatusCode
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxFilingStatusCode/
codeValue
Marital Status N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/taxFilingStatusCode/
longName
N Only codeValue is
required for updates.
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
taxWithholdingAllowanceQuantity
Exemptions N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/
additionalTaxPercentage
Additional Tax
Amount
N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/additionalTaxAmount
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalIncomeTaxInstruction/additionalTaxAmount/
amountValue
Additional Tax
Amount
N
/events/data/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/taxWithholdingStatus
Not Displayed N
Use Cases 16
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/events/data/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/taxWithholdingStatus/
statusCode
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/taxWithholdingStatus/
statusCode/codeValue
/events/data/usTaxProfile/usFederalTaxInstruction/
socialSecurityTaxInstruction/taxWithholdingStatus/
statusCode/shortName
Do not Calculate
Social Security
N Only codeValue is
required for updates.
/events/data/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/taxWithholdingStatus
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/taxWithholdingStatus/
statusCode
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/taxWithholdingStatus/
statusCode/codeValue
Do not calculate
Medicare
N
/events/data/usTaxProfile/usFederalTaxInstruction/
medicareTaxInstruction/taxWithholdingStatus/
statusCode/shortName
Only codeValue
Required for updates
/events/data/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus
Not Displayed N
Use Cases 17
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/events/data/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode/codeValue
Do not Calculate
F.U.T.A Taxable
N
/events/data/usTaxProfile/usFederalTaxInstruction/
federalUnemploymentTaxInstruction/
taxWithholdingStatus/statusCode/shortName
Only codeValue is
required for updates.
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/distributionCodes
Not Displayed N
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/distributionCodes/codeValue
Box 7 for
Distribution
Code 1
Box 7 for
Distribution
Code 2
N
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/totalDistributionIndicator
Box 2B for Total
Distribution
N
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/individualRetirementAccountI
ndicator
Box 7 for
IRA/SEP
Distribution
N
/events/data/usTaxProfile/usFederalTaxInstruction/
form1099Instruction/simplifiedEmployeePensionAc
countIndicator
W-2 Box 13
Retirement
Plan/Qualified
Pension
N
Use Cases 18
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name Is
Required
(Y/N)
Note
/events/data/usTaxProfile/usFederalTaxInstruction/
interimW2IssuesIndicator
Reissue W-2 for
terminated
employee
N
/events/data/usTaxProfile/usFederalTaxInstruction/
statutoryWorkerIndicator
Statutory
employee
N
/events/data/usTaxProfile/usFederalTaxInstruction/
qualifiedPensionPlanCoverageIndicator
Not Displayed N
API Usage
Method URI Description Sample Request
Payload
Sample Response
Payload
POST
/events/payroll/v1/us-tax-
profile.federal-income-tax-
instruction.change
Update a
worker or
multiple workers
tax profiles.
federal-
usTaxProfile-
married-dollar-
200.request.json
federal-usTaxProfile-
married-dollar-
200.response.json
GET
/events/payroll/v1/us-tax-
profile.federal-income-tax-
instruction.change/meta
Payload field
and code list
information.
NA
federal-usTaxProfile-
metaRes-
200.response.json
Application Scope
The following canonical needs to be added to your application scope to enable this use case:
/payroll/payrollManagement/payrollInstructionManagement/taxProfileManagement/
usTaxProfileFederalIncomeTaxInstruction.change
Supported Actors
Request Parameter roleCode
Value: practitioner
Usage: Practitioners can retrieve or make updates to a workers U.S. tax
profile.
Use Cases 19
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Request Header Parameters
There are no request header parameters.
Other Supported Parameters
There are no other supported parameters.
Sequence of Interactions
The following are the steps:
1. Your consumer application makes a request to the ADP API Endpoint to POST us-tax-profiles for the worker.
2. The ADP API Endpoint responds to your consumer application with single worker federal tax information.
Responses
You may encounter exceptions outside your common success scenarios. You must account for the
following exceptions during your initial development. Refer to Working with Common Exceptions.
Response
Code
Condition GitHub Sample
Request Payload
GitHub Sample
Response Payload
Tips to Handle
200 OK Returns when the tax is
updated in the current date.
federal-change-
currentDate-
200.request.json
federal-change-
currentDate-
200.response.json
Returns when the exempt
field is checked in the U.S.
Federal Withholding API.
federal-change-
exemptChecked-
200.request.json
federal-change-
exemptChecked-
200.response.json
Returns when the additional
tax amount is passed.
federal-change-
otherIncome-
200.request.json
federal-change-
otherIncome-
200.response.json
Returns when Dependents
and deductions are provided.
federal-change-
deductions_
dependents-
200.request.json
federal-change-
deductions_
dependents-
200.response.json
Use Cases 20
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code
Condition GitHub Sample
Request Payload
GitHub Sample
Response Payload
Tips to Handle
200 OK
(cont.)
Returns when the filing
status is "MH" – Married but
withhold at higher Single
rate).
federal-change-
PRE2020_MH-
200.request.json
federal-change-
PRE2020_MH-
200.response.json
Returns when the filing
status is "M" – Married.
federal-change-
PRE2020_M-
200.request.json
federal-change-
PRE2020_M-
200.response.json
Returns when the filing
status is "S" – Single.
federal-change-
PRE2020_S-
200.request.json
federal-change-
PRE2020_S-
200.response.json
Returns when the filing
status is "D" – Single or
Married Filing Separately.
federal-change-
2020_D-
200.request.json
federal-change-
2020_D-
200.response.json
Returns when the filing
status is "J" – Married filing
jointly (or Qualifying
widower).
federal-change-
2020_J-
200.request.json
federal-change-
2020_J-
200.response.json
Returns when the filing
status is "H" – Head of
household.
federal-change-
2020_H-
200.request.json
federal-change-
2020_H-
200.response.json
Returns when the field
multipleJobIndicator is
Unchecked.
federal-change-
multipleJobIndicator-
200.request.json
federal-change-
multipleJobIndicator-
200.response.json
Returns when the field
NON_RESIDENT_ALIEN is
Unchecked.
federal-change-
Non_resident_alien-
200.request.json
federal-change-
Non_resident_alien-
200.response.json
Use Cases 21
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code
Condition GitHub Sample
Request Payload
GitHub Sample
Response Payload
Tips to Handle
200 OK
(cont.)
Returns when the following
fields are checked:
socialSecurityTax
Instruction
medicareTaxInstruction
totalDistributionIndicator
indiviualRetirement
AccountIndicator
simplifiedEmployee
PensionAccountIndicator
interimW2IssuedIndicator
statutoryWorkerIndicator
qualifiedPension
Plan
CoverageIndicator
federal-change-
IndicatorAllChecked-
200.request.json
federal-change-
IndicatorAllChecked-
200.response.json
Returns when the following
fields are Unchecked:
socialSecurityTax
Instruction
medicareTaxInstruction
totalDistributionIndicator
indiviualRetirement
AccountIndicator
simplifiedEmployee
PensionAccountIndicator
interimW2IssuedIndicator
statutoryWorkerIndicator
qualifiedPensionPlan
CoverageIndicator
federal-change-
IndicatorAllUnchecked-
200.request.json
federal-change-
IndicatorAllUnchecke
d-200.response.json
Use Cases 22
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code
Condition GitHub Sample
Request Payload
GitHub Sample
Response Payload
Tips to Handle
200 OK
(cont.)
Returns when both the
form1099Instruction fields
are empty.
federal-change-
Form1099Notselected-
200.request.json
federal-change-
Form1099Not
selected-
200.response.json
400 Bad
Request
Returns when the Invalid
associate ID is passed in
request payload.
federal-usTaxProfile-
Invalid-associateID-
400.request.json
federal-usTaxProfile-
Invalid-associateID-
400.response.json
Returns when Invalid payroll
company code is passed in
request payload.
federal-usTaxProfile-
Invalid-companyCode-
400.request.json
federal-usTaxProfile-
Invalid-
companyCode-
400.response.json
Returns when Invalid payroll
file number is passed in
request payload.
federal-usTaxProfile-
Invalid-filenumber-
400.request.json
federal-usTaxProfile-
Invalid-filenumber-
400.response.json
Returns when Invalid
effective date value is
passed in request payload.
federal-usTaxProfile-
Invalid-effectiveDate-
400.request.json
federal-usTaxProfile-
Invalid-effectiveDate-
400.response.json
Returns when Invalid
taxFilingStatusCode value is
passed in request payload.
federal-usTaxProfile-
Invalid-
taxfillingStatusCode-
400.request.json
federal-usTaxProfile-
Invalid-
taxFillingstatusCode-
400.response.json
Returns when Invalid
socialSecurityTaxInstruction
value is passed in request
payload.
federal-usTaxProfile-
Invalid-
socialSecurityTaxInstru
ction-400
federal-usTaxProfile-
Invalid-
socialSecuritytaxInstr
uction-400
Returns when Invalid
medicareTaxInstruction
value is passed in request
payload.
federal-usTaxProfile-
Invalid-
MedicaretaxInstruction
-400
federal-usTaxProfile-
Invalid-
MedicaretaxInstructio
n-400
Known Issues and Limitations 23
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code
Condition GitHub Sample
Request Payload
GitHub Sample
Response Payload
Tips to Handle
400 Bad
Request
(cont.)
Returns when Invalid
form1099Instruction code is
passed in request payload.
federal-usTaxProfile-
Invalid-
form1099InstructionCo
de-400
federal-usTaxProfile-
Invalid-
form1099Instruction
Code-400
Returns when Invalid ItemId
value is missing in the
request payload.
federal-usTaxProfile-
Invalid-ItemID-
400.request.json
federal-usTaxProfile-
Invalid-ItemID-
400.response.json
500
Internal
Server
Error
Returns when empty ItemId
value is missing in the
request payload.
federal-usTaxProfile-
empty-ItemID-
500.request.json
federal-usTaxProfile-
empty-ItemID-
500.response.json
For a list of other use cases, see Use Cases on page 3.
Known Issues and Limitations
This section details all reported and known issues. This is so developers can be aware of those issues
when using APIs.
These issues include:
• US1341873: Federal Tax Event Notification
• US140416: The Following ADP Workforce Now Fields are Currently Not Handled by the API
US1341873: Federal Tax Event Notification
Impacted APIs
Method: POST
URI: /events/payroll/v1/worker.us-federal-income-tax-instruction.change
roleCode: practitioner
Issue Description
Currently, the Federal tax withholding doesn't support event notifications.
Known Issues and Limitations 24
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Suggested Workaround
There are no suggested workarounds.
For a list of other issues, see Known Issues and Limitations on page 23.
US140416: The Following ADP Workforce Now Fields are Currently Not
Handled by the API
Impacted APIs
Method: POST
URI: /events/payroll/v1/worker.us-federal-income-tax-instruction.change
roleCode: practitioner
Issue Description
The ADP Workforce Now UI fields in the following table are not supported as part of the U.S. Tax
Withholding API.
Field Notes
Taxable Fringe Benefits This is a Check box field in WFN UI
Number of Hours Per Meal This is an Input field in WFN UI
Average Tip Amount Per Hour This is an Input field in WFN UI
Block the employee from updating the Form W-4
federal tax exemptions
This is a Check box field in WFN UI
Do not calculate Federal Taxable This is a Check box field in WFN UI
W-2 Box 13 Retirement Plan/Qualified Pension This is dropdown field in WFN UI
Appendix – Adding or Changing an Employee’s Federal Tax Information 25
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Field Notes
overrideTaxPercentage The following are the API schema fields which
are not mapped with the UI
overrideTaxAmount The following are the API schema fields which
are not mapped with the UI
For a list of other issues, see Known Issues and Limitations on page 23.
Appendix – Adding or Changing an Employee’s
Federal Tax Information
Starting Point: People > Pay > Pay Profile
1. Select an employee.
2. In the Tax Withholdings section, click Federal.
3. If your company uses effective dating, choose one of the following actions:
You cannot change the effective date of the current Tax record for a new hire, or if no other Tax
record exists for the employee. Also, you cannot change the effective date of any current record
to a future date if the record was already sent to ADP as part of the employee data in your payroll
file.
• To enter information for the record you are currently viewing, enter the effective date.
• To enter information for another record, find the record and enter information as appropriate.
4. As appropriate, add or change the following information.
To… Do This…
Change the filing status In the Tax Information section, change the values in the Marital
Status and/or Exemptions fields.
Withhold additional taxes In the Tax Information section, select the Additional Tax Type and
enter a dollar amount or percentage of pay in the Additional Tax
Amount field.
Appendix – Adding or Changing an Employee’s Federal Tax Information 26
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
To… Do This…
Change the standard tax
calculation
In the Changes to Federal Tax Calculation section, select the tax
and/or taxables that should not be calculated.
Some of these options are not available to ADP TotalSource
practitioners. You can change these options only when entering
the employee as a new hire. After the information for the new hire
is submitted to ADP, you cannot change this data.
Block changes to IRS W-4
tax withholdings
In the Employee Access to Form W-4 section, select Block the
employee from updating the Form W-4 federal tax exemptions.
These options are not available to ADP TotalSource practitioners.
Stop Social Security
and/or Medicare
withholding
In the Social Security/Medicare section, select Do Not Calculate
Social Security and/or Do Not Calculate Medicare.
These options are not available to ADP TotalSource practitioners.
You can change these options only when entering the employee
as a new hire. After the information for the new hire is submitted
to ADP, you cannot change this data.
Identify an employee's
pension, retirement, or
profit-sharing plan
distribution
Complete the appropriate fields in the 1099R section.
These options are not available to ADP TotalSource practitioners.
Set up an employee's
restaurant information
In the Restaurant Controls section, enter the appropriate information
in the Number of Hours Per Meal and Average Tip Amount Per
Hour fields.
These options are not available to ADP TotalSource practitioners.
Enter additional tax
information
Select the appropriate values in the Other Codes section.
These options are not available to ADP TotalSource practitioners.
5. Click Done.