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: []