Deduction Template Definition Object

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 (Coming Q3) - (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.

403(b) (Coming Q3) - (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 (Coming Q3) - (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 (Coming Q3) - (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 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 edit it. 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, 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 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 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.34
  • percentage - 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"
            ]
        },
        "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"
            ]
        }
    }
}