Work Assignment API Guide for ADP Workforce Now
ADP Copyright Information
ADP, the ADP logo, Always Designing for People, 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/31/2019 3:23 PM
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Contents
About the Work Assignment API .............................................................................................................. 1
Supported Product Version and Customer Base ...................................................................................... 1
Required Setup Steps .............................................................................................................................. 1
Postman Collection .................................................................................................................................. 2
Use Case - Updating Work Assignment Details for an Employee ............................................................. 2
Use Case Description ........................................................................................................................... 2
API Usage ............................................................................................................................................ 2
Application Scope ................................................................................................................................. 2
Supported Actors .................................................................................................................................. 3
Request Header Parameters ................................................................................................................ 3
Sequence of Interactions ...................................................................................................................... 3
Data Dictionary ..................................................................................................................................... 4
Responses ........................................................................................................................................... 6
Known Issues and Limitations – USXXXX: Event notification not supported ............................................ 9
Impacted APIs ...................................................................................................................................... 9
Issue Description ................................................................................................................................ 10
Suggested Workaround ...................................................................................................................... 10
About the Work Assignment API 1
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
About the Work Assignment API
Work Assignment Application Programming Interface (API) updates the work assignments details such
as a worker’s Job Title and Job Function.
Supported Product Version and Customer Base
The Work Assignment API is available for United States (U.S.) clients in ADP Workforce Now.
Required Setup Steps
Clients need to make sure the codes used by your application are added and configured in ADP
Workforce Now. Refer to the following table on setup pages.
Records ADP Workforce Now
Job Title Setup > Tools > Validation Tables > Employment Profile > Position > Job
Title
Job Change Reason Setup > Tools > Validation Tables > Employment Profile > Position > Job
Change Reasons
Job Function Setup > Tools > Validation Tables > Employment Profile > Position > Job
Function
Job Class Setup > Tools > Validation Tables > Employment Profile > Position > Job
Class
FLSA Code Setup > Tools > Validation Tables > Employment Profile > Position > FLSA
Code
NAICS Workers
Comp
Setup > Tools > Validation Tables > Employment Profile > Position >
NAICS Workers Comp
Pay Grade Setup > Tools > Validation Tables > Employment Profile > Pay Rates > Pay
Grade
EEO Establishment Setup > Tools > Validation Tables >Employment Profile > Position > EEO
Establishment
Postman Collection 2
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
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 Work Assignment API from the ADP GitHub library and import them
to Postman, go to Postman Collection.
Use Case - Updating Work Assignment Details for
an Employee
Use Case Description
The Work Assignment API updates the work assignments for a worker.
API Usage
Method Uniform Resource
Identifier (URI)
Description Sample Request
Payload
Sample Response
Payload
POST /events/hr/v1/worker.work-
assignment.modify
Updates work
assignment
details for an
Associate.
Workassignment-
update-success-http-
200-request.json
Workassignment-
update-success-http-
200-response.json
GET /events/hr/v1/worker.work-
assignment.modify/meta
Retrieves the
meta
information.
NA workassignment-
meta-call-http-200-
response.json
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 canonical needs to be added to your application scope to enable this use case:
/hr/workerInformationManagement/workerManagement/workAssignmentManagement
/worker.workAssignment.modify
Use Case - Updating Work Assignment Details for an Employee 3
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Supported Actors
Request Parameter
roleCode Value:
Practitioner
Usage: Updates work assignment details for an employee as a practitioner. A
system user is considered a practitioner.
Request Header Parameters
There are no Request Header Parameters, in addition to the ADP standard header parameters.
Sequence of Interactions
1. Your consumer application makes a request for /events/hr/v1
/worker.work-assignment.modify/meta to the ADP API endpoint.
2. The ADP API endpoint responds to your consumer application with the meta payload. See the
table in Responses on page 6. Your consumer application processes the meta payload to
validate data included in the payload in step 3 and prompts the user to fix any validation issues.
Otherwise, compose the payload for the /events/hr/v1/worker.work-assignment.modify request.
3. Your consumer application makes an /events/hr/v1/worker.work-assignment.modify request to the
ADP API endpoint.
4. The ADP API endpoint responds to the consumer application concerning the details of
/events/hr/v1/worker.work-assignment.modify request.
Use Case - Updating Work Assignment Details for an Employee 4
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Data Dictionary
Resources listed in the following table can be accessed in ADP Workforce Now, under People >
Employment > Employment Profile > Position.
Schema Location Field Name in ADP
Workforce Now
User Interface (UI)
Is
Required
(Y/N)
Note
/associateOID Not Displayed Y
/workAssignmentID Not Displayed Y
The workAssignmentID
can be obtained by making
hr/v2/workers API call. Use
itemID under
workAssignments of API
response.
/effectiveDateTime Effective Y
/eventReasonCode Job Change
Reason
Y
/eventReasonCode/codeValue
/workAssignment/wageLawCoverage FLSA Y
/workAssignment/wageLawCoverage/c
overageCode
/workAssignment/wageLawCoverage/c
overageCode/codeValue
/workAssignment/expectedStartDate Position Start Date Y
/workAssignment/jobTitle Job Title Y
/workAssignment/JobFunctionCode Job Function Y
/workAssignment/JobFunctionCode
/codeValue
Use Case - Updating Work Assignment Details for an Employee 5
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name in ADP
Workforce Now
User Interface (UI)
Is
Required
(Y/N)
Note
/workAssignmentManagement
/PositionIndicator
Management
Position
Y
/workAssignment/PayGradeCode Pay Grade Y
/workAssignment/PayGradeCode
/codeValue
/workAssignment/Industry
Classifications
NAICS Worker's
Comp
Y
/workAssignment/Industry
Classifications/ClassificationCode
/workAssignment/Industry
Classifications/ClassificationCode
/codeValue
/workAssignment/Occupational
Classifications
EEOC/Job
Class/EEO
Establishment
Y
/workAssignment/Occupational
Classifications/NameCode
/workAssignment/Occupational
Classifications/NameCode/codeValue
/workAssignment/Occupational
Classifications/ClassificationCode
EEOC Job
Classification
or
Job Class
or
EEO Establishment
Y
/workAssignment/Occupational
Classifications/ClassificationCode
/codeValue
Use Case - Updating Work Assignment Details for an Employee 6
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Schema Location Field Name in ADP
Workforce Now
User Interface (UI)
Is
Required
(Y/N)
Note
/workAssignment/OfficerTypeCode Officer/Owner Y
/workAssignment/OfficerTypeCode
/codeValue
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 messageTxt
GitHub Sample
Request
Payload
GitHub Sample
Response
Payload
Tips to
Handle
200 OK
Update work
assignment details
for an employee
with valid data.
NA
Workassignment
-update-success-
http-200-
request.json
Workassignment
-update-
success-
http-200-
response.json
400 Bad
Request
Update work
assignment details
with Incorrect
Associate ID.
"userMessage": {
"messageTxt":
"associateOID is
invalid." }
Workassignment
-invalid-AOID-
http-400-
request.json
Workassignment
-invalid-AOID-
http-400-
response.json
Update work
assignment details
with Invalid Work
assignment ID.
"userMessage": {
"messageTxt":
"workAssignmentID is
invalid."
Workassignment
-invalid-itemID-
http-400-
request.json
Workassignment
-invalid-itemID-
http-400-
response.json
Update work
assignment details
with Invalid code
value for the job
change reason.
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/workAssignm
ent/eventReasonCode/
codeValue is invalid." }
Workassignment
-invalid-
JobReason-http-
400-request.json
Workassignment
-invalid-
JobReason-http-
400-
response.json
Use Case - Updating Work Assignment Details for an Employee 7
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code Condition messageTxt
GitHub Sample
Request
Payload
GitHub Sample
Response
Payload
Tips to
Handle
400 Bad
Request
(cont.)
Update work
assignment details
with Invalid Effective
date.
"userMessage": {
"messageTxt":
"transform/
effectiveDateTime is
not a valid date. Enter
the date in the format
yyyy-MM-dd."}
workassignment-
invalid-
effectiveDate
Time-http-400-
request.json
workassignment-
invalid-
effectiveDate
Time-http-400-
response.json
Update work
assignment details
with Invalid
wageLawcoverage
(FLSA).
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/work
Assignment/wageLaw
Coverage is invalid." }
Workassignment
-invalid-wageLaw
coverage-http-
400-request.json
Workassignment
-invalid-
wageLaw
coverage-
http-400-
response.json
Update work
assignment details
with invalid position
start date.
"userMessage": {
"messageTxt": "An
employee's position
start date must be
greater than or equal
to the effective hire
date (the greater of the
hire date or the rehire
date)." }
workassignment-
invalid-
positionstartdate-
http-400-
request.json
workassignment-
invalid-
positionstartdate
-http-400-
response.json
Update work
assignment details
with invalid Job
Title.
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/workAssignm
ent/jobTitle is invalid."
}
Workassignment
-invalid-jobTitle-
http-400-
request.json
Workassignment
-invalid-jobTitle-
http-400-
response.json
Update work
assignment details
with invalid JOB
function code.
"userMessage":{
"messageTxt":"/events/
data/transform/workers
/workAssignment
/jobFunctionCode/code
Value is invalid." }
Workassignment
-invalid-
jobfunction-code-
http-400-
request.json
Workassignment
-invalid-
jobfunction-
code-http-400-
response.json
Use Case - Updating Work Assignment Details for an Employee 8
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code Condition messageTxt
GitHub Sample
Request
Payload
GitHub Sample
Response
Payload
Tips to
Handle
400 Bad
Request
(cont.)
Update work
assignment details
with invalid NAICS
(industry
classification code)
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/workAssignm
ent/industryClassificati
ons/classificationCode
is invalid." }
Workassignment
-invalid-industry
classification-
code-http-400-
request.json
Workassignment
-invalid-industry
classification-
code-http-400-
response.json
Update work
assignment details
with Invalid
officerTypeCode.
"userMessage": {
"messageTxt":
"/events/data
/transform/workers
/workAssignment
/officerTypeCode/code
Value is invalid." }
Workassignment
-invalid-
officerTypecode-
code-http-400-
request.json
Workassignment
-invalid-
officerTypecode-
code-http-400-
response.json
Update work
assignment details
with Invalid Pay
grade code.
"userMessage": {
"messageTxt":
"/events/data
/transform/workers
/workAssignment
/payGradeCode is
invalid." }
Workassignment
-invalid-
payGrade-code-
http-400-
request.json
Workassignment
-invalid-
payGrade-code-
http-400-
response.json
Known Issues and Limitations – USXXXX: Event notification not supported 9
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Response
Code Condition messageTxt
GitHub Sample
Request
Payload
GitHub Sample
Response
Payload
Tips to
Handle
400 Bad
Request
(cont.)
Update work
assignment details
with invalid EEOC
job classification
code.
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/work
Assignment
/occupational
Classifications/
classificationCode
(EEOC) is invalid." }
Workassignment
-invalid-
jobclassification-
code-http-400-
request.json
Workassignment
-invalid-
jobclassification-
code-http-400-
response.json
Update work
assignment details
with invalid EEO
Establishment.
"userMessage": {
"messageTxt":
"/events/data/transform
/workers/work
Assignment/
occupational
Classifications/
classificationCode/
codeValue (EEO
Establishment) is
invalid." }
Workassignment
-invalid-EEO-
Estalishment-
http-400-
request.json
Workassignment
-invalid-EEO-
Estalishment-
http-400-
response.json
Known Issues and Limitations – USXXXX: Event
notification not supported
This section details all reported and known issues. This is so developers can be aware of those issues
when using APIs.
Impacted APIs
Method: POST
URI: /events/hr/v1/worker.work-assignment.modify
roleCode: Practitioner
Known Issues and Limitations – USXXXX: Event notification not supported 10
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.
Copyright © 2019 ADP, LLC.
Issue Description
When a change is made to the position details of an associate, either through the
/events/hr/v1/worker.work-assignment.modify API or ADP Workforce Now, event notifications are not
generated to Infolink. Infolink is unable to retrieve the event notifications through the GET event
notification call.
Suggested Workaround
There are no workarounds available.