openapi: 3.1.0
info:
  title: ADP Payroll 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: PayrollInstructions
  description: Payroll instructions and overrides

- name: PayrollOutputs
  description: Payroll output and run data
paths:
  /payroll/v1/payroll-outputs:
    get:
      operationId: listPayrollOutputs
      summary: List Payroll Outputs
      description: >-
        Retrieve payroll output summaries for completed payroll runs including
        totals, period dates, and status.
      tags: [PayrollOutputs]
      parameters:
      - name: $filter
        in: query
        description: OData filter expression
        schema:
          type: string
        example: example_value
      - name: $top
        in: query
        schema:
          type: integer
          default: 25
        example: 10
      - name: $skip
        in: query
        schema:
          type: integer
          default: 0
        example: 10
      responses:
        '200':
          description: List of payroll outputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollOutputsResponse'
              examples:
                Listpayrolloutputs200Example:
                  summary: Default listPayrollOutputs 200 response
                  x-microcks-default: true
                  value:
                    payrollOutputs:
                    - payrollOutputID: '500123'
                      payrollScheduleReference: {}
                      payrollStatusCode: {}
                      workerCount: 10
                    meta:
                      totalCount: 10
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payroll/v1/payroll-outputs/{payrollOutputID}:
    get:
      operationId: getPayrollOutput
      summary: Get Payroll Output Details
      description: Retrieve full payroll output details for a specific payroll run by output ID.
      tags: [PayrollOutputs]
      parameters:
      - name: payrollOutputID
        in: path
        required: true
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Payroll output details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollOutputResponse'
              examples:
                Getpayrolloutput200Example:
                  summary: Default getPayrollOutput 200 response
                  x-microcks-default: true
                  value:
                    payrollOutputs:
                    - payrollOutputID: '500123'
                      payrollScheduleReference: {}
                      payrollSummary: {}
        '404':
          $ref: '#/components/responses/NotFound'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payroll/v1/payroll-outputs/{payrollOutputID}/worker-outputs:
    get:
      operationId: getPayrollWorkerOutputs
      summary: Get Worker-level Payroll Outputs
      description: Retrieve individual worker pay statement data for a specific payroll run.
      tags: [PayrollOutputs]
      parameters:
      - name: payrollOutputID
        in: path
        required: true
        schema:
          type: string
        example: '500123'
      - name: $top
        in: query
        schema:
          type: integer
          default: 100
        example: 10
      - name: $skip
        in: query
        schema:
          type: integer
          default: 0
        example: 10
      responses:
        '200':
          description: Worker payroll outputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerOutputsResponse'

              examples:
                Getpayrollworkeroutputs200Example:
                  summary: Default getPayrollWorkerOutputs 200 response
                  x-microcks-default: true
                  value:
                    payrollOutputs:
                    - payrollOutputID: '500123'
                      workerOutputs:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payroll/v1/payroll-instructions:
    get:
      operationId: listPayrollInstructions
      summary: List Payroll Instructions
      description: Retrieve pending payroll instructions and overrides for the next payroll run.
      tags: [PayrollInstructions]
      responses:
        '200':
          description: Payroll instructions
          content:
            application/json:
              schema:
                type: object
                properties:
                  payrollInstructions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayrollInstruction'

              examples:
                Listpayrollinstructions200Example:
                  summary: Default listPayrollInstructions 200 response
                  x-microcks-default: true
                  value:
                    payrollInstructions:
                    - instructionID: '500123'
                      associateOID: '500123'
                      instructionTypeCode: Bonus
                      effectiveDate: '2026-01-15'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPayrollInstruction
      summary: Create Payroll Instruction
      description: Add a pay instruction (bonus, deduction override, garnishment) for an upcoming payroll run.
      tags: [PayrollInstructions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayrollInstructionRequest'
            examples:
              CreatepayrollinstructionRequestExample:
                summary: Default createPayrollInstruction request
                x-microcks-default: true
                value:
                  associateOID: '500123'
                  instructionTypeCode: Bonus
                  amount:
                    amountValue: 42.5
                    currencyCode: example_value
                  effectiveDate: '2026-01-15'
                  description: A sample description.
      responses:
        '201':
          description: Instruction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollInstruction'

              examples:
                Createpayrollinstruction201Example:
                  summary: Default createPayrollInstruction 201 response
                  x-microcks-default: true
                  value:
                    instructionID: '500123'
                    associateOID: '500123'
                    instructionTypeCode: Bonus
                    amount:
                      amountValue: 42.5
                      currencyCode: example_value
                    effectiveDate: '2026-01-15'
      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__payroll-output-v1__read: Read payroll output data

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'

  schemas:
    PayrollOutputsResponse:
      type: object
      properties:
        payrollOutputs:
          type: array
          items:
            $ref: '#/components/schemas/PayrollOutputSummary'
          example: []
        meta:
          type: object
          properties:
            totalCount:
              type: integer

          example: example_value
    PayrollOutputSummary:
      type: object
      properties:
        payrollOutputID:
          type: string
          example: '500123'
        payrollScheduleReference:
          type: object
          properties:
            payFrequencyCode:
              type: object
              properties:
                codeValue:
                  type: string
                  enum: [Weekly, BiWeekly, SemiMonthly, Monthly]
            payPeriodStartDate:
              type: string
              format: date
            payPeriodEndDate:
              type: string
              format: date
            payDate:
              type: string
              format: date
          example: example_value
        payrollStatusCode:
          type: object
          properties:
            codeValue:
              type: string
              enum: [Open, Closed, Processing, Completed, Locked]
          example: example_value
        workerCount:
          type: integer

          example: 10
    PayrollOutputResponse:
      type: object
      properties:
        payrollOutputs:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/PayrollOutput'

          example: []
    PayrollOutput:
      type: object
      properties:
        payrollOutputID:
          type: string
          example: '500123'
        payrollScheduleReference:
          type: object
          properties:
            payFrequencyCode:
              type: object
              properties:
                codeValue:
                  type: string
            payPeriodStartDate:
              type: string
              format: date
            payPeriodEndDate:
              type: string
              format: date
            payDate:
              type: string
              format: date
          example: example_value
        payrollSummary:
          type: object
          properties:
            grossPayAmount:
              $ref: '#/components/schemas/AmountValue'
            netPayAmount:
              $ref: '#/components/schemas/AmountValue'
            totalDeductionsAmount:
              $ref: '#/components/schemas/AmountValue'
            totalTaxesAmount:
              $ref: '#/components/schemas/AmountValue'

          example: example_value
    WorkerOutputsResponse:
      type: object
      properties:
        payrollOutputs:
          type: array
          items:
            type: object
            properties:
              payrollOutputID:
                type: string
              workerOutputs:
                type: array
                items:
                  $ref: '#/components/schemas/WorkerPayOutput'

          example: []
    WorkerPayOutput:
      type: object
      properties:
        associateOID:
          type: string
          example: '500123'
        workerID:
          type: object
          properties:
            idValue:
              type: string
          example: '500123'
        payStatementID:
          type: string
          example: '500123'
        payDate:
          type: string
          format: date
          example: '2026-01-15'
        grossPayAmount:
          $ref: '#/components/schemas/AmountValue'
        netPayAmount:
          $ref: '#/components/schemas/AmountValue'
        regularEarnings:
          type: array
          items:
            $ref: '#/components/schemas/EarningItem'
          example: []
        overtimeEarnings:
          type: array
          items:
            $ref: '#/components/schemas/EarningItem'
          example: []
        otherEarnings:
          type: array
          items:
            $ref: '#/components/schemas/EarningItem'
          example: []
        deductions:
          type: array
          items:
            $ref: '#/components/schemas/DeductionItem'
          example: []
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/TaxItem'

          example: []
    EarningItem:
      type: object
      properties:
        typeCode:
          type: object
          properties:
            codeValue:
              type: string
          example: example_value
        nameCode:
          type: object
          properties:
            codeValue:
              type: string
            shortName:
              type: string
          example: example_value
        amount:
          $ref: '#/components/schemas/AmountValue'
        hoursQuantity:
          type: number
          example: 42.5
        rateAmount:
          $ref: '#/components/schemas/AmountValue'

    DeductionItem:
      type: object
      properties:
        typeCode:
          type: object
          properties:
            codeValue:
              type: string
          example: example_value
        nameCode:
          type: object
          properties:
            codeValue:
              type: string
            shortName:
              type: string
          example: example_value
        amount:
          $ref: '#/components/schemas/AmountValue'

    TaxItem:
      type: object
      properties:
        typeCode:
          type: object
          properties:
            codeValue:
              type: string
          example: example_value
        nameCode:
          type: object
          properties:
            codeValue:
              type: string
          example: example_value
        amount:
          $ref: '#/components/schemas/AmountValue'
        jurisdictionCode:
          type: object
          properties:
            codeValue:
              type: string

          example: example_value
    AmountValue:
      type: object
      properties:
        amountValue:
          type: number
          format: double
          example: 42.5
        currencyCode:
          type: string
          default: USD

          example: example_value
    PayrollInstruction:
      type: object
      properties:
        instructionID:
          type: string
          example: '500123'
        associateOID:
          type: string
          example: '500123'
        instructionTypeCode:
          type: string
          enum: [Bonus, Deduction, Garnishment, Override]
          example: Bonus
        amount:
          $ref: '#/components/schemas/AmountValue'
        effectiveDate:
          type: string
          format: date

          example: '2026-01-15'
    PayrollInstructionRequest:
      type: object
      required: [associateOID, instructionTypeCode, amount]
      properties:
        associateOID:
          type: string
          example: '500123'
        instructionTypeCode:
          type: string
          enum: [Bonus, Deduction, Garnishment, Override]
          example: Bonus
        amount:
          $ref: '#/components/schemas/AmountValue'
        effectiveDate:
          type: string
          format: date
          example: '2026-01-15'
        description:
          type: string

          example: A sample description.
    ErrorMessage:
      type: object
      properties:
        confirmMessage:
          type: object
          properties:
            processMessages:
              type: array
              items:
                type: object
                properties:
                  messageTypeCode:
                    type: object
                    properties:
                      codeValue:
                        type: string
                  userMessage:
                    type: object
                    properties:
                      messageTxt:
                        type: string
          example: example_value