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



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



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



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.

https://developers.adp.com/articles/general/make-your-first-api-call-using-postman-1

https://github.com/adpllc/marketplace-sample-payloads/tree/master/wfn/payroll/us-tax-profile/federal/postman-collection

https://developers.adp.com/articles/faq/what-are-the-latest-api-updated-or-released-for-adp-workforce-now

https://developers.adp.com/articles/faq/what-is-the-release-plan-for-adp-workforce-now-apis

https://developers.adp.com/articles/faq/what-is-the-release-plan-for-adp-workforce-now-apis

Use Cases 3



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



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.


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

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-200.response.json


https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-Future-asOfDate-200.response.json



Use Cases 5



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


federalIncomeTaxInstruction/

taxWithholdingStatus

Not Displayed N

Use Cases 6




Required

(Y/N)

Note



taxWithholdingStatus/statusCode

Not Displayed N



taxWithholdingStatus/statusCode/

codeValue

Do not calculate

Federal Income Tax

Do not calculate

Federal Taxable

Y




shortName

N



taxWithholdingStatus/reasonCode

Not Displayed N



taxWithholdingStatus/effectiveDate

Effective N



taxFilingStatusCode

Not Displayed N



taxFilingStatusCode/codeValue

Marital Status Y



taxFilingStatusCode/longName

N Only the codeValue

required.



taxWithholdingAllowanceQuantity

Exemptions N

Use Cases 7




Required

(Y/N)

Note



additionalTaxPercentage

Additional Tax

Amount

Y



additionalTaxAmount

Not Displayed N



additionalTaxAmount/amountValue

Additional Tax

Amount

Y



overrideTaxPercentage

Not Displayed N



overrideTaxAmount

Not Displayed N


socialSecurityTaxInstruction

Not Displayed N


socialSecurityTaxInstruction/


Not Displayed N




Not Displayed Y

/usTaxProfile/usFederalTaxInstruction/soci

alSecurityTaxInstruction/


codeValue/usTaxProfile/

usFederalTaxInstruction/



shortName

Do not Calculate

Social Security

N Only codeValue

required.

Use Cases 8




Required

(Y/N)

Note




Not Displayed N




Effective N


medicareTaxInstruction

Not Displayed N


medicareTaxInstruction/


Not Displayed N




Not Displayed N




codeValue

Do not calculate

Medicare

Y

/usTaxProfile/usFederalTaxInstruction/me

dicareTaxInstruction/taxWithholdingStatus

/statusCode/shortName

N Only codeValue

required.


federalUnemploymentTaxInstruction

Not Displayed N


federalUnemploymentTaxInstruction/


Not Displayed N




Not Displayed N

Use Cases 9




Required

(Y/N)

Note




codeValue

Do not Calculate

F.U.T.A Taxable

Y




shortName

N Only codeValue

required.




Not Displayed N




Effective N


form1099Instruction

Not Displayed N


form1099Instruction/distributionCodes

N


form1099Instruction/distributionCodes/

codeValue

Box 7 for Distribution

Code 1

Box 7 for Distribution

Code 2

Y


form1099Instruction/

totalDistributionIndicator

Box 2B for Total

Distribution

N



individualRetirementAccountIndicator

Box 7 for IRA/SEP

Distribution

N

Use Cases 10




Required

(Y/N)

Note



simplifiedEmployeePensionAccount

Indicator

Box 7 for IRA/SEP

Distribution

N


interimW2IssuesIndicator

Reissue W-2 for

terminated employee

[Check Box]

N


statutoryWorkerIndicator

Statutory employee

[Check Box]

N


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.


200.response.json

Passing asOfDate as the

past date when making a

request.


PAST-asOfDate-

200.response.json

When making a request with

asOfDate as future date.


Future-asOfDate-

200.response.json

https://developers.adp.com/services/elasticSearch/articles/general/d8ec94ad8e656f716d0244cfb0904876cac6cc4f/doc/APICommonExceptionsandTipsforHandling.pdf




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-PAST-asOfDate-200.response.json








Use Cases 11



Response

Code Condition message txt

GitHub Sample

Response Payload Tips to Handle

400 Bad

Request


asOfDate, but there is no

record previous to the

asOfDate passed in the end

point.

"userMessage": {

"messageTxt": "As

Of Date is invalid."

}


Invalid-asOfDate-

400.response.json


an invalid associate ID.

"userMessage": {

"messageTxt":

"AOID is invalid."

}


InvalidAssociate-

400.response.json

For a list of other use cases, see Use Cases on page 3.

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-asOfDate-400.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-InvalidAssociate-400.response.json




