ADP Developer Resources

Chapter 1

About the Guide

Summary

The Worker Management API Guide for ADP Vantage describes how your application can access and manage information about workers in the ADP Vantage application. It helps you to determine which use case best meets your business needs. It also guides you through the implementation of each use case.

A worker is a person who performs duties and responsibilities for an organization. In that capacity, a worker fills one or more positions through a work assignment. For a given work assignment, a worker is related to the organization as an employee or contractor.

What's New in this Guide?

In this section, we will announce any new revisions to the Worker Management Application Programming Interface (API) and this guide.

December 2020

Added new Chapter 2: Retrieving Full Worker Information.

Process Overview

The following table shows how your data connector application would be used by a client.

	Actor	Task Description
1	Client Practitioner	Trigger the API-based data exchange between your application and ADP Vantage HCM
2	Your application	Retrieve worker information details based on your needs.
3	Your application	Retrieve event notifications and make updates in your system according to your needs so the data is synchronized between your application and ADP Vantage HCM.
4	Your application	Send worker updates to ADP Vantage HCM as your application collects the updates.
5	Client Practitioner	Verify the Information in ADP Vantage HCM

Chapter 2

Use Case: Retrieving Full Worker Information

Before You Begin

Full worker information commonly requested includes the following:

Name
Address
Communication profile
Birth date
Government IDs
Hire dates
Work status
Work assignment information, such as the following:
- Job title
- Pay information
- Manager/reports to information
- Custom fields

Use Case Description

This use case retrieves details of a single worker or a collection of workers with all the above mentioned information.

API Usage

Method	Uniform Resource Identifier (URI)	Description	GitHub Sample Response Payload
GET	/hr/v2/workers	Requests the list of all available workers the requester is authorized to view. Note:At once API maximum of 2500 records.	Retrieve-all-workers-details-http-200-response.json
GET	/hr/v2/workers/meta	Returns a meta for a worker's call.	Retrieve-single-associate-details-http-200-response.json
GET	/hr/v2/workers/{associate-oid}	Requests a single worker the requester is authorized to view.	workers-v2-meta-http-200-response.json

Method

Uniform Resource Identifier (URI)

Description

GitHub Sample Response Payload

GET

/hr/v2/workers

Requests the list of all available workers the requester is authorized to view.

Note:At once API maximum of 2500 records.

Retrieve-all-workers-details-http-200-response.json

GET

/hr/v2/workers/meta

Returns a meta for a worker's call.

Retrieve-single-associate-details-http-200-response.json

GET

/hr/v2/workers/{associate-oid}

Requests a single worker the requester is authorized to view.

workers-v2-meta-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:

Scope
/hr/workerInformationManagement/workerManagement/workerProfileManagement/worker.read

Supported Actors

Request Parameter roleCode Value	Usage
Practitioner	Retrieves a list of all available workers information as a practitioner. A system user is considered a practitioner.

Request Header Parameters

Parameter Name	Required (Y/N)	Usage	Sample
Accept	Y	To reveal masked data.	application/json;masked=false

Sensitive Information Masking

To establish compliance with data security best-practices, our Worker V2 API only returns the month and day of the Birth Date and the last four numbers of the Social Security Number (SSN) unless you specify that you want to see the values unmasked in your Hypertext Transfer Protocol (HTTP) request. To see these values unmasked, simply add the following header to your HTTP request:

Accept: application/json;masked=false

Supported OData Query Options

This use case supports Query String Options as defined by Open Data Protocol (OData). For more information about OData, see Introduction to ADP API Open Data Protocol (OData).

Query String Option	Description	Example
$top	Requests the number of items in the queried collection to be included in the result.	hr/v2/workers?$top=100
$skip	Starts with record offset 101 and returns the next 100 employees	/hr/v2/workers?$top=100&$skip=100
$filter	Filters a collection of resources addressed by a request Uniform Resource Locator (URL). Only items for which the expression evaluates to true are included in the response.	/hr/v2/workers?$filter=workers/workAssignments/reportsTo/positionID eq '93V000061'

