Guides
Signup For Free

Creating comapny wide deduction using workday APIs

Suggest Edits

Workday has Benefits modules which are kind of deductions as per Knit's Data model. Workday has following types of Benefit (Deductions) -

  1. Retirement Savings Plan
  2. Health Savings Account Plan
  3. Health Care Coverage Plan
  4. Spending Account Plan
  5. Insurance Coverage Plan
  6. Additional Benefits Plan

Depeneding upon the benefit plan you need extra parameters apart from name, frequency, description etc as part of metadata key in the Create a company wide deduction.

Common Deduction Input

  1. Name : It can be anything short and concise.
  2. Description: It should be a one liner about the deduction .
  3. Frequency: It can be one the described frequency enum below.
  4. type: It must be one of given enum for type.
  5. metadata: It will have all the remaining properties depending on the plan type.
 HEALTH_COVERAGE_CARE_PLAN,
 HEALTH_SAVING_ACCOUNT_PLAN,
 SPENDING_ACCOUNT_PLAN,
INSURANCE_COVERAGE_PLAN,
 RETIREMENT_SAVING_PLAN,
 ADDITIONAL_BENEFITS_PLAN

ANNUAL
WEEKLY
QUARTERLY
SEMI_MONTHLY
MONTHLY
HOURLY
BI_WEEKLY
DAILY

📘

Essential Guide: Preparing Your Request Body

Integration IDs will be needed for different kind of properties like - Benefit Type, Benefit Rate Type, Currency etc. See this guide - How to Fetch Integration IDs. Input parameter which have name - Reference or ID will be of Integration ID type input.

Now we will look different types of request parameters needed to create benefit Plan (deduction) in workday. Here we tried to keep the property name same as in Put_Benefit_Request Workday so that to minimize error and ambiguity. Few properties are mandatory as per API without it Workday will throw error. Others are essential to have like - Contribution details , description , name etc.

Retirement Savings Plan

