Workday Business Processes Process Instances API

openapi: 3.0.3
info:
  title: Workday Business Process Approvals Process Instances API
  description: The Workday Business Process API provides RESTful access to business process management capabilities including initiating workflows, managing approvals, tracking process instances, retrieving process definitions, and handling inbox items. The API enables organizations to programmatically trigger Workday business processes, monitor their status, and integrate workflow automation with external systems.
  version: v41.1
  contact:
    name: Workday Developer Support
    url: https://community.workday.com/
  x-generated-from: documentation
servers:
- url: https://{tenant}.workday.com/api/businessProcess/v1
  description: Workday tenant REST API endpoint
  variables:
    tenant:
      default: wd2-impl-services1
      description: Your Workday tenant hostname
security:
- oauth2: []
tags:
- name: Process Instances
  description: Manage running business process instances
paths:
  /processInstances:
    get:
      operationId: listProcessInstances
      summary: Workday List Process Instances
      description: Retrieves a collection of business process instances with status and progress information.
      tags:
      - Process Instances
      parameters:
      - name: limit
        in: query
        description: Maximum number of records to return
        schema:
          type: integer
          default: 100
        example: 100
      - name: offset
        in: query
        description: Number of records to skip
        schema:
          type: integer
          default: 0
        example: 0
      - name: status
        in: query
        description: Filter by process status
        schema:
          type: string
        example: IN_PROGRESS
      - name: processType
        in: query
        description: Filter by business process type
        schema:
          type: string
        example: HireEmployee
      - name: initiatorId
        in: query
        description: Filter by process initiator ID
        schema:
          type: string
        example: EMP-12345
      responses:
        '200':
          description: A list of process instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessInstancesResponse'
              examples:
                ListProcessInstances200Example:
                  summary: Default listProcessInstances 200 response
                  x-microcks-default: true
                  value:
                    total: 28
                    data:
                    - id: PI-2026-001
                      definitionId: BPD-HIRE-001
                      processType: HireEmployee
                      status: IN_PROGRESS
                      initiatorId: EMP-00100
                      startDate: '2026-04-15T09:00:00Z'
                      currentStep: Background Check
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: initiateProcess
      summary: Workday Initiate Process
      description: Initiates a new business process instance.
      tags:
      - Process Instances
      requestBody:
        description: Business process initiation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateProcessRequest'
            examples:
              InitiateProcessExample:
                summary: Initiate a hire employee process
                x-microcks-default: true
                value:
                  definitionId: BPD-HIRE-001
                  transactionId: TXN-EMP-NEW-001
                  initiatorId: EMP-00100
                  processData:
                    employeeId: EMP-NEW-001
                    positionId: POS-TECH-042
                    startDate: '2026-05-15'
      responses:
        '201':
          description: Process instance created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessInstance'
              examples:
                InitiateProcess201Example:
                  summary: Default initiateProcess 201 response
                  x-microcks-default: true
                  value:
                    id: PI-2026-050
                    definitionId: BPD-HIRE-001
                    processType: HireEmployee
                    status: INITIATED
                    initiatorId: EMP-00100
                    startDate: '2026-05-01T10:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /processInstances/{instanceId}:
    get:
      operationId: getProcessInstance
      summary: Workday Get Process Instance
      description: Retrieves a specific business process instance by its identifier.
      tags:
      - Process Instances
      parameters:
      - name: instanceId
        in: path
        required: true
        description: Process instance identifier
        schema:
          type: string
        example: PI-2026-001
      responses:
        '200':
          description: A process instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessInstance'
              examples:
                GetProcessInstance200Example:
                  summary: Default getProcessInstance 200 response
                  x-microcks-default: true
                  value:
                    id: PI-2026-001
                    definitionId: BPD-HIRE-001
                    processType: HireEmployee
                    status: IN_PROGRESS
                    initiatorId: EMP-00100
                    startDate: '2026-04-15T09:00:00Z'
                    currentStep: Background Check
                    completionPercent: 65
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: URI_PARTS
        dispatcherRules: instanceId
  /processInstances/{instanceId}/cancel:
    post:
      operationId: cancelProcessInstance
      summary: Workday Cancel Process Instance
      description: Cancels a running business process instance.
      tags:
      - Process Instances
      parameters:
      - name: instanceId
        in: path
        required: true
        description: Process instance identifier
        schema:
          type: string
        example: PI-2026-001
      requestBody:
        description: Cancellation details
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Reason for cancellation
              required:
              - reason
            examples:
              CancelProcessExample:
                summary: Cancel process request
                x-microcks-default: true
                value:
                  reason: Position filled by internal candidate
      responses:
        '200':
          description: Process cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessInstance'
              examples:
                CancelProcessInstance200Example:
                  summary: Default cancelProcessInstance 200 response
                  x-microcks-default: true
                  value:
                    id: PI-2026-001
                    status: CANCELLED
                    cancelReason: Position filled by internal candidate
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: URI_PARTS
        dispatcherRules: instanceId
  /processInstances/{instanceId}/steps:
    get:
      operationId: listProcessSteps
      summary: Workday List Process Steps
      description: Retrieves the steps for a specific business process instance including completion status.
      tags:
      - Process Instances
      parameters:
      - name: instanceId
        in: path
        required: true
        description: Process instance identifier
        schema:
          type: string
        example: PI-2026-001
      responses:
        '200':
          description: A list of process steps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessStepsResponse'
              examples:
                ListProcessSteps200Example:
                  summary: Default listProcessSteps 200 response
                  x-microcks-default: true
                  value:
                    total: 8
                    data:
                    - stepId: STEP-001
                      stepName: Manager Approval
                      stepType: APPROVAL
                      status: COMPLETE
                      assignedTo: EMP-00100
                      completedDate: '2026-04-16T10:00:00Z'
                    - stepId: STEP-002
                      stepName: Background Check
                      stepType: ACTION
                      status: IN_PROGRESS
                      assignedTo: HR-TEAM
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: URI_PARTS
        dispatcherRules: instanceId