Filtering capabilities on GET Workers V2 collections

Schema	Field Name in ADP Vantage HCM	API URI Example
workers/workerStatus/statusCode/codeValue	Employment Status (i.e. Active, Inactive, etc.)	/hr/v2/workers?$filter=workers/workerStatus/status Code/codeValue%20eq%20'xxxxxx'
workers/workAssignments/jobCode/codeValue	Job Code	/hr/v2/workers?$filter=workers/workAssignments/jobCode/codeValue%20eq%20'xxxxxx'
workers/workAssignments/homeOrganizationalUnits/nameCode/codeValue	Cost Number	/hr/v2/workers?$filter=workers/workAssignments/homeOrganizationalUnits/nameCode/codeValue eq 'xxxxxx'
workers/workAssignments/assignedOrganizationalUnits/nameCode/codeValue	Department ID	/hr/v2/workers?$filter=workers/workAssignments/assignedOrganizationalUnits/nameCode/codeValue eq 'xxxxxx'
workers/workAssignments/homeWorkLocation/nameCode/codeValue	Reporting Location	/hr/v2/workers?$filter=workers/workAssignments/homeWorkLocation/nameCode/codeValue eq 'xxxxxx'
workers/workAssignments/assignedWorkLocations/nameCode/codeValue	Job Location	/hr/v2/workers?$filter=workers/workAssignments/assignedWorkLocations/nameCode/codeValue eq 'xxxxxx'
workers/workerDates/originalHireDate	Employment Hire Date	/hr/v2/workers?$filter=workers/workerDates/originalHireDate eq '2016-04-28' or /hr/v2/workers?$filter=workers/workerDates/originalHireDate ge '2016-04-28' or /hr/v2/workers?$filter=workers/workerDates/originalHireDate le '2016-04-28'
workers/workerDates/rehireDate	Employment Rehire Date	/hr/v2/workers?$filter=workers/workerDates/rehireDate eq '2020-06-29' /hr/v2/workers?$filter=workers/workerDates/rehireDate lt '2020-06-29' /hr/v2/workers?$filter=workers/workerDates/rehireDate gt '2020-06-29'
workers/workerDates/terminationDate	Employment Termination Date	/hr/v2/workers?$filter=workers/workerDates/terminationDate eq '2020-06-22' /hr/v2/workers?$filter=workers/workerDates/terminationDate lt '2020-06-22' /hr/v2/workers?$filter=workers/workerDates/terminationDate gt '2020-06-22' /hr/v2/workers?$filter=workers/workerDates/terminationDate le '2020-06-22' /hr/v2/workers?$filter=workers/workerDates/terminationDate ge '2020-06-22'

Sequence of Interactions

The following are the sequence of interactions to retrieve full worker information for a collection of workers:

Your consumer application makes a request for an initial collection of workers to the ADP API endpoint.
The ADP API endpoint responds to your consumer application with a collection of workers.
Your consumer application makes a request for a subsequent collection of workers to the ADP API endpoint.
The ADP API endpoint responds to your consumer application with a collection of workers.

Your consumer application repeats steps 3 and 4 until a 204 No Content Hypertext Transfer Protocol (HTTP) response status code is returned.

Chapter 3

Use Case: Updating worker's Data

People > Employee Profile > Personal Information >Name

ADP Vantage HCM Field Name	Application scope	API and Event Type	Description	Github Sample Request Payload	Github Sample Response Payload
Legal Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.legalName.change	/events/hr/v1/worker.legal-name.change	Updates a Worker's legal name	worker.legal-name-change-http-200-request.json	worker.legal-name-change-http-200-response.json
Preferred Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.preferredName.change	/events/hr/v1/worker.preferred-name.change	Updates a workers preferred name	worker.preferred-name-change-http-200-request.json	worker.preferred-name-change-http-200-response.json
Former Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.formerName.change	/events/hr/v1/worker.former-name.change	Updates a workers former name	worker.former-name-change-http-200-request.json	worker.former-name-change-http-200-response.json

