Deduction Template Definition represents a JSON schema, which is essentially a way to represent instructions to create a Deduction Template in a JSON format.

With Zeal, using a Deduction Template Definition object, you first create a Deduction Template, and then subsequently create a Deduction using the Deduction Template, which also contains a JSON schema.

The different types of Deduction Template Definition objects that Zeal returns are listed below.

Types of Deductions

{
    "success": true,
    "data": {
        "type": "object",
        "required": [
            "employee_contribution",
            "additional_fields"
        ],
        "properties": {
            "required_template_fields": {
                "const": [
                    "employee_contribution"
                ]
            },
            "custom_name": {
                "type": "string"
            },
            "deduction_type": {
                "const": "hsa"
            },
            "employee_contribution": {
                "type": "object",
                "properties": {
                    "contribution_type": {
                        "enum": [
                            "dollars"
                        ]
                    },
                    "value": {
                        "type": "number"
                    },
                    "override_type": {
                        "enum": [
                            "overridable",
                            "needs_input",
                            "final"
                        ]
                    },
                    "required_template_fields": {
                        "const": [
                            "value"
                        ]
                    }
                },
                "allOf": [
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "final"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    },
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "overridable"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    }
                ],
                "required": [
                    "override_type",
                    "contribution_type"
                ]
            },
            "employer_contribution": {
                "type": "object",
                "properties": {
                    "contribution_type": {
                        "enum": [
                            "dollars"
                        ]
                    },
                    "value": {
                        "type": "number"
                    },
                    "override_type": {
                        "enum": [
                            "overridable",
                            "needs_input",
                            "final"
                        ]
                    },
                    "required_template_fields": {
                        "const": [
                            "value"
                        ]
                    }
                },
                "allOf": [
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "final"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    },
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "overridable"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    }
                ],
                "required": [
                    "override_type",
                    "contribution_type"
                ]
            },
            "additional_fields": {
                "type": "object",
                "properties": {
                    "hsa_type": {
                        "enum": [
                            "family",
                            "individual"
                        ]
                    }
                },
                "required": [
                    "hsa_type"
                ]
            }
        }
    }
}

{
  "success": true,
  "data": {
    "type": "object",
    "required": [
      "employee_contribution",
      "custom_name"
    ],
    "properties": {
      "required_template_fields": {
        "const": [
          "employee_contribution"
        ]
      },
      "custom_name": {
        "type": "string"
      },
      "deduction_type": {
        "const": "401k"
      },
      "employee_contribution": {
        "type": "object",
        "properties": {
          "contribution_type": {
            "enum": [
              "dollars",
              "percentage"
            ]
          },
          "percentage_source": {
            "const": "gross"
          },
          "value": {
            "type": "number"
          },
          "override_type": {
            "enum": [
              "overridable",
              "needs_input",
              "final"
            ]
          },
          "required_template_fields": {
            "const": [
              "value"
            ]
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "final"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "overridable"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          }
        ],
        "required": [
          "override_type",
          "contribution_type"
        ]
      },
      "employer_contribution": {
        "type": "object",
        "properties": {
          "contribution_type": {
            "enum": [
              "dollars"
            ]
          },
          "value": {
            "type": "number"
          },
          "override_type": {
            "enum": [
              "overridable",
              "needs_input",
              "final"
            ]
          },
          "required_template_fields": {
            "const": [
              "value"
            ]
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "final"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "overridable"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          }
        ],
        "required": [
          "override_type",
          "contribution_type"
        ]
      }
    }
  }
}

