openapi: 3.1.0
info:
  title: ADP Payroll Organizations Workers API
  description: The ADP Payroll API provides programmatic access to payroll processing, payroll output data, and compensation management. REST APIs support payroll runs, payroll output retrieval (including CSV-formatted bulk data), and headcount and compensation analysis across ADP payroll platforms.
  version: 1.0.0
  contact:
    name: ADP Developer Resources
    url: https://developers.adp.com/
servers:
- url: https://api.adp.com
  description: ADP Production API
security:
- oauth2ClientCredentials: []
tags:
- 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
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmMessage'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmMessage'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmMessage'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmMessage'
  schemas:
    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
    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
    WorkerResponse:
      type: object
      properties:
        workers:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/Worker'
          example: []
    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'
    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: []
    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: []
    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: []
    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
    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: []
    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: []
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.adp.com/auth/oauth/v2/token
          scopes:
            api__payroll-output-v1__read: Read payroll output data