For more information on Name change APIs, refer Worker Name Change API Guide for ADP Vantage HCM

People > Employee Profile > Personal Information > Addresses

ADP Vantage HCM Field Name	Application scope	API and Event Type	Description	Github Sample Request Payload	Github Sample Response Payload
Legal Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.legalAddress.change	/events/hr/v1/worker.legal-address.change	Updates a worker's legal address.	legal-address.change-http-200-request.json	legal-address.change-http-200-response.json
Personal Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.add	/events/hr/v1/worker.personal-address.add	Adds a worker's personal address.	personal-address.add-http-200-request.json	personal-address.add-http-200-response.json
Personal Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.change	/events/hr/v1/worker.personal-address.change	Updates a Worker's Personal address.	personal-address.change-http-200-request.json	personal-address.change-http-200-response.json

For more information on Address change APIs, refer Worker Address API Guide for ADP Vantage HCM

People > Employee Profile >Personal Information >Contact Information

ADP Vantage HCM Field Name	Application Scope	API and Event Type	Description	GitHub Sample Request Payload	GitHub Sample Response Payload
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.add	/events/hr/v1/worker.personal-communication.landline.add	Adds a worker's personal landline number.	Personal Communication landline add request	Personal Communication landline response
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.change	/events/hr/v1/worker.personal-communication.landline.change	Changes a worker's personal landline number.	Personal Communication landline change request	Personal Communication landline change response
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.remove	/events/hr/v1/worker.personal-communication.landline.remove	Removes a worker's personal landline number.	Personal Communication landline remove request	Personal Communication landline remove response
Personal Email	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.add	/events/hr/v1/worker.personal-communication.email.add	Add a worker's personal email address.	Personal Communication email add request	Personal Communication email add response
Personal Email	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.change	/events/hr/v1/worker.personal-communication.email.change	Changes a worker's personal email address.	Personal Communication email change request	Personal Communication email change response
Personal Email	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.remove	/events/hr/v1/worker.personal-communication.email.remove	Removes a worker's personal email address.	Personal Communication email remove request	Personal Communication email remove response
Home Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.add	/events/hr/v1/worker.personal-communication.fax.add	Adds a worker's personal fax number.	Personal Communication fax add request	Personal Communication fax add response
Home Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.change	/events/hr/v1/worker.personal-communication.fax.change	Changes a worker's personal fax number.	Personal Communication fax change request	Personal Communication fax change response
Home Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.remove	/events/hr/v1/worker.personal-communication.fax.remove	Removes a worker's personal fax number.	Personal Communication fax remove request	Personal Communication fax remove response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.mobile.add	/events/hr/v1/worker.personal-communication. mobile.add	Adds a worker's personal mobile telephone number.	Personal Communication mobile add request	Personal Communication mobile add response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.mobile.change	/events/hr/v1/worker.personal-communication.mobile.change	Changes a worker's personal mobile telephone number.	Personal Communication mobile change request	Personal Communication mobile change response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.personalCommunication.mobile.remove	/events/hr/v1/worker.personal-communication.mobile.remove	Removes a worker's personal mobile telephone number.	Personal Communication mobile remove request	Personal Communication mobile remove response
Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.add	/events/hr/v1/worker.personal-communication.pager.add	Adds a worker's personal pager number.	Personal Communication pager add request	Personal Communication pager add response
Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.change	/events/hr/v1/worker.personal-communication.pager.change	Changes a worker's personal pager number.	Personal Communication pager change request	Personal Communication pager change response
Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.remove	/events/hr/v1/worker.personal-communication.pager.remove	Removes a worker's personal pager number.	Personal Communication pager remove request	Personal Communication pager remove response
Work Cell	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.mobile.add	/events/hr/v1/worker.business-communication.mobile.add	Adds a worker's business mobile telephone number.	Business Communication mobile add request	Business Communication mobile add response
Work Cell	/hr/workerInformation Management /workerManagement/communication Management /worker.business Communication.mobile. change	/events/hr/v1/worker.business-communication.mobile.change	Changes a worker's business mobile telephone number.	Business Communication mobile change request	Business Communication mobile change response
Work Cell	/hr/workerInformation Management /workerManagement/communication Management /worker.business Communication.mobile. remove	/events/hr/v1/worker.business-communication.mobile.remove	Removes a worker's business mobile telephone number.	Business Communication mobile remove request	Business Communication mobile remove response
Work Email	/hr/workerInformation Management /workerManagement/communication Management /worker.business Communication. email.add	/events/hr/v1/worker.business-communication.email.add	Adds a worker's business email address.	Business communication email add request	Business communication email add response
Work Email	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.businessCommunication.email. change	/events/hr/v1/worker.business-communication.email.change	Changes a worker's business email address.	Business Communication email Change request	Business communication email change response
Work Email	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.businessCommunication.email. remove	/events/hr/v1/worker.business-communication.email.remove	Removes a worker's business email address.	Business Communication email remove request	Business Communication email remove response
Work Fax	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.businessCommunication.fax.add	/events/hr/v1/worker.business-communication.fax.add	Adds a worker's business fax number.	Business Communication fax add request	Business Communication fax add response
Work Fax	/hr/workerInformationManagement /workerManagement/communicationManagement /worker.businessCommunication.fax. change	/events/hr/v1/worker.business-communication.fax.change	Changes a worker's business fax number.	Business communication fax change request	Business communication fax change response
Work Fax	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.businessCommunication.fax. remove	/events/hr/v1/worker.business-communication.fax.remove	Removes a worker's business fax number.	Business Communication fax remove request	Business Communication fax remove response
Office	/hr/workerInformationManagement/workerManagement/communicationManagement /worker.businessCommunication.landline. add	/events/hr/v1/worker.business-communication. landline.add	Adds a worker's business landline number.	Business Communication landline add request	Business Communication landline add response
Office	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.landline.change	/events/hr/v1/worker.business-communication.landline.change	Changes a worker's business landline number.	Business Communication landline change request	Business Communication landline change response
Office	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.landline.remove	/events/hr/v1/worker.business-communication.landline.remove	Removes a worker's business landline number.	Business Communication landline remove request	Business Communication landline remove response

