> ## 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. # Create Garnishment > Creates a garnishment for an employee or contractor. Creates a garnishment for an employee or contractor. Provide either simple caps (`cap_amount` and/or `cap_percentage`) **or** an advanced `withholding_schedule` (not both). Advanced schedules are employee-only — contractors have no pay frequency, so use simple caps instead. When both caps are set, the withholding engine applies the stricter (lower) of the two on each check or payment. A schedule defines fixed amounts and/or disposable-earnings brackets per pay frequency (money fields in dollars). Each frequency branch must tile disposable earnings from `$0.00` to infinity with no gaps or overlaps (first `min` is `0`, each next `min` is the previous `max` plus `$0.01`, last `max` is `null`), and at least one bracket must withhold. A schedule does not need to cover every pay frequency — include only the frequencies the order specifies; a payment whose pay frequency is not listed in the schedule withholds nothing. You may pass `total_amount_withheld` to seed prior withholdings (for example when migrating an existing order); when `total_amount_owed` is set, it must be greater than or equal to `total_amount_withheld`. ## OpenAPI ````yaml openapi/zeal-api.json post /garnishments openapi: 3.1.0 info: title: zeal-api version: '1.0' servers: - url: https://api.zeal.com security: - sec0: [] paths: /garnishments: post: summary: Create Garnishment description: >- Creates a garnishment for an employee or contractor. Provide either simple caps (cap_amount and/or cap_percentage) or an advanced withholding_schedule (not both). withholding_schedule is employee-only; contractors have no pay frequency and must use simple caps. A withholding_schedule must tile $0.00 to infinity per pay frequency with no gaps or overlaps, and at least one bracket must withhold. operationId: create-garnishment requestBody: required: true content: application/json: schema: type: object required: - companyID - workerID - workerType - garnishment_type - effective_start_date - agency_name - agency_address - case_id - order_number properties: companyID: type: string description: Company ID of employer workerID: type: string description: Employee or contractor ID workerType: type: string enum: - employee - contractor description: >- Whether the worker is an employee or contractor. withholding_schedule is supported for employees only. garnishment_type: type: string enum: - child_support - federal_tax_levy - state_tax_levy - creditor - student_loan - other description: Type of garnishment order priority: type: integer minimum: 0 description: >- Optional. Prefer omitting `priority` unless you need a custom withholding order. When omitted, Zeal applies a federal-baseline default by `garnishment_type` (lower numbers are withheld first): `child_support`=10, `federal_tax_levy`=20, `state_tax_levy`=30, `student_loan`=40, `creditor`=50, `other`=60. Defaults are spaced by 10 so you can insert an override between two types without renumbering everything. total_amount_owed: type: number minimum: 0 description: >- Total balance owed in dollars. Omit for open-ended orders. When set, must be greater than or equal to total_amount_withheld. total_amount_withheld: type: number minimum: 0 description: >- Optional. Amount already withheld before this garnishment was created, in dollars (for example when migrating an existing order). Defaults to 0. When total_amount_owed is set, it must be greater than or equal to total_amount_withheld. effective_start_date: type: string description: ISO date (YYYY-MM-DD) when withholding begins effective_end_date: type: string description: >- ISO date (YYYY-MM-DD) when withholding ends. Must be after effective_start_date. agency_name: type: string description: Name of the collecting agency agency_address: type: string description: Address of the collecting agency cap_amount: type: number minimum: 0 description: >- Per-paycheck maximum withhold amount in dollars. At least one of cap_amount, cap_percentage, or withholding_schedule is required. Mutually exclusive with withholding_schedule. cap_percentage: type: number minimum: 0 maximum: 100 description: >- Per-paycheck maximum withhold percentage (0-100). At least one of cap_amount, cap_percentage, or withholding_schedule is required. Mutually exclusive with withholding_schedule. garnishment_state: type: string description: US state code (2-letter) associated with the order case_id: type: string description: Court/agency case identifier order_number: type: string description: Court/agency order number custom_name: type: string description: Optional display name for this garnishment external_id: type: string description: Optional external identifier for your own systems withholding_schedule: $ref: '#/components/schemas/WithholdingSchedule' examples: Simple caps: value: companyID: 1eeec343485723ee58afef12 workerID: 674759a85785745748e3847a workerType: contractor garnishment_type: creditor effective_start_date: '2025-01-01' agency_name: Acme Agency agency_address: 123 Court St case_id: CASE-1 order_number: ORD-1 cap_percentage: 25 total_amount_owed: 500 total_amount_withheld: 0 Withholding schedule (fixed amount per pay frequency): summary: Fixed amount per pay frequency value: companyID: 1eeec343485723ee58afef12 workerID: 674759a85785745748e3847a workerType: employee garnishment_type: child_support effective_start_date: '2025-01-01' agency_name: State Disbursement Unit agency_address: 5500 S Eastern Ave, Commerce CA 90040 case_id: '200000002611596' order_number: 23CWCS16629 withholding_schedule: - frequency: weekly brackets: - min: 0 max: null action: kind: amount amount: 216.34 - frequency: biweekly brackets: - min: 0 max: null action: kind: amount amount: 432.69 - frequency: monthly brackets: - min: 0 max: null action: kind: amount amount: 937.5 Withholding schedule: summary: Advanced withholding schedule value: companyID: 1eeec343485723ee58afef12 workerID: 674759a85785745748e3847a workerType: employee garnishment_type: creditor effective_start_date: '2025-01-01' agency_name: Acme Agency agency_address: 123 Court St case_id: CASE-1 order_number: ORD-1 withholding_schedule: - frequency: weekly brackets: - min: 0 max: 217.5 action: kind: exempt - min: 217.51 max: 290 action: kind: excess_over_floor floor: 217.5 - min: 290.01 max: null action: kind: percentage percentage: 25 - frequency: monthly brackets: - min: 0 max: null action: kind: amount amount: 937.5 total_amount_owed: 500 total_amount_withheld: 0 responses: '201': description: '201' content: application/json: examples: Simple caps: value: success: true data: garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa companyID: 1eeec343485723ee58afef12 workerID: 674759a85785745748e3847a workerType: contractor garnishment_type: creditor priority: 50 total_amount_owed: 500 total_amount_withheld: 0 status: active effective_start_date: '2025-01-01' agency_name: Acme Agency agency_address: 123 Court St cap_percentage: 25 case_id: CASE-1 order_number: ORD-1 created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' Withholding schedule: summary: Advanced withholding schedule value: success: true data: garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa companyID: 1eeec343485723ee58afef12 workerID: 674759a85785745748e3847a workerType: employee garnishment_type: creditor priority: 50 total_amount_owed: 500 total_amount_withheld: 0 status: active effective_start_date: '2025-01-01' agency_name: Acme Agency agency_address: 123 Court St withholding_schedule: - frequency: weekly brackets: - min: 0 max: 217.5 action: kind: exempt - min: 217.51 max: 290 action: kind: excess_over_floor floor: 217.5 - min: 290.01 max: null action: kind: percentage percentage: 25 - frequency: monthly brackets: - min: 0 max: null action: kind: amount amount: 937.5 case_id: CASE-1 order_number: ORD-1 created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' schema: type: object properties: success: type: boolean example: true default: true data: type: object properties: garnishmentID: type: string description: Unique identifier for this garnishment example: 3cab1c18d38a45e7a688aceeb4fcfcaa companyID: type: string description: Company ID of employer example: 1eeec343485723ee58afef12 workerID: type: string description: Employee or contractor ID this garnishment applies to example: 674759a85785745748e3847a workerType: type: string enum: - employee - contractor description: Whether the worker is an employee or contractor example: contractor garnishment_type: type: string enum: - child_support - federal_tax_levy - state_tax_levy - creditor - student_loan - other description: Type of garnishment order example: creditor priority: type: integer description: >- Effective withholding priority. Lower numbers are withheld first. When omitted on create, Zeal applies a type-based default (child_support=10, federal_tax_levy=20, state_tax_levy=30, student_loan=40, creditor=50, other=60). example: 50 total_amount_owed: type: number description: >- Total balance owed in dollars. Omit for open-ended / forever orders. example: 500 total_amount_withheld: type: number description: Total amount withheld to date in dollars example: 0 status: type: string enum: - active - satisfied - modified - vacated - canceled description: Lifecycle status of the garnishment example: active effective_start_date: type: string description: ISO date (YYYY-MM-DD) when withholding begins example: '2025-01-01' effective_end_date: type: string description: >- ISO date (YYYY-MM-DD) when withholding ends. Omit for open-ended orders. example: '2025-12-31' agency_name: type: string description: Name of the collecting agency example: Acme Agency agency_address: type: string description: Address of the collecting agency example: 123 Court St cap_amount: type: number description: >- Per-paycheck maximum withhold amount in dollars. At least one of cap_amount or cap_percentage is required on create. example: 150 cap_percentage: type: number description: >- Per-paycheck maximum withhold percentage of disposable earnings (0-100). At least one of cap_amount or cap_percentage is required on create. example: 25 garnishment_state: type: string description: US state code (2-letter) associated with the order example: CA case_id: type: string description: Court/agency case identifier example: CASE-1 order_number: type: string description: Court/agency order number example: ORD-1 custom_name: type: string description: Optional display name for this garnishment example: Acme creditor external_id: type: string description: Optional external identifier for your own systems example: ext-create-1 previous_garnishmentID: type: string description: >- ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (status: modified) transition; omitted otherwise. example: 2bab1c18d38a45e7a688aceeb4fcfcbb canceled_reason: type: string description: Reason provided when status is canceled satisfied_at: type: string description: ISO timestamp when the garnishment was fully satisfied created_at: type: string description: ISO timestamp when the garnishment was created example: '2025-01-01T00:00:00.000Z' updated_at: type: string description: ISO timestamp when the garnishment was last updated example: '2025-01-01T00:00:00.000Z' withholding_schedule: $ref: '#/components/schemas/WithholdingSchedule' '400': description: '400' content: application/json: examples: Result: value: success: false errors: - message: cap_amount or cap_percentage must be provided. code: 0 schema: type: object properties: success: type: boolean example: false errors: type: array items: type: object properties: message: type: string code: type: integer example: 0 deprecated: false components: schemas: WithholdingSchedule: type: array minItems: 1 description: >- Advanced withholding schedule (mutually exclusive with cap_amount / cap_percentage). Employee-only: contractors have no pay frequency, so a schedule on a contractor is rejected — use cap_amount / cap_percentage instead. Use for fixed amounts per pay frequency or disposable-earnings brackets. At least one of cap_amount, cap_percentage, or withholding_schedule is required. Money fields are in dollars. When present, every frequency branch must tile disposable earnings from $0.00 to infinity with no gaps or overlaps: the first bracket min must be 0, each next min must be exactly $0.01 after the previous max, and the last bracket max must be null. At least one bracket in the schedule must withhold (not all exempt). items: type: object required: - frequency - brackets properties: frequency: type: string enum: - daily - weekly - biweekly - semimonthly - monthly - quarterly description: Pay frequency this branch applies to brackets: type: array minItems: 1 description: >- Disposable-earnings brackets for this frequency. Must tile $0.00 to infinity with no gaps or overlaps (first min is 0; each next min is previous max + 0.01; last max is null). items: type: object required: - min - max - action properties: min: type: number minimum: 0 description: >- Inclusive lower bound of disposable earnings in dollars. The first bracket in a branch must start at 0. max: type: number minimum: 0 nullable: true description: >- Inclusive upper bound of disposable earnings in dollars. Only the last bracket may be null (open-ended); earlier brackets require a max. action: oneOf: - type: object required: - kind properties: kind: type: string enum: - exempt description: Do not withhold in this band - type: object required: - kind - amount properties: kind: type: string enum: - amount amount: type: number minimum: 0 description: Fixed dollar amount to withhold - type: object required: - kind - floor properties: kind: type: string enum: - excess_over_floor floor: type: number minimum: 0 description: >- Withhold disposable earnings above this floor (dollars) - type: object required: - kind - percentage properties: kind: type: string enum: - percentage percentage: type: number minimum: 0 maximum: 100 description: >- Percentage of disposable earnings to withhold (0-100) description: How to compute the withhold amount for this bracket securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer ````