openapi: 3.0.3
info:
  title: Workday Benefits Benefit Enrollments Benefit Plans 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 Plans
  description: Manage benefit plan definitions and configurations
paths:
  /benefitPlans:
    get:
      operationId: listBenefitPlans
      summary: Workday List Benefit Plans
      description: Retrieves a collection of benefit plans including health, dental, vision, life insurance, and retirement plans available to employees.
      tags:
      - Benefit Plans
      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: planType
        in: query
        description: Filter by benefit plan type (HEALTH, DENTAL, VISION, LIFE, RETIREMENT)
        schema:
          type: string
        example: HEALTH
      responses:
        '200':
          description: A list of benefit plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitPlansResponse'
              examples:
                ListBenefitPlans200Example:
                  summary: Default listBenefitPlans 200 response
                  x-microcks-default: true
                  value:
                    total: 12
                    data:
                    - id: BP-HEALTH-001
                      name: Premier Health PPO Plan
                      type: HEALTH
                      carrier: Blue Cross Blue Shield
                      status: ACTIVE
                      effectiveDate: '2026-01-01'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /benefitPlans/{planId}:
    get:
      operationId: getBenefitPlan
      summary: Workday Get Benefit Plan
      description: Retrieves a specific benefit plan by its identifier including coverage options and costs.
      tags:
      - Benefit Plans
      parameters:
      - name: planId
        in: path
        required: true
        description: Benefit plan identifier
        schema:
          type: string
        example: BP-HEALTH-001
      responses:
        '200':
          description: A benefit plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitPlan'
              examples:
                GetBenefitPlan200Example:
                  summary: Default getBenefitPlan 200 response
                  x-microcks-default: true
                  value:
                    id: BP-HEALTH-001
                    name: Premier Health PPO Plan
                    type: HEALTH
                    carrier: Blue Cross Blue Shield
                    status: ACTIVE
                    effectiveDate: '2026-01-01'
                    employeePremium: 150.0
                    employerContribution: 450.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: planId
components:
  schemas:
    BenefitPlansResponse:
      title: Benefit Plans Response
      description: Paginated response containing a list of benefit plans
      type: object
      properties:
        total:
          type: integer
          description: Total number of benefit plans
        data:
          type: array
          items:
            $ref: '#/components/schemas/BenefitPlan'
      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
    BenefitPlan:
      title: Benefit Plan
      description: A Workday benefit plan including health, dental, vision, life, or retirement benefits
      type: object
      properties:
        id:
          type: string
          description: Unique benefit plan identifier
        name:
          type: string
          description: Benefit plan name
        type:
          type: string
          enum:
          - HEALTH
          - DENTAL
          - VISION
          - LIFE
          - RETIREMENT
          - DISABILITY
          - FSA
          - HSA
          description: Type of benefit plan
        carrier:
          type: string
          description: Insurance carrier or plan provider name
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - PENDING
          description: Plan status
        effectiveDate:
          type: string
          format: date
          description: Plan effective date
        endDate:
          type: string
          format: date
          description: Plan end date
        employeePremium:
          type: number
          description: Employee monthly premium cost
        employerContribution:
          type: number
          description: Employer monthly contribution amount
        currency:
          type: string
          description: Currency code
        description:
          type: string
          description: Plan description
      required:
      - id
      - name
      - type
      - status
      - effectiveDate
  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
    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