Data Dictionary

The client practitioner can manage data controls in the ADP Vantage user interface (UI) by selecting People > Employee Profile > Personal Information > Contact Information

Schema Location	Field Name in ADP Vantage HCM	Is Required (Y/N)	Note
/worker/person/communication/landline	Home Phone	Y
/worker/person/communication/landline/nameCode	Not Displayed	Y
/worker/person/communication/landline/nameCode/codeValue	Not Displayed	Y
/worker/person/communication/landline/countryDialing	Not Displayed	Y
/workers/person/communication/landlines/formattedNumber	Not Displayed	Y
/workers/person/communication/landlines/dialNumber	Not Displayed	N
/worker/person/communication/mobile	Personal Mobile	N
/workers/person/communication/mobiles/countryDialing	Not Displayed	Y
/workers/person/communication/mobiles/areaDialing	Not Displayed	N
/workers/person/communication/mobiles/formattedNumber	Not Displayed	Y
/workers/person/communication/faxes	Home Fax	N
/workers/person/communication/faxes/countryDialing	Not Displayed	Y
/workers/person/communication/faxes/areaDialing	Not Displayed	N
/workers/person/communication/faxes/formattedNumber	Not Displayed	Y
/workers/person/communication/pagers	Pager	N
/workers/person/communication/pagers/countryDialing	Not Displayed	Y
/workers/person/communication/pagers/areaDialing	Not Displayed	N
/workers/person/communication/pagers/formattedNumber	Not Displayed	Y
/workers/person/communication/pagers/extension	Not Displayed	N
/workers/person/communication/emails/emailUri	Personal Email	Y
/workers/businessCommunication/landlines	Office	N
/workers/businessCommunication/landlines/countryDialing	Not Displayed	Y
/workers/businessCommunication/landlines/areaDialing	Not Displayed	N
/workers/businessCommunication/landlines/formattedNumber	Not Displayed	Y
/workers/businessCommunication/landlines/extension	Extension	N	Displayed under Extension section, on the Office field.
/workers/businessCommunication/mobiles	Work Cell	N
/workers/businessCommunication/mobiles/countryDialing	Not Displayed	N
/workers/businessCommunication/mobiles/areaDialing	Not Displayed	N
/workers/businessCommunication/mobiles/formattedNumber	Not Displayed	Y
/workers/businessCommunication/faxes	Work Fax	N
/workers/businessCommunication/faxes/countryDialing	Not Displayed	Y
/workers/businessCommunication/faxes/areaDialing	Not Displayed	N
/workers/businessCommunication/faxes/formattedNumber	Not Displayed	Y
/workers/businessCommunication/emails/emailUri	Work Email	Y