Use Cases 12



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.


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




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


payrollFileNumber

Y

/events/data/eventContext/usTaxProfiles/payrollGr

oupCode

Not Displayed Y


payrollGroupCode/codeValue

Company Code Y

/events/data/transform Not Displayed Y

/events/data/transform/usTaxProfile/

usFederalTaxInstruction/multipleJobIndicator

Multiple Jobs

Indicator

N


additionalStatutoryInputs/FormatCode

Non Resident

Alien

This field also

enables the

form 2020 or

PRE2020

based on the

FormatCode.

Y


additionalStatutoryInputs/TagCode


additionalStatutoryInputs/TagValues


additionalStatutoryInputs/DataTypeCode

Use Cases 14




Required

(Y/N)

Note


federalIncomeTaxInstruction/taxAllowances/

allowanceTypeCode/codeValue

Dependents |

Deductions


federalIncomeTaxInstruction/taxAllowances/

taxAllowanceAmount/amountValue



additionalIncomeAmount/amountValue

Other Income


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


federalIncomeTaxInstruction/taxWithholdingStatus

Not Displayed N


federalIncomeTaxInstruction/taxWithholdingStatus/

statusCode

Not Displayed N



statusCode/codeValue

Do not calculate

Federal Income

Tax

N

Use Cases 15




Required

(Y/N)

Note



statusCode/shortName

Do not calculate

Federal Taxable

N Only codeValue is

required for updates.


federalIncomeTaxInstruction/taxFilingStatusCode

Not Displayed N


federalIncomeTaxInstruction/taxFilingStatusCode/

codeValue

Marital Status N


federalIncomeTaxInstruction/taxFilingStatusCode/

longName

N Only codeValue is




taxWithholdingAllowanceQuantity

Exemptions N



additionalTaxPercentage

Additional Tax

Amount

N


federalIncomeTaxInstruction/additionalTaxAmount

Not Displayed N


federalIncomeTaxInstruction/additionalTaxAmount/

amountValue

Additional Tax

Amount

N



Not Displayed N


socialSecurityTaxInstruction/taxWithholdingStatus

Not Displayed N

Use Cases 16




Required

(Y/N)

Note


socialSecurityTaxInstruction/taxWithholdingStatus/

statusCode

Not Displayed N







Do not Calculate

Social Security

N Only codeValue is




Not Displayed N


medicareTaxInstruction/taxWithholdingStatus

Not Displayed N


medicareTaxInstruction/taxWithholdingStatus/

statusCode

Not Displayed N




Do not calculate

Medicare

N




Only codeValue

Required for updates


federalUnemploymentTaxInstruction

Not Displayed N




Not Displayed N

Use Cases 17




Required

(Y/N)

Note




Not Displayed N



taxWithholdingStatus/statusCode/codeValue

Do not Calculate

F.U.T.A Taxable

N



taxWithholdingStatus/statusCode/shortName

Only codeValue is



form1099Instruction

Not Displayed N


form1099Instruction/distributionCodes

Not Displayed N


form1099Instruction/distributionCodes/codeValue

Box 7 for

Distribution

Code 1

Box 7 for

Distribution

Code 2

N


form1099Instruction/totalDistributionIndicator

Box 2B for Total

Distribution

N


form1099Instruction/individualRetirementAccountI

ndicator

Box 7 for

IRA/SEP

Distribution

N


form1099Instruction/simplifiedEmployeePensionAc

countIndicator

W-2 Box 13

Retirement

Plan/Qualified

Pension

N

Use Cases 18




Required

(Y/N)

Note


interimW2IssuesIndicator

Reissue W-2 for

terminated

employee

N



Statutory

employee

N


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


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


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.

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-married-dollar-200.request.json





https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-married-dollar-200.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/federal-usTaxProfile-metaRes-200.response.json



Use Cases 19



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

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-currentDate-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-currentDate-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-exemptChecked-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-exemptChecked-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-otherIncome-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-otherIncome-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-deductions_dependents-200.request.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-deductions_dependents-200.response.json




Use Cases 20



Response

Code


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


status is "M" – Married.

federal-change-

PRE2020_M-

200.request.json

federal-change-

PRE2020_M-

200.response.json


status is "S" – Single.

federal-change-

PRE2020_S-

200.request.json

federal-change-

PRE2020_S-

200.response.json


status is "D" – Single or

Married Filing Separately.

federal-change-

2020_D-

200.request.json

federal-change-

2020_D-

200.response.json


status is "J" – Married filing

