openapi: 3.0.3
info:
  title: Workday Benefits Benefit Enrollments API
  description: The Workday Benefits API provides RESTful access to employee benefits management capabilities including health insurance enrollments, retirement plans, life insurance, dependent management, time off policies, and benefits administration. The API enables organizations to programmatically manage employee benefit programs, process enrollments, and integrate benefits data with other systems.
  version: v40.2
  contact:
    name: Workday Developer Support
    url: https://community.workday.com/
  x-generated-from: documentation
servers:
- url: https://{tenant}.workday.com/api/benefits/v1
  description: Workday tenant REST API endpoint
  variables:
    tenant:
      default: wd2-impl-services1
      description: Your Workday tenant hostname
security:
- oauth2: []
tags:
- name: Benefit Enrollments
  description: Manage employee benefit enrollments and elections
paths:
  /benefitEnrollments:
    get:
      operationId: listBenefitEnrollments
      summary: Workday List Benefit Enrollments
      description: Retrieves a collection of employee benefit enrollments and elections.
      tags:
      - Benefit Enrollments
      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: employeeId
        in: query
        description: Filter enrollments by employee ID
        schema:
          type: string
        example: EMP-12345
      - name: planId
        in: query
        description: Filter enrollments by benefit plan ID
        schema:
          type: string
        example: BP-HEALTH-001
      responses:
        '200':
          description: A list of benefit enrollments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitEnrollmentsResponse'
              examples:
                ListBenefitEnrollments200Example:
                  summary: Default listBenefitEnrollments 200 response
                  x-microcks-default: true
                  value:
                    total: 250
                    data:
                    - id: ENR-001
                      employeeId: EMP-12345
                      planId: BP-HEALTH-001
                      coverageLevel: EMPLOYEE_PLUS_FAMILY
                      effectiveDate: '2026-01-01'
                      status: ACTIVE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createBenefitEnrollment
      summary: Workday Create Benefit Enrollment
      description: Creates a new employee benefit enrollment election.
      tags:
      - Benefit Enrollments
      requestBody:
        description: Benefit enrollment details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenefitEnrollmentRequest'
            examples:
              CreateBenefitEnrollmentExample:
                summary: Create benefit enrollment request
                x-microcks-default: true
                value:
                  employeeId: EMP-12345
                  planId: BP-HEALTH-001
                  coverageLevel: EMPLOYEE_PLUS_FAMILY
                  effectiveDate: '2026-01-01'
                  dependentIds:
                  - DEP-001
                  - DEP-002
      responses:
        '201':
          description: Benefit enrollment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitEnrollment'
              examples:
                CreateBenefitEnrollment201Example:
                  summary: Default createBenefitEnrollment 201 response
                  x-microcks-default: true
                  value:
                    id: ENR-002
                    employeeId: EMP-12345
                    planId: BP-HEALTH-001
                    coverageLevel: EMPLOYEE_PLUS_FAMILY
                    effectiveDate: '2026-01-01'
                    status: PENDING
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /benefitEnrollments/{enrollmentId}:
    get:
      operationId: getBenefitEnrollment
      summary: Workday Get Benefit Enrollment
      description: Retrieves a specific benefit enrollment by ID.
      tags:
      - Benefit Enrollments
      parameters:
      - name: enrollmentId
        in: path
        required: true
        description: Benefit enrollment identifier
        schema:
          type: string
        example: ENR-001
      responses:
        '200':
          description: A benefit enrollment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitEnrollment'
              examples:
                GetBenefitEnrollment200Example:
                  summary: Default getBenefitEnrollment 200 response
                  x-microcks-default: true
                  value:
                    id: ENR-001
                    employeeId: EMP-12345
                    planId: BP-HEALTH-001
                    coverageLevel: EMPLOYEE_PLUS_FAMILY
                    effectiveDate: '2026-01-01'
                    status: ACTIVE
                    employeePremium: 150.0
                    currency: USD
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: URI_PARTS
        dispatcherRules: enrollmentId
components:
  schemas:
    BenefitEnrollmentRequest:
      title: Benefit Enrollment Request
      description: Request to create or update a benefit enrollment
      type: object
      properties:
        employeeId:
          type: string
          description: Employee identifier
        planId:
          type: string
          description: Benefit plan identifier
        coverageLevel:
          type: string
          enum:
          - EMPLOYEE_ONLY
          - EMPLOYEE_PLUS_SPOUSE
          - EMPLOYEE_PLUS_CHILDREN
          - EMPLOYEE_PLUS_FAMILY
          description: Desired coverage level
        effectiveDate:
          type: string
          format: date
          description: Enrollment effective date
        dependentIds:
          type: array
          items:
            type: string
          description: List of dependent IDs to enroll
        waiveReason:
          type: string
          description: Reason for waiving coverage (if applicable)
      required:
      - employeeId
      - planId
      - coverageLevel
      - effectiveDate
    BenefitEnrollment:
      title: Benefit Enrollment
      description: An employee benefit enrollment election
      type: object
      properties:
        id:
          type: string
          description: Unique enrollment identifier
        employeeId:
          type: string
          description: Employee identifier
        planId:
          type: string
          description: Benefit plan identifier
        coverageLevel:
          type: string
          enum:
          - EMPLOYEE_ONLY
          - EMPLOYEE_PLUS_SPOUSE
          - EMPLOYEE_PLUS_CHILDREN
          - EMPLOYEE_PLUS_FAMILY
          description: Coverage level selected
        effectiveDate:
          type: string
          format: date
          description: Enrollment effective date
        endDate:
          type: string
          format: date
          description: Enrollment end date
        status:
          type: string
          enum:
          - ACTIVE
          - PENDING
          - CANCELLED
          - WAIVED
          description: Enrollment status
        employeePremium:
          type: number
          description: Employee monthly premium amount
        currency:
          type: string
          description: Currency code
        dependentIds:
          type: array
          items:
            type: string
          description: List of enrolled dependent IDs
      required:
      - id
      - employeeId
      - planId
      - coverageLevel
      - effectiveDate
      - status
    BenefitEnrollmentsResponse:
      title: Benefit Enrollments Response
      description: Paginated response containing a list of benefit enrollments
      type: object
      properties:
        total:
          type: integer
          description: Total number of enrollments
        data:
          type: array
          items:
            $ref: '#/components/schemas/BenefitEnrollment'
      required:
      - total
      - data
    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
  responses:
    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
    BadRequest:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: BAD_REQUEST
            message: Invalid request body
    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
    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
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.workday.com/ccx/oauth2/{tenant}/token
          scopes:
            benefits: Access to Workday Benefits API