People > Employee Profile > Personal Information > Custom fields

ADP Vantage HCM Field Name	Application scope	API and Event Type	Description	Github Sample Request Payload	Github Sample Response Payload
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.date.change	/events/hr/v1/worker.person.custom-field.date.change	Updates a worker's custom field date	update-person-customfield-date-http-200-request.json	update-person-customfield-date-http-200-response.json
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.number.change	/events/hr/v1/worker.person.custom-field.number.change	Updates a worker's custom field numer	update-person-customfield-number-http-200-request.json	update-person-customfield-number-http-200-response.json
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.string.change	/events/hr/v1/worker.person.custom-field.string.change	Updates a worker's custom field String	update-person-customfield-string-http-200-request.json	update-person-customfield-string-http-200-response.json

For more information on Custom Field APIs, refer Worker Personal Custom Fields API Guide for ADP Vantage HCM

People > Employee Profile > Personal Information > Demographics

Description

This use case describes how to change an employee's Military classification and status in the ADP Vantage HCM UI.

API Usage

Method	Uniform Resource Identifier (URI)	Description	GitHub Sample Request Payload	GitHub Sample Response Payload
GET	/events/hr/v1/worker.military-classification.change/meta	Returns worker military classification change API meta data	NA	military-classification-change-meta-http-200-response.json
GET	/events/hr/v1/worker.military-status.change/meta	Returns worker military status change API meta data	NA	military-status-change-meta-http-200-response.json
POST	/events/hr/v1/worker.military-status.change	Posts a military status change information into ADP Vantage HCM.	update-military-status-http-200-request.json	update-military-status-http-200-response.json
POST	/events/hr/v1/worker.military-classification.change	Posts a military classification change information into ADP Vantage HCM.	update-military-classification-http-200-request.json	update-military-classification-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.

/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryClassification.change

/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryStatus.change

Supported Actors

Request Parameter roleCode Value	Supported (Y/N)?
Practitioner	Y

Request Header Parameters

Parameter Name	Required (Y/N)	Usage	Value
Content-Type	Y	application/json	Content-Type: application/json

Sequence of Interactions

Your consumer application makes a request to the ADP API endpoint for the Worker military status or classification change.
The ADP endpoint responds to your consumer application with the processing result.

Data Dictionary

This API exposes values found in the ADP Vantage HCM UI by selecting People > Employee Profile > Personal Information > Demographics.