Retirement plan request will have following parameters

  1. Benefit Coverage Type((Benefit_Coverage_Type_ID): It is the sub type ID for retirement plan.
  2. Benefit Groups(Benefit_Group_Reference): List of benefit group IDs.
  3. Benefit Provider (Benefit_Provider_ID): It is the provider offering benefit.
  4. Currency(Currency_ID): Currency Intergation IDs like - USD, INR etc.
  5. Effective Date (Effective_Date): You can pass effective date for this plan. Format must be (yyyy-mm-dd'Z').
  6. Auto Enroll (Auto_Enroll): Enrollment of users should be auto.
  7. Eligibility Criteria (Worker_Eligibility_Rule_Reference): Integration IDs for worker eligibility.
  8. Earning and deductions (Pay_Component_Reference): Pass the type and integration IDs for possible paycomponent which will be associated with the benefit plan.
  9. External URL (External_URL_Reference): The link for benefit provider details saved in workday. can be fetched from integration IDs page.
  10. Employee Contribution (Employee_Contribution_Data)
  11. Employer Contribution(Employer_Contribution_Data) ->Amount OR Percentage

See the below sample json for creating retirement plan.

{
    "name": "Retirement Plan ACPC",
    "type": "RETIREMENT_SAVING_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a retirement plan for asia pacafic.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-1",
        "Benefit_Coverage_Type_ID": "RETIREMENT_SAVINGS_COVERAGE_TYPE-4-4",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-6-14"
        ],
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "GRP-1223",
        "Do_Not_Use": true,
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Auto_Enroll": false,
        "Pay_Component_Reference": [
            {
                "type": "Earning_Code",
                "code": "SPOTBON"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm",
        "Employee_Contribution_Data": {
            "Percentage_Minimum": "10",
            "Percentage_Maximum": "20",
            "Amount_Minimum": "1000",
            "Amount_Maximum": "3000"
        },
        "Employer_Contribution_Data": {
            "Percentage": "10"
          "Amount": "1000" //Choice
        }
    }
}

Additional Benefits Plan

Apart from common field described in above plans

  1. Coverage Cost Data(Coverage_Cost_Data) : It contains Target and contribution details for employee and employer.
  2. Coverage_Target_Reference - ID for different coverage target like - Employee, Spouse etc.
{
    "name": "Additional Plan Knit",
    "type": "ADDITIONAL_BENEFITS_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a additonal plan for asia pacafic.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-63",
        "Benefit_Coverage_Type_ID": "ADDITIONAL_BENEFITS_COVERAGE_TYPE-6-19",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-6-14",
            "BENEFIT_GROUP-4-6"
        ],
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "ADD-1223",
        "Do_Not_Use": true,
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Auto_Enroll": false,
        "Pay_Component_Reference": [
            {
                "type": "Earning_Code",
                "code": "INCN-PI"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm",
        "Employee_Cost_is_Pre-tax": false,
        "Use_Individual_Rates": false,
        "Reset_Individual_Rates": false,
        "Whole_Number_Percentages_Only": false,
        "Coverage_Cost_Data": {
            "Coverage_Target_Reference": "ADDITIONAL_BENEFITS_COVERAGE_TARGET-4-3",
            "Employee_Amount_Minimum": "10",
            "Employee_Amount_Maximum": "20",
            "Employee_Percent_Minimum": "10",
            "Employee_Percent_Maximum": "13",
            "Employee_Cost_Pre-Tax": "100",
            "Employee_Cost_Post-Tax": "90",
            "Employer_Cost_Non-Taxable": "10",
            "Employer_Cost_Taxable": "10"
        }
    }
}

Health Savings Plan

The parameters apart from the above described ones are

  1. Health Savings Account Plan Rate(Health_Savings_Account_Plan_Rate_ID): Integration ID for plan rate.
  2. Limit Data: Details for coverage target and contibution.

If Rate ID is given then Limit Data is not required

{
    "name": "Health Plan Knit",
    "type": "HEALTH_SAVING_ACCOUNT_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a health savings plan for India.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-63",
        "Benefit_Coverage_Type_ID": "HEALTH_SAVINGS_ACCOUNT_COVERAGE_TYPE-4-1",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-4-6"
        ],
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "ADD-1223",
        "Do_Not_Use": true,
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Auto_Enroll": false,
        "Pay_Component_Reference": [
            {
                "type": "Workday_Earning_Code",
                "code": "W_DEU_PHI"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm",
        "Do_Not_Calculate_Remaining_Pay_Periods": false,
        "Health_Savings_Account_Plan_Rate_ID": "HEALTH_SAVINGS_ACCOUNT_PLAN_RATE-6-2",
        "Inactive": false,
        "Limit_Data": [
            {
                "Health_Savings_Account_Coverage_Target_ID": "Employee_Health_Savings_Account_Coverage_Target_ID",
                "Contribution_Maximum": "100",
                "Minimum_Pledge": "100",
                "Employer_Contribution": "10"
            },
            {
                "Health_Savings_Account_Coverage_Target_ID": "Family_Health_Savings_Account_Coverage_Target_ID",
                "Contribution_Maximum": "100",
                "Minimum_Pledge": "100",
                "Employer_Contribution": "10"
            }
        ]
    }
}

Spending Accounts Plan

The parameters apart from the above described ones are:

  1. Employee minimum contribution (Contribution_Minimum)
  2. Employee maximum contribution (Contribution_Maximum)
  3. Employer Contribution: (Employer_Contribution)

All are amount based

{
    "name": "Spending Plan Knit",
    "type": "SPENDING_ACCOUNT_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a spendings savings plan for India.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-63",
        "Benefit_Coverage_Type_ID": "548.1",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-4-6"
        ],
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "ADD-1223",
        "Do_Not_Use": true,
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Pay_Component_Reference": [
            {
                "type": "Workday_Earning_Code",
                "code": "W_DEU_PHI"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm",
        "Contribution_Minimum": "10",
        "Contribution_Maximum": "100",
        "Employer_Contribution": "10"
    }
}

Insurance Coverage Plan

