> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Deduction Template Definitions

> Retrieve the JSON schema definition for a deduction type, describing every field allowed when creating a Deduction Template.

Zeal's deduction system lets you model additional withholding - 401(k), HSA, garnishments, and more - on top of standard tax withholdings. First define the rules by creating a **Deduction Template**, then attach a **Deduction** to a specific employee check. Each deduction type has a corresponding JSON-schema definition that tells you exactly which fields are required and what values are accepted.

### Reading the JSON Schema

The definition schema uses three value constraint types:

| Constraint | Meaning                                                     |
| ---------- | ----------------------------------------------------------- |
| `const`    | The field must be exactly that value                        |
| `enum`     | The field must be one of the listed values                  |
| `type`     | The field must match the given JSON type (e.g., `"number"`) |

The `required_template_fields` property is **not** included in the Deduction Template request body. Instead, it tells you which fields will be required later when you create an actual Deduction using that template.

### Understanding `override_type`

Contribution objects typically include an `override_type` field that controls how the value is handled at check time:

| Value         | Behavior                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| `final`       | The value set in the template is locked and cannot be changed when creating a deduction.                |
| `needs_input` | No default value is stored in the template. You must supply the value each time you create a deduction. |
| `overridable` | A default value is stored in the template but can be overridden when creating a deduction.              |


## OpenAPI

````yaml openapi/employee-checks.json get /deductionTemplateDefinitions
openapi: 3.1.0
info:
  title: zeal-api
  version: '1.0'
servers:
  - url: https://api.zeal.com
security:
  - sec0: []
paths:
  /deductionTemplateDefinitions:
    get:
      summary: Get Deduction Template Definitions
      description: Get a definition for a deduction template.
      operationId: get-deduction-template-definitions
      parameters:
        - name: deduction_type
          in: query
          description: Deduction type for which Deduction Template Definition is required
          required: true
          schema:
            type: string
            enum:
              - 401k
              - section_125
              - hsa
              - miscellaneous
              - garnishment
              - 403b
              - roth_ira
              - simple_ira
              - roth_401k
      requestBody:
        content:
          application/json:
            schema: {}
            examples:
              Request Example:
                value:
                  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
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    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
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                    default: true
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: object
                      required:
                        type: array
                        items:
                          type: string
                          example: employee_contribution
                      properties:
                        type: object
                        properties:
                          required_template_fields:
                            type: object
                            properties:
                              const:
                                type: array
                                items:
                                  type: string
                                  example: employee_contribution
                          custom_name:
                            type: object
                            properties:
                              type:
                                type: string
                                example: string
                          deduction_type:
                            type: object
                            properties:
                              const:
                                type: string
                                example: hsa
                          employee_contribution:
                            type: object
                            properties:
                              type:
                                type: string
                                example: object
                              properties:
                                type: object
                                properties:
                                  contribution_type:
                                    type: object
                                    properties:
                                      enum:
                                        type: array
                                        items:
                                          type: string
                                          example: dollars
                                  value:
                                    type: object
                                    properties:
                                      type:
                                        type: string
                                        example: number
                                  override_type:
                                    type: object
                                    properties:
                                      enum:
                                        type: array
                                        items:
                                          type: string
                                          example: overridable
                                  required_template_fields:
                                    type: object
                                    properties:
                                      const:
                                        type: array
                                        items:
                                          type: string
                                          example: value
                              allOf:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    if:
                                      type: object
                                      properties:
                                        properties:
                                          type: object
                                          properties:
                                            override_type:
                                              type: object
                                              properties:
                                                const:
                                                  type: string
                                                  example: final
                                        required:
                                          type: array
                                          items:
                                            type: string
                                            example: override_type
                                    then:
                                      type: object
                                      properties:
                                        required:
                                          type: array
                                          items:
                                            type: string
                                            example: value
                              required:
                                type: array
                                items:
                                  type: string
                                  example: override_type
                          employer_contribution:
                            type: object
                            properties:
                              type:
                                type: string
                                example: object
                              properties:
                                type: object
                                properties:
                                  contribution_type:
                                    type: object
                                    properties:
                                      enum:
                                        type: array
                                        items:
                                          type: string
                                          example: dollars
                                  value:
                                    type: object
                                    properties:
                                      type:
                                        type: string
                                        example: number
                                  override_type:
                                    type: object
                                    properties:
                                      enum:
                                        type: array
                                        items:
                                          type: string
                                          example: overridable
                                  required_template_fields:
                                    type: object
                                    properties:
                                      const:
                                        type: array
                                        items:
                                          type: string
                                          example: value
                              allOf:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    if:
                                      type: object
                                      properties:
                                        properties:
                                          type: object
                                          properties:
                                            override_type:
                                              type: object
                                              properties:
                                                const:
                                                  type: string
                                                  example: final
                                        required:
                                          type: array
                                          items:
                                            type: string
                                            example: override_type
                                    then:
                                      type: object
                                      properties:
                                        required:
                                          type: array
                                          items:
                                            type: string
                                            example: value
                              required:
                                type: array
                                items:
                                  type: string
                                  example: override_type
                          additional_fields:
                            type: object
                            properties:
                              type:
                                type: string
                                example: object
                              properties:
                                type: object
                                properties:
                                  hsa_type:
                                    type: object
                                    properties:
                                      enum:
                                        type: array
                                        items:
                                          type: string
                                          example: family
                              required:
                                type: array
                                items:
                                  type: string
                                  example: hsa_type
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: false
                    errors:
                      - message: Unsupported deduction type
                        code: 13
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                    default: true
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          example: Unsupported deduction type
                        code:
                          type: integer
                          example: 13
                          default: 0
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: Authorization
      x-bearer-format: bearer

````