Schema Location	Field Name in ADP Vantage HCM UI	Is Required (Y/N)
/worker/person/militaryClassificationCodes	Not displayed	Y
/worker/person/militaryClassificationCodes/codeValue	VETS-100A : Military Status	Y
/worker/associateOID	Not displayed	Y
/worker/person/militaryStatusCode	Not displayed	Y
/worker/person/militaryStatusCode/codeValue	Protected Veteran Status	Y
/worker/person/militaryDischargeDate	Military Discharge Date	N

Fields that Can't be Updated by this API

Schema Location	Field Name
People > Employee Profile > Personal Information > Demographics	Disabled

Responses

You may encounter exceptions outside your common success scenarios. You must account for the following 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 Success	Update military status of an employee	NA	update-military-status-http-200-request.json	update-military-status-http-200-response.json
200 Success	Update military classification of any employee	NA	update-military-classification-http-200-request.json	update-military-classification-http-200-response.json
200 Success	Update military status with discharge date of an employee	NA	update-military-status-discharge-date-http-200-request.json	update-military-status-discharge-date-http-200-response.json
200 Success	Update military status of an employee with incorrect/invalid military status longname	NA	update-military-status-with-incorrect-longname-http-200-request.json	update-military-status-with-incorrect-longname-http-200-response.json	Code value should be correct
200 Success	Update military classification of an employee with incorrect/invalid military classification longname	NA	update-military-classification-with-incorrect-longname-http-200-request.json	update-military-classification-with-incorrect-longname-http-200-response.json
400 Bad Request	Update military status of an employee with incorrect/invalid military status codevalue	"messageTxt": "You have entered an invalid value for Employee Personal Data-Military Status Vets 4212. Select a valid value from the list provided. (15,11)\n"	update-military-status-with-incorrect-codevalue-http-400-request.json	update-person-customfield-date-with-invalid-data-http-400-response.json
400 Bad Request	Update military classification of an employee with incorrect/invalid military classification codevalue	"messageTxt": "You have entered an invalid value for Employee Personal Data-Military Status Vets 100A. Select a valid value from the list provided. (15,11)\n"	update-military-classification-with-incorrect-codevalue-http-400-request.json	update-military-status-with-incorrect-codevalue-http-400-response.json
400 Bad Request	Update military status of an employee with incorrect/invalid military discharge date	"messageTxt": "The date you entered is invalid. Enter a valid date (-Military Discharge Date). (40,10)\n"	update-military-status-with-incorrect-discharge-date-http-400-request.json	update-military-status-with-incorrect-discharge-date-http-400-response.json
403 Forbidden	update military status invalid employee(associateID)	"messageTxt": "You do not have the authorization to access the server. Contact your system administrator"	update-military-status-with-incorrect-employeeOID-http-403-request.json	update-military-status-with-incorrect-employeeOID-http-403-response.json
403 Forbidden	update military classification with invalid employee(associateID)	"messageTxt": "You do not have the authorization to access the server. Contact your system administrator "	update-military-classification-with-incorrect-employeeOID-http-403-request.json	update-military-classification-with-incorrect-employeeOID-http-403-response.json

Chapter 4

Use Case: Synchronizing a Worker Using Notifications

Use Case Description

ADP applications trigger notifications when data is updated, and your application subscribes notifications to sync-up data. For more information about ADP notifications, see ADP Event APIs and Event Notification Guide.

Supported Notifications

The tables in the following sections list all supported notifications. The following describes how the tables are set-up:

Table title describes the navigation path to the ADP Vantage HCM screen.
Field Name – Indicates the name of the field.
Application Scope – Lists the canonical ID to be added to your application.
GitHub Sample Payload – Lists the file name and location where you could find sample payload on ADP's GITHUB repository.

People > Employee Profile > Personal Information

**Notifications are generated when values are updated through API but not when the changes are made through UI.