The parameters apart from the above described ones are:

  1. Insurance Coverage (Insurance_Coverage_ID): It describes the ID for kind of insurance quantum like - x percent of salary etc.
  2. Insurance Target(Insurance_Coverage_Target_ID): It is the ID for different insurance coverage target like - employee, spouse, faimly etc.
  3. Dependent Eligibility Rule (Dependent_Eligibility_Rule_Reference): It is the Id for type of dependent eligible for insurance like Child below 18 , Parents less than age 60 etc.
{
    "name": "Insurance Plan Knit API",
    "type": "INSURANCE_COVERAGE_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a insurance coveraage plan for India.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-63",
        "Benefit_Coverage_Type_ID": "550.1",
        "Insurance_Coverage_ID": "MULTIPLES_OF_SALARY_COVERAGE-6-1",
        "Insurance_Coverage_Target_ID": "551.2",
        "Dependent_Eligibility_Rule_Reference": "DEPENDENT_BENEFIT_ELIGIBILITY_RULE-6-2",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-4-6"
        ],
        "Insurance_Rate_Reference": [
            "INSURANCE_FIXED_RATE-4-15"
        ],
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "ADD-1223",
        "Use_Individual_Rates": false,
        "Auto_Enroll": false,
        "Reset_Individual_Rates": false,
        "Pretax": false,
        "Nontaxable": false,
        "Inactive": false,
        "Insurance_Plan_Rate_ID": "INSURANCE_PLAN_RATE-4-14",
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Pay_Component_Reference": [
            {
                "type": "Workday_Earning_Code",
                "code": "W_DEU_PHI"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm"
    }
}

Health Care Coverage Plan

The parameters apart from the above described ones are:

  1. Rate ID (Health_Care_Rate_Type_ID): It is the ID for rate type - Flat Rate OR Calculcation Based Rate.
  2. Banded Rate Reference : Required for Flat Rate.
  3. Coverage_Cost_Data: Required for calculation based Rate.
{
    "name": "Health Care coverage Plan Knit API",
    "type": "HEALTH_COVERAGE_CARE_PLAN",
    "frequency": "MONTHLY",
    "description": "This is a health care coverage plan for India.",
    "metadata": {
        "Benefit_Provider_ID": "BENEFIT_PROVIDER-6-63",
        "Benefit_Coverage_Type_ID": "540.2",
        "Health_Care_Classification_ID": "HEALTH_CARE_CLASSIFICATION-6-6",
        "Dependent_Eligibility_Rule_Reference": "DEPENDENT_BENEFIT_ELIGIBILITY_RULE-6-2",
        "Over_Age_Dependent_Eligibility_Rule_Reference": "DEPENDENT_BENEFIT_ELIGIBILITY_RULE-4-11",
        "Health_Care_Rate_Type_ID": "3261.1",
        "Benefit_Group_Reference": [
            "BENEFIT_GROUP-4-6"
        ],
        "Coverage_Cost_Data": [
            {
                "Health_Care_Coverage_Target_ID": "546.3",
                "Employee_Cost_Pre-Tax": "100",
                "Employee_Cost_Post-Tax": "90",
                "Employer_Cost_Non-Taxable": "10",
                "Employer_Cost_Taxable": "10",
                "Fair_Market_Value_per_Dependent": "10"
            }
        ],
        "Banded_Rate_Reference": {
            "Benefit_Rate_ID": "ID_1234"
        },
        "Currency_ID": "INR",
        "Effective_Date": "2024-03-22Z",
        "Group_Policy_Number": "ADD-1223",
        "Derive_Coverage_Targets": false,
        "Requires_Provider_ID": false,
        "Is_High_Deductible_Health_Plan": false,
        "Use_Individual_Rates": false,
        "Auto_Enroll": false,
        "Reset_Individual_Rates": false,
        "ACA_Minimum_Value_Coverage": false,
        "ACA_Minimum_Essential_Coverage_for_Employee": false,
        "ACA_Minimum_Essential_Coverage_for_Spouse": false,
        "ACA_Minimum_Essential_Coverage_for_Dependents": false,
        "Spousal_coverage_offered_conditionally": false,
        "Rx_Group_Number": "RXG",
        "Rx_PCN": "PCN",
        "Rx_BIN": "BIN",
        "Rx_Toll_Free_Complete_Phone_Number": "+102929292",
        "Worker_Eligibility_Rule_Reference": "BENEFIT_PLAN_ELIGIBILITY_RULE-4-16",
        "Pay_Component_Reference": [
            {
                "type": "Workday_Earning_Code",
                "code": "W_DEU_PHI"
            }
        ],
        "External_URL_Reference": "http://www.aetna.com/index.htm"
    }
}

Updated 8 months ago