Workday Studio Benefits Administration API

openapi: 3.2.0
info:
  title: Workday Studio Workday Web Services Benefits Administration…
  description: REST and SOAP web services for integrating with Workday applications, providing programmatic access to business management services across 55 service areas including Human Resources, Payroll, Benefits, and Financial Management. This specification covers the REST-accessible portions of the Workday Web Services (WWS) directory, enabling discovery and invocation of web service operations with WSDL and XML Schema definitions.
  version: v45
  contact:
    name: Workday API Support
    email: api-support@workday.com
    url: https://community.workday.com
  license:
    name: Proprietary
    url: https://www.workday.com/en-us/legal/site-terms.html
  termsOfService: https://www.workday.com/en-us/legal.html
servers:
- url: https://{baseUrl}/ccx/service/{tenant}
  description: Workday Web Services Server
  variables:
    baseUrl:
      default: wd2-impl-services1.workday.com
      description: The Workday data center hostname
    tenant:
      default: tenant
      description: The Workday tenant name
security:
- OAuth2:
  - r:wws
  - w:wws
- WSSecurity: []
tags:
- name: Benefits Administration
  description: Web service operations for benefits enrollment, plan management, coverage administration, and life events processing.
paths:
  /Benefits_Administration/Get_Benefit_Plans:
    post:
      operationId: getBenefitPlans
      summary: Workday Studio Retrieve Benefit Plans
      description: Returns a collection of benefit plan records including health insurance, retirement plans, life insurance, and other benefit offerings configured in the tenant.
      tags:
      - Benefits Administration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBenefitPlansRequest'
      responses:
        '200':
          description: Successful response with benefit plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitPlansResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    RequestCriteria:
      type: object
      description: Common request criteria for filtering web service results
      properties:
        effectiveDate:
          type: string
          format: date
          description: The effective date for the request
        fromDate:
          type: string
          format: date
          description: The start date for date range filtering
        toDate:
          type: string
          format: date
          description: The end date for date range filtering
        pageSize:
          type: integer
          description: The number of records to return per page
          default: 100
          maximum: 999
        page:
          type: integer
          description: The page number to return
          default: 1
    BenefitPlansResponse:
      type: object
      properties:
        total:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              descriptor:
                type: string
              planType:
                type: string
              coverageType:
                type: string
              isActive:
                type: boolean
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A high-level error message
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
              field:
                type: string
              message:
                type: string
    GetBenefitPlansRequest:
      type: object
      properties:
        requestCriteria:
          $ref: '#/components/schemas/RequestCriteria'
        benefitPlanType:
          type: string
  responses:
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{baseUrl}/authorize
          tokenUrl: https://{baseUrl}/oauth2/{tenant}/token
          refreshUrl: https://{baseUrl}/oauth2/{tenant}/token
          scopes:
            r:wws: Read access to web services
            w:wws: Write access to web services
    WSSecurity:
      type: http
      scheme: basic
      description: WS-Security with X.509 certificates or username/password tokens for SOAP API authentication.
externalDocs:
  description: Workday Web Services Directory
  url: https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html