ADP Vantage HCM Field Name	Application Scope	GitHub Sample Response Payload
Legal Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.legalName.change.eventNotify.subscribe	legal-name-change-event-notification-http-200-response.json
Former Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.formerName.change.eventNotify.subscribe	former-name-change-event-notification-http-200-response.json
Preferred Name	/hr/workerInformationManagement/workerManagement/associateManagement/worker.preferredName.change.eventNotify.subscribe	preferred-name-change-event-notification-http-200-response.json

ADP Vantage HCM Field Name

Application Scope

GitHub Sample Response Payload

Legal Name

/hr/workerInformationManagement/workerManagement/associateManagement/worker.legalName.change.eventNotify.subscribe

legal-name-change-event-notification-http-200-response.json

Former Name

/hr/workerInformationManagement/workerManagement/associateManagement/worker.formerName.change.eventNotify.subscribe

former-name-change-event-notification-http-200-response.json

Preferred Name

/hr/workerInformationManagement/workerManagement/associateManagement/worker.preferredName.change.eventNotify.subscribe

preferred-name-change-event-notification-http-200-response.json

People > Employee Profile > Personal Information > Addresses

**Notifications are generated when values are updated through API but not when the changes are made through UI.

ADP Vantage HCM Field Name	Application Scope	GitHub Sample Response Payload
Home Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.legalAddress.change.eventNotify.subscribe	legal-address-change-event-notification-http-200-response.json
Mailing Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.change.eventNotify.subscribe	personal -address-change-event-notification-http-200-response.json
Mailing Address	/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.add.eventNotify.subscribe	personal-address-add-event-notification-http-200-response.json

ADP Vantage HCM Field Name

Application Scope

GitHub Sample Response Payload

Home Address

/hr/workerInformationManagement/workerManagement/addressManagement/worker.legalAddress.change.eventNotify.subscribe

legal-address-change-event-notification-http-200-response.json

Mailing Address

/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.change.eventNotify.subscribe

personal -address-change-event-notification-http-200-response.json

Mailing Address

/hr/workerInformationManagement/workerManagement/addressManagement/worker.personalAddress.add.eventNotify.subscribe

personal-address-add-event-notification-http-200-response.json

People > Employee Profile > Personal Information > Custom Fields

**Notifications will not get generated from UI when data is newly added to any of person custom field whereas when existing data is modified notifications will get generated.

Though API, notifications will be generated when a value is newly added or when existing value is modified.

ADP Vantage HCM Field Name	Application Scope	GitHub Sample Response Payload
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.number.change.eventNotify.subscribe	person-customfield-number-event-notification-http-200-response.json
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.date.change.eventNotify.subscribe	person-customfield-date-event-notification-http-200-response.json
Custom Field	/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.string.change.eventNotify.subscribe	person-customfield-string-event-notification-http-200-response.json

ADP Vantage HCM Field Name

Application Scope

GitHub Sample Response Payload

Custom Field

/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.number.change.eventNotify.subscribe

person-customfield-number-event-notification-http-200-response.json

Custom Field

/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.date.change.eventNotify.subscribe

person-customfield-date-event-notification-http-200-response.json

Custom Field

/hr/workerInformationManagement/workerManagement/customFieldManagement/worker.person.customField.string.change.eventNotify.subscribe

person-customfield-string-event-notification-http-200-response.json

People > Employee Profile > Personal Information > Contact Information

**Event notification is supported both through API and ADP Vantage UI