{
    "success": true,
    "data": {
        "type": "object",
        "required": [
            "employee_contribution",
            "additional_fields"
        ],
        "properties": {
            "custom_name": {
                "type": "string"
            },
            "deduction_type": {
                "const": "garnishment"
            },
            "employee_contribution": {
                "type": "object",
                "properties": {
                    "contribution_type": {
                        "enum": [
                            "dollars",
                          	"percentage"
                        ]
                    },
                    "override_type": {
                        "enum": [
                            "overridable",
                            "needs_input",
                            "final"
                        ]
                    },
                    "value": {
                        "type": "number"
                    }
                },
                "allOf": [
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "final"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    },
                    {
                        "if": {
                            "properties": {
                                "override_type": {
                                    "const": "overridable"
                                }
                            },
                            "required": [
                                "override_type"
                            ]
                        },
                        "then": {
                            "required": [
                                "value"
                            ]
                        }
                    }
                ],
                "required": [
                    "override_type",
                    "contribution_type"
                ]
            },
            "additional_fields": {
                "type": "object",
                "required": [
                    "order_number",
                    "case_id",
                    "agency"
                ],
                "properties": {
                    "required_template_fields": {
                        "const": [
                            "agency",
                            "case_id"
                        ]
                    },
                    "order_number": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "value": {
                                "type": "string"
                            }
                        },
                        "allOf": [
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "final"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "value"
                                    ]
                                }
                            },
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "overridable"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "value"
                                    ]
                                }
                            }
                        ],
                        "required": [
                            "override_type"
                        ]
                    },
                    "case_id": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "value": {
                                "type": "string"
                            }
                        },
                        "allOf": [
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "final"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "value"
                                    ]
                                }
                            },
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "overridable"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "value"
                                    ]
                                }
                            }
                        ],
                        "required": [
                            "override_type"
                        ]
                    },
                    "agency": {
                        "type": "object",
                        "properties": {
                            "override_type": {
                                "enum": [
                                    "overridable",
                                    "needs_input",
                                    "final"
                                ]
                            },
                            "address": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "allOf": [
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "final"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "address",
                                        "name"
                                    ]
                                }
                            },
                            {
                                "if": {
                                    "properties": {
                                        "override_type": {
                                            "const": "overridable"
                                        }
                                    },
                                    "required": [
                                        "override_type"
                                    ]
                                },
                                "then": {
                                    "required": [
                                        "address",
                                        "name"
                                    ]
                                }
                            }
                        ],
                        "required": [
                            "override_type"
                        ]
                    }
                }
            }
        }
    }
}

{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "section_125"
        },
        "employee_contribution": {
            "properties": {
                "contribution_type": {
                    "enum": [
                        "flat"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                }
            },
            "required_template_fields": {
                "const": [
                    "value"
                ]
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}

{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "miscellaneous"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "post_tax": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}

{
  "success": true,
  "data": {
    "type": "object",
    "required": [
      "employee_contribution"
    ],
    "properties": {
      "required_template_fields": {
        "const": [
          "employee_contribution"
        ]
      },
      "custom_name": {
        "type": "string"
      },
      "deduction_type": {
        "const": "roth_401k"
      },
      "employee_contribution": {
        "type": "object",
        "properties": {
          "contribution_type": {
            "enum": [
              "dollars",
              "percentage"
            ]
          },
          "percentage_source": {
            "const": "gross"
          },
          "value": {
            "type": "number"
          },
          "override_type": {
            "enum": [
              "overridable",
              "needs_input",
              "final"
            ]
          },
          "required_template_fields": {
            "const": [
              "value"
            ]
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "final"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "override_type": {
                  "const": "overridable"
                }
              },
              "required": [
                "override_type"
              ]
            },
            "then": {
              "required": [
                "value"
              ]
            }
          }
        ],
        "required": [
          "override_type",
          "contribution_type"
        ]
      }
    }
  }
}

{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "403(b)"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "percentage_source": {
                    "enum": [
                        "contribution",
                        "paycheck"
                    ]
                },
                "matching": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type",
                "matching"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}

{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "simple_ira"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
        },
        "employer_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars"
                    ]
                },
                "percentage_source": {
                    "enum": [
                        "contribution",
                        "paycheck"
                    ]
                },
                "matching": {
                    "type": "boolean"
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type",
                "matching"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}

{
    "type": "object",
    "properties": {
        "custom_name": {
            "type": "string"
        },
        "deduction_type": {
            "const": "roth_ira"
        },
        "employee_contribution": {
            "type": "object",
            "properties": {
                "contribution_type": {
                    "enum": [
                        "dollars",
                        "percentage"
                    ]
                },
                "value": {
                    "type": "number"
                },
                "override_type": {
                    "enum": [
                        "overridable",
                        "needs_input",
                        "final"
                    ]
                },
                "required_template_fields": {
                    "const": [
                        "value"
                    ]
                }
            },
            "required": [
                "override_type",
                "contribution_type"
            ]
       		 },
            "required": [
                "override_type",
                "contribution_type",
                "matching"
            ]
        },
        "required_template_fields": {
            "const": [
                "employee_contribution"
            ]
        }
    }
}