components:
  schemas:
    InitiateProcessRequest:
      title: Initiate Process Request
      description: Request to initiate a new business process instance
      type: object
      properties:
        definitionId:
          type: string
          description: Business process definition to initiate
        transactionId:
          type: string
          description: Associated transaction or subject worker ID
        initiatorId:
          type: string
          description: ID of the user initiating the process
        processData:
          type: object
          description: Additional process-specific data fields
          additionalProperties: true
      required:
      - definitionId
      - initiatorId
    ProcessInstance:
      title: Process Instance
      description: A running or completed business process instance
      type: object
      properties:
        id:
          type: string
          description: Unique process instance identifier
        definitionId:
          type: string
          description: Business process definition identifier
        processType:
          type: string
          description: Business process type
        status:
          type: string
          enum:
          - INITIATED
          - IN_PROGRESS
          - PENDING_ACTION
          - COMPLETE
          - CANCELLED
          - ERROR
          description: Current process status
        initiatorId:
          type: string
          description: ID of the user who initiated the process
        transactionId:
          type: string
          description: Associated transaction or worker ID
        startDate:
          type: string
          format: date-time
          description: Process start timestamp
        endDate:
          type: string
          format: date-time
          description: Process completion timestamp
        currentStep:
          type: string
          description: Name of the current active step
        completionPercent:
          type: integer
          description: Percentage of steps completed
        cancelReason:
          type: string
          description: Reason for cancellation (if cancelled)
      required:
      - id
      - definitionId
      - processType
      - status
      - initiatorId
    ErrorResponse:
      title: Error Response
      description: Standard error response
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: string
          description: Additional error details
      required:
      - error
      - message
    ProcessStepsResponse:
      title: Process Steps Response
      description: Paginated response containing a list of process steps
      type: object
      properties:
        total:
          type: integer
          description: Total number of steps
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProcessStep'
      required:
      - total
      - data
    ProcessStep:
      title: Process Step
      description: A step within a running business process instance
      type: object
      properties:
        stepId:
          type: string
          description: Step identifier
        stepName:
          type: string
          description: Step display name
        stepType:
          type: string
          enum:
          - APPROVAL
          - ACTION
          - NOTIFICATION
          - CONDITION
          - INTEGRATION
          description: Type of process step
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETE
          - SKIPPED
          - ERROR
          description: Step status
        assignedTo:
          type: string
          description: User or group assigned to this step
        dueDate:
          type: string
          format: date
          description: Step due date
        completedDate:
          type: string
          format: date-time
          description: Step completion timestamp
        completedBy:
          type: string
          description: User who completed the step
      required:
      - stepId
      - stepName
      - stepType
      - status
    ProcessInstancesResponse:
      title: Process Instances Response
      description: Paginated response containing a list of process instances
      type: object
      properties:
        total:
          type: integer
          description: Total number of instances
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProcessInstance'
      required:
      - total
      - data
  responses:
    Forbidden:
      description: Insufficient permissions to access the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: FORBIDDEN
            message: You do not have permission to perform this action
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: UNAUTHORIZED
            message: Valid authentication credentials are required
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: NOT_FOUND
            message: The requested resource does not exist
    BadRequest:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: BAD_REQUEST
            message: Invalid request body
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.workday.com/ccx/oauth2/{tenant}/token
          scopes:
            businessProcess: Access to Workday Business Process API