ADP Vantage HCM Field Name	Application Scope	GitHub Sample Response Payload
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.add.eventNotify.subscribe	Get personal communication landline add Response
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.change.eventNotify.subscribe	Get personal communication landline change Response
Home Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.landline.remove.eventNotify.subscribe	Get personal communication landline remove Response
Personal Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.add.eventNotify.subscribe	Get personal communication fax add Response
Personal Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.change.eventNotify.subscribe	Get personal communication fax change Response
Personal Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.fax.remove.eventNotify.subscribe	Get personal communication fax remove Response
Personal Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.add.eventNotify.subscribe	Get personal communication pager add Response
Personal Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.change.eventNotify.subscribe	Get personal communication pager change Response
Personal Pager	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.pager.remove.eventNotify.subscribe	Get personal communication pager remove Response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.mobile.add.eventNotify.subscribe	Get personal communication mobile add Response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.mobile.change.eventNotify.subscribe	Get personal communication mobile change Response
Personal Mobile	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.mobile.remove.eventNotify.subscribe	Get personal communication mobile remove Response
Personal E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.add.eventNotify.subscribe	Get personal communication email add Response
Personal E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.change.eventNotify.subscribe	Get personal communication email change Response
Personal E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.personalCommunication.email.remove.eventNotify.subscribe	Get personal communication email remove Response
Work Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.landline.add.eventNotify.subscribe	Get Business Communication landline add Response
Work Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.landline.change.eventNotify.subscribe	Get Business Communication landline change Response
Work Phone	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.landline.remove.eventNotify.subscribe	Get Business Communication landline remove Response
Work Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.fax.add.eventNotify.subscribe	Get Business Communication fax add Response
Work Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.fax.change.eventNotify.subscribe	Get Business Communication fax change Response
Work Fax	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.fax.remove.eventNotify.subscribe	Get Business Communication fax remove Response
Work Cell	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.mobile.add.eventNotify.subscribe	Get Business Communication mobile add Response
Work Cell	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.mobile.change.eventNotify.subscribe	Get Business Communication mobile change Response
Work Cell	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.mobile.remove.eventNotify.subscribe	Get Business Communication mobile remove Response
Work E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.email.add.eventNotify.subscribe	Get Business Communication email add Response
Work E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.email.change.eventNotify.subscribe	Get Business Communication email change Response
Work E-mail	/hr/workerInformationManagement/workerManagement/communicationManagement/worker.businessCommunication.email.remove.eventNotify.subscribe	Get Business Communication email remove Response

People > Employee Profile > Personal Information > Demographics

**Event notification is supported both through API and ADP Vantage UI

ADP Vantage HCM Field Name	Application Scope	GitHub Sample Response Payload
Protected Veteran Status or Military Discharge Date	/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryStatus.change.eventNotify.subscribe	military-status-change-event-notification-http-200-response.json
Military Status	/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryClassification.change.eventNotify.subscribe	military-classification-change-event-notification-http-200-response.json

ADP Vantage HCM Field Name

Application Scope

GitHub Sample Response Payload

Protected Veteran Status or Military Discharge Date

/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryStatus.change.eventNotify.subscribe

military-status-change-event-notification-http-200-response.json

Military Status

/hr/workerInformationManagement/workerManagement/associateManagement/worker.militaryClassification.change.eventNotify.subscribe

military-classification-change-event-notification-http-200-response.json

Summary

What's New in this Guide?

December 2020

Process Overview

Before You Begin

Use Case Description

API Usage

Application Scope

Supported Actors

Request Header Parameters

Sensitive Information Masking

Supported OData Query Options

Filtering capabilities on GET Workers V2 collections

Sequence of Interactions

People > Employee Profile > Personal Information >Name

People > Employee Profile > Personal Information > Addresses

People > Employee Profile >Personal Information >Contact Information

Data Dictionary

People > Employee Profile > Personal Information > Custom fields

People > Employee Profile > Personal Information > Demographics

Description

API Usage

Application Scope

Supported Actors

Request Header Parameters

Sequence of Interactions

Data Dictionary

Fields that Can't be Updated by this API

Responses

Use Case Description

Supported Notifications

People > Employee Profile > Personal Information

People > Employee Profile > Personal Information > Addresses

People > Employee Profile > Personal Information > Custom Fields

People > Employee Profile > Personal Information > Contact Information

People > Employee Profile > Personal Information > Demographics

Worker Management API Guide for ADP Vantage HCM