jointly (or Qualifying

widower).

federal-change-

2020_J-

200.request.json

federal-change-

2020_J-

200.response.json


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

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_MH-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_MH-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_M-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_M-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_S-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-PRE2020_S-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_D-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_D-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_J-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_J-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_H-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-2020_H-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-multipleJobIndicator-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-multipleJobIndicator-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-Non_resident_alien-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-Non_resident_alien-200.response.json



Use Cases 21



Response

Code


Request Payload

GitHub Sample

Response Payload

Tips to Handle

200 OK

(cont.)

Returns when the following

fields are checked:

socialSecurityTax

Instruction



indiviualRetirement

AccountIndicator

simplifiedEmployee

PensionAccountIndicator

interimW2IssuedIndicator


qualifiedPension

Plan

CoverageIndicator

federal-change-

IndicatorAllChecked-

200.request.json

federal-change-

IndicatorAllChecked-

200.response.json

Returns when the following

fields are Unchecked:

socialSecurityTax

Instruction



indiviualRetirement

AccountIndicator

simplifiedEmployee

PensionAccountIndicator

interimW2IssuedIndicator


qualifiedPensionPlan

CoverageIndicator

federal-change-

IndicatorAllUnchecked-

200.request.json

federal-change-

IndicatorAllUnchecke

d-200.response.json

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-IndicatorAllChecked-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-IndicatorAllChecked-200.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-IndicatorAllUnchecked-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-IndicatorAllUnchecked-200.response.json



Use Cases 22



Response

Code


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.


Invalid-associateID-

400.request.json


Invalid-associateID-

400.response.json

Returns when Invalid payroll

company code is passed in

request payload.


Invalid-companyCode-

400.request.json


Invalid-

companyCode-

400.response.json

Returns when Invalid payroll

file number is passed in

request payload.


Invalid-filenumber-

400.request.json


Invalid-filenumber-

400.response.json

Returns when Invalid

effective date value is

passed in request payload.


Invalid-effectiveDate-

400.request.json


Invalid-effectiveDate-

400.response.json


taxFilingStatusCode value is



Invalid-

taxfillingStatusCode-

400.request.json


Invalid-

taxFillingstatusCode-

400.response.json



value is passed in request

payload.


Invalid-

socialSecurityTaxInstru

ction-400


Invalid-

socialSecuritytaxInstr

uction-400



value is passed in request

payload.


Invalid-

MedicaretaxInstruction

-400


Invalid-

MedicaretaxInstructio

n-400

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-Form1099Notselected-200.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/success/2020-Enhancements/federal-change-Form1099Notselected-200.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-associateID-400.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-associateID-400.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-companyCode-400.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-companyCode-400.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-filenumber-400.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-filenumber-400.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-effectiveDate-400.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-effectiveDate-400.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-taxfillingStatusCode-400.request.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-taxFillingstatusCode-400.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-socialSecurityTaxInstruction-400.request.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-socialSecuritytaxInstruction-400.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-MedicaretaxInstruction-400.request.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-MedicaretaxInstruction-400.response.json




Known Issues and Limitations 23



Response

Code


Request Payload

GitHub Sample

Response Payload

Tips to Handle

400 Bad

Request

(cont.)


form1099Instruction code is



Invalid-

form1099InstructionCo

de-400


Invalid-

form1099Instruction

Code-400

Returns when Invalid ItemId

value is missing in the

request payload.


Invalid-ItemID-

400.request.json


Invalid-ItemID-

400.response.json

500

Internal

Server

Error

Returns when empty ItemId

value is missing in the

request payload.


empty-ItemID-

500.request.json


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.

https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-form1099InstructionCode-400.request.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-form1099InstructionCode-400.response.json




https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-ItemID-400.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-Invalid-ItemID-400.response.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-empty-ItemID-500.request.json



https://github.com/adpllc/marketplace-sample-payloads/blob/master/wfn/payroll/us-tax-profile/federal/errors/federal-usTaxProfile-empty-ItemID-500.response.json



Known Issues and Limitations 24



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



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.

https://supportiat.adp.com/basic/cr/wfn/help/wfn_19/en_us/pract/hr_payroll/all_core/eff_date/eff_date_other_records_pract_task.htm

Appendix – Adding or Changing an Employee’s Federal Tax Information 26



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.


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.


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.


Enter additional tax

information

Select the appropriate values in the Other Codes section.


5. Click Done.

U.S. Federal Tax Withholding API Guide for ADP Workforce Now

Documents

Transcript of U.S. Federal Tax Withholding API Guide for ADP Workforce Now