The ADP Workers API enables access to employee and worker data including personal information, job assignments, pay grades, and employment status. REST APIs support worker lifecycle management for HCM integrations across ADP Workforce Now, Vantage HCM, and Enterprise HR platforms.
openapi: 3.1.0
info:
title: ADP Workers API
description: >-
The ADP Workers API enables access to employee and worker data including personal
information, job assignments, pay grades, compensation, and employment status.
REST APIs support worker lifecycle management for HCM integrations across ADP
Workforce Now, Vantage HCM, and Enterprise HR platforms.
version: 2.0.0
contact:
name: ADP Developer Resources
url: https://developers.adp.com/
license:
name: ADP API License
url: https://developers.adp.com/
servers:
- url: https://api.adp.com
description: ADP Production API
security:
- oauth2ClientCredentials: []
tags:
- name: Organizations
description: Organizational unit management
- name: Workers
description: Worker (employee) data access
paths:
/hr/v2/workers:
get:
operationId: listWorkers
summary: List Workers
description: >-
Retrieve a collection of workers (employees and contractors) from the
organization. Supports filtering by worker type, status, and OData query parameters.
tags: [Workers]
parameters:
- name: $filter
in: query
description: OData filter expression (e.g., workers/workAssignments/assignmentStatus/statusCode/codeValue eq 'Active')
schema:
type: string
example: example_value
- name: $select
in: query
description: OData select fields to return
schema:
type: string
example: example_value
- name: $top
in: query
description: Number of records to return
schema:
type: integer
default: 25
maximum: 100
example: 10
- name: $skip
in: query
description: Number of records to skip for pagination
schema:
type: integer
default: 0
example: 10
responses:
'200':
description: Collection of workers
content:
application/json:
schema:
$ref: '#/components/schemas/WorkersResponse'
examples:
Listworkers200Example:
summary: Default listWorkers 200 response
x-microcks-default: true
value:
workers:
- associateOID: '500123'
workerID: {}
workerDates: {}
workAssignments: {}
customFieldGroup: example_value
meta:
totalCount: 10
startIndex: 10
itemsPerPage: 10
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/hr/v2/workers/{aoid}:
get:
operationId: getWorker
summary: Get Worker by Aoid
description: Retrieve a single worker record by the ADP worker AOID (Associate OID).
tags: [Workers]
parameters:
- name: aoid
in: path
required: true
description: ADP Associate Object Identifier (AOID)
schema:
type: string
example: '500123'
responses:
'200':
description: Worker details
content:
application/json:
schema:
$ref: '#/components/schemas/WorkerResponse'
examples:
Getworker200Example:
summary: Default getWorker 200 response
x-microcks-default: true
value:
workers:
- associateOID: '500123'
workerID: {}
workerDates: {}
workAssignments: {}
customFieldGroup: example_value
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/hr/v2/workers/{aoid}/work-assignments:
get:
operationId: getWorkerWorkAssignments
summary: Get Worker Work Assignments
description: Retrieve all work assignments (positions) associated with a worker.
tags: [Workers]
parameters:
- name: aoid
in: path
required: true
schema:
type: string
example: '500123'
responses:
'200':
description: Work assignments for the worker
content:
application/json:
schema:
type: object
properties:
workers:
type: array
items:
$ref: '#/components/schemas/WorkAssignment'
examples:
Getworkerworkassignments200Example:
summary: Default getWorkerWorkAssignments 200 response
x-microcks-default: true
value:
workers:
- itemID: '500123'
primaryIndicator: true
hireDate: '2026-01-15'
assignmentStatus:
statusCode: {}
positionID: '500123'
jobCode:
codeValue: example_value
shortName: example_value
jobTitle: example_value
standardHours:
hoursQuantity: 42.5
unitCode: {}
annualBaseRemuneration:
annualRateAmount: {}
homeOrganizationalUnits:
- {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/events/hr/v1/worker.hire:
post:
operationId: hireWorker
summary: Hire a New Worker
description: >-
Submit a worker hire event to onboard a new employee or contractor into the
ADP HCM system. This creates a new worker record with initial work assignment.
tags: [Workers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkerHireEvent'
examples:
HireworkerRequestExample:
summary: Default hireWorker request
x-microcks-default: true
value:
events:
- eventNameCode:
codeValue: worker.hire
data:
transform: {}
responses:
'201':
description: Worker hire event accepted
content:
application/json:
schema:
$ref: '#/components/schemas/EventResponse'
examples:
Hireworker201Example:
summary: Default hireWorker 201 response
x-microcks-default: true
value:
events:
- eventID: '500123'
eventNameCode:
codeValue: example_value
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/events/hr/v1/worker.terminate:
post:
operationId: terminateWorker
summary: Terminate a Worker
description: >-
Submit a worker termination event to end employment for an existing worker.
tags: [Workers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkerTerminateEvent'
examples:
TerminateworkerRequestExample:
summary: Default terminateWorker request
x-microcks-default: true
value:
events:
- eventNameCode:
codeValue: worker.terminate
data:
transform: {}
responses:
'201':
description: Termination event accepted
content:
application/json:
schema:
$ref: '#/components/schemas/EventResponse'
examples:
Terminateworker201Example:
summary: Default terminateWorker 201 response
x-microcks-default: true
value:
events:
- eventID: '500123'
eventNameCode:
codeValue: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/core/v1/organization-departments:
get:
operationId: listDepartments
summary: List Organization Departments
description: Retrieve all departments/organizational units in the company structure.
tags: [Organizations]
responses:
'200':
description: List of departments
content:
application/json:
schema:
type: object
properties:
organizationDepartments:
type: array
items:
$ref: '#/components/schemas/Department'
examples:
Listdepartments200Example:
summary: Default listDepartments 200 response
x-microcks-default: true
value:
organizationDepartments:
- departmentCode: example_value
departmentName: example_value
parentDepartmentCode: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
oauth2ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://accounts.adp.com/auth/oauth/v2/token
scopes:
api__workers-v2__read: Read worker data
api__workers-v2__write: Write worker data
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmMessage'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmMessage'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmMessage'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmMessage'
schemas:
WorkersResponse:
type: object
properties:
workers:
type: array
items:
$ref: '#/components/schemas/Worker'
example: []
meta:
type: object
properties:
totalCount:
type: integer
startIndex:
type: integer
itemsPerPage:
type: integer
example: example_value
WorkerResponse:
type: object
properties:
workers:
type: array
maxItems: 1
items:
$ref: '#/components/schemas/Worker'
example: []
Worker:
type: object
description: ADP Worker (employee or contractor)
properties:
associateOID:
type: string
description: ADP Associate Object Identifier - unique worker identifier
example: '500123'
workerID:
type: object
properties:
idValue:
type: string
schemeCode:
type: object
properties:
codeValue:
type: string
example: '500123'
person:
$ref: '#/components/schemas/Person'
workerDates:
type: object
properties:
originalHireDate:
type: string
format: date
terminationDate:
type: string
format: date
rehireDate:
type: string
format: date
example: example_value
workAssignments:
type: array
items:
$ref: '#/components/schemas/WorkAssignment'
example: []
customFieldGroup:
type: object
additionalProperties: true
example: example_value
Person:
type: object
properties:
legalName:
type: object
properties:
givenName:
type: string
familyName1:
type: string
preferredSalutations:
type: array
items:
type: object
example: example_value
birthDate:
type: string
format: date
example: '2026-01-15'
genderCode:
type: object
properties:
codeValue:
type: string
enum: [M, F, N]
example: example_value
maritalStatusCode:
type: object
properties:
codeValue:
type: string
example: example_value
communication:
type: object
properties:
emails:
type: array
items:
type: object
properties:
emailUri:
type: string
format: email
phones:
type: array
items:
type: object
properties:
countryDialing:
type: string
areaDialing:
type: string
dialNumber:
type: string
example: example_value
legalAddress:
$ref: '#/components/schemas/Address'
WorkAssignment:
type: object
properties:
itemID:
type: string
example: '500123'
primaryIndicator:
type: boolean
example: true
hireDate:
type: string
format: date
example: '2026-01-15'
assignmentStatus:
type: object
properties:
statusCode:
type: object
properties:
codeValue:
type: string
enum: [Active, Inactive, Terminated]
example: example_value
positionID:
type: string
example: '500123'
jobCode:
type: object
properties:
codeValue:
type: string
shortName:
type: string
example: example_value
jobTitle:
type: string
example: example_value
standardHours:
type: object
properties:
hoursQuantity:
type: number
unitCode:
type: object
properties:
codeValue:
type: string
enum: [HRS, WK, MO]
example: example_value
annualBaseRemuneration:
type: object
properties:
annualRateAmount:
type: object
properties:
amountValue:
type: number
currencyCode:
type: string
example: example_value
homeOrganizationalUnits:
type: array
items:
type: object
properties:
nameCode:
type: object
properties:
codeValue:
type: string
unitCode:
type: object
properties:
codeValue:
type: string
example: []
Department:
type: object
properties:
departmentCode:
type: string
example: example_value
departmentName:
type: string
example: example_value
parentDepartmentCode:
type: string
example: example_value
Address:
type: object
properties:
lineOne:
type: string
example: example_value
lineTwo:
type: string
example: example_value
cityName:
type: string
example: example_value
countrySubdivisionLevel1:
type: object
properties:
codeValue:
type: string
example: example_value
postalCode:
type: string
example: example_value
countryCode:
type: string
example: example_value
WorkerHireEvent:
type: object
required: [events]
properties:
events:
type: array
items:
type: object
required: [eventNameCode, data]
properties:
eventNameCode:
type: object
properties:
codeValue:
type: string
enum: [worker.hire]
data:
type: object
properties:
transform:
type: object
properties:
worker:
$ref: '#/components/schemas/Worker'
example: []
WorkerTerminateEvent:
type: object
required: [events]
properties:
events:
type: array
items:
type: object
properties:
eventNameCode:
type: object
properties:
codeValue:
type: string
enum: [worker.terminate]
data:
type: object
properties:
transform:
type: object
properties:
workerDates:
type: object
properties:
terminationDate:
type: string
format: date
terminationReason:
type: object
properties:
codeValue:
type: string
example: []
EventResponse:
type: object
properties:
events:
type: array
items:
type: object
properties:
eventID:
type: string
eventNameCode:
type: object
properties:
codeValue:
type: string
confirmMessage:
$ref: '#/components/schemas/ConfirmMessage'
example: []
ConfirmMessage:
type: object
properties:
confirmMessageID:
type: object
properties:
idValue:
type: string
example: '500123'
processMessages:
type: array
items:
type: object
properties:
processMessageID:
type: object
properties:
idValue:
type: string
messageTypeCode:
type: object
properties:
codeValue:
type: string
userMessage:
type: object
properties:
messageTxt:
type: string
example: []