openapi: 3.0.3
info:
  title: Workday Benefits Benefit Enrollments Dependents 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: Dependents
  description: Manage employee dependents and beneficiaries
paths:
  /dependents:
    get:
      operationId: listDependents
      summary: Workday List Dependents
      description: Retrieves a collection of employee dependents and beneficiaries.
      tags:
      - Dependents
      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 dependents by employee ID
        schema:
          type: string
        example: EMP-12345
      responses:
        '200':
          description: A list of dependents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DependentsResponse'
              examples:
                ListDependents200Example:
                  summary: Default listDependents 200 response
                  x-microcks-default: true
                  value:
                    total: 3
                    data:
                    - id: DEP-001
                      employeeId: EMP-12345
                      firstName: John
                      lastName: Smith
                      relationship: SPOUSE
                      dateOfBirth: '1985-03-15'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDependent
      summary: Workday Create Dependent
      description: Creates a new employee dependent or beneficiary record.
      tags:
      - Dependents
      requestBody:
        description: Dependent details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DependentRequest'
            examples:
              CreateDependentExample:
                summary: Create dependent request
                x-microcks-default: true
                value:
                  employeeId: EMP-12345
                  firstName: Sarah
                  lastName: Smith
                  relationship: CHILD
                  dateOfBirth: '2015-07-22'
      responses:
        '201':
          description: Dependent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dependent'
              examples:
                CreateDependent201Example:
                  summary: Default createDependent 201 response
                  x-microcks-default: true
                  value:
                    id: DEP-003
                    employeeId: EMP-12345
                    firstName: Sarah
                    lastName: Smith
                    relationship: CHILD
                    dateOfBirth: '2015-07-22'
                    status: ACTIVE
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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
    DependentRequest:
      title: Dependent Request
      description: Request to add a new dependent or beneficiary
      type: object
      properties:
        employeeId:
          type: string
          description: Associated employee identifier
        firstName:
          type: string
          description: Dependent first name
        lastName:
          type: string
          description: Dependent last name
        relationship:
          type: string
          enum:
          - SPOUSE
          - DOMESTIC_PARTNER
          - CHILD
          - STEP_CHILD
          - FOSTER_CHILD
          description: Relationship to employee
        dateOfBirth:
          type: string
          format: date
          description: Dependent date of birth
        socialSecurityNumber:
          type: string
          description: Social security number (for US dependents)
      required:
      - employeeId
      - firstName
      - lastName
      - relationship
      - dateOfBirth
    Dependent:
      title: Dependent
      description: An employee dependent or beneficiary
      type: object
      properties:
        id:
          type: string
          description: Unique dependent identifier
        employeeId:
          type: string
          description: Associated employee identifier
        firstName:
          type: string
          description: Dependent first name
        lastName:
          type: string
          description: Dependent last name
        relationship:
          type: string
          enum:
          - SPOUSE
          - DOMESTIC_PARTNER
          - CHILD
          - STEP_CHILD
          - FOSTER_CHILD
          description: Relationship to employee
        dateOfBirth:
          type: string
          format: date
          description: Dependent date of birth
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          description: Dependent status
      required:
      - id
      - employeeId
      - firstName
      - lastName
      - relationship
      - dateOfBirth
    DependentsResponse:
      title: Dependents Response
      description: Paginated response containing a list of dependents
      type: object
      properties:
        total:
          type: integer
          description: Total number of dependents
        data:
          type: array
          items:
            $ref: '#/components/schemas/Dependent'
      required:
      - total
      - data
  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
    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