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.
You can see below, the different types of Deduction Template Definition objects that Zeal returns
Types of Deductions
The following is a list of Deductions (both 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 Wage 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) Use this 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's 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
Override Types
-
final- Use thisoverride_typewhen creating a Deduction Template, if you want to set the contribution field to only be set by the employer, and not let employees edit it. Example of this would be setting the employer contribution on a 401k -
overridable- Use thisoverride_typewhen creating a Deduction Template, if you want to set an initial value from the employer's side, but the employee can change it. 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 thisoverride_typewhen creating a Deduction Template, if you want the employee to set their contribution amount. If the field is left blank by the employee, it should be set to 0. Example of this would be an employee setting their preferred contribution amount for a 401k plan.
Contribution Types
dollars- Amount is accepted as cents e.g. 10034 to represent $100.34percentage- Amount is to be accepted as a percentage, e.g. 10.21 (Not Currently Supported for Employer Contributions)
{
"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"
]
}
}
}
}
{
"type": "object",
"properties": {
"custom_name": {
"type": "string"
},
"deduction_type": {
"const": "401k"
},
"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"
]
}
}
}
{
"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"
]
}
}
}