The following is a list of deductions (pre-tax and post-tax) that Zeal supports:

401k - (Pre-Tax) A 401(k) plan is a tax-qualified, defined-contribution pension account that provides for pretax retirement savings.

hsa - (Pre-Tax) A health savings account (HSA) is a tax-advantaged medical savings account enrolled in a high-deductible health plan. Funds accumulate and can be used to pay for qualified medical expenses without tax liabilities.

garnishment - (Post-Tax) A garnishment is a court-mandated withholding of an employee’s earnings from a paycheck for use toward debts. Common sources include child support, federal debt, state debt, student loans, and credit card debt. This serves as a post-tax deduction.

miscellaneous - (Post-Tax) A type for a generic post-tax deduction on the employee check.

section_125 - (Pre-Tax) A benefit belonging to a Section 125 plan that allows employees to choose between different types of qualified benefits.

roth_401k - (Post-Tax) The Roth 401(k) is a defined-contribution pension account that requires that the income tax be paid immediately, so the employee's real net income is reduced by the amount earmarked for savings. Employers can match employee contributions to a Roth 401k, but those employer contributions must be matched in a separate traditional 401k deduction.

403(b) - (Pre-Tax) A 403(b) plan (tax-sheltered annuity plan or TSA) is a retirement plan offered by public schools, non-profit organizations, and government entities It is similar to a 401(k) plan maintained by a for-profit entity. Just as with a 401(k) plan, a 403(b) plan lets employees defer some of their salary into individual accounts.

simple_ira - (Pre-Tax) A SIMPLE IRA plan (Savings Incentive Match Plan for Employees) allows employees and employers to contribute to traditional IRAs set up for employees by usually smaller businesses or companies.

roth_ira - (Post-Tax) A Individual Retirement Account to which you contribute after-tax dollars. Your contributions and earnings can grow tax-free, and you can withdraw them tax- and penalty-free after age 59½ and once the account has been open for five years

calsavers - (Post-tax) California’s state-mandated retirement savings program for employees who don’t have access to a workplace retirement plan. Employers with five or more employees are required to either offer a qualified retirement plan or register for CalSavers and facilitate payroll deductions. The program uses Roth IRAs, meaning contributions are made with after-tax dollars and qualified withdrawals are tax-free. Contributions are not tax-deductible for employees, and employers are not required to contribute or pay any fees.

dependent_care_benefit - (Pre Tax) Dependent care benefits refer to specific benefits that are provided by employers to their employees in the care of their dependents. Dependent care benefits are under a bigger umbrella of the employee benefits system administered by the Internal Revenue Service (IRS). A list of dependent care benefits can be found in the W-2 Form, box 10

employer_sponsored_health_coverage - (Pre Tax) The Affordable Care Act requires employers to report the cost of coverage under an employer-sponsored group health plan on an employee’s Form W-2, Wage and Tax Statement, in Box 12, using Code DD. The amount reported does not affect tax liability, as the value of the employer contribution continues to be excludable from an employee’s income and is not taxable. This reporting is for informational purposes only, to show employees the value of their health care benefits.
Note - employer_sponsored_health_coverage needs both the employer and employee contributions. It's expected that the employee contributions will be set to 0 through the API

Override Types

final - Use this override_type when creating a Deduction Template, if you want to set the contribution field to only be set by the employer, and not let employees override it. An example of this would be setting the employer contribution on a 401k
overridable - Use this override_type when creating a Deduction Template, if you want to set an initial value from the employer's side, the employee can change it. An example of this would be setting the hsa_type to be individual at first, but allowing an employee to set it to family.
needs_input - Use this override_type when creating a Deduction Template, if you want the employee to set their contribution amount. If the field is left blank by the employee, it will be set to 0. An example of this would be an employee setting their preferred contribution amount for a 401k plan.

Contribution Types

dollars - Amount is accepted as number
percentage - Amount is to be accepted as a percentage of the pay, e.g. 10.21