Garnishment Object

The Garnishment Object represents a court or agency withholding order applied to an employee or contractor. Amounts are returned in dollars.

attribute	type	description
`garnishmentID`	string	Unique identifier for this garnishment
`companyID`	string	Company ID of employer
`workerID`	string	Employee or contractor ID this garnishment applies to
`workerType`	string	`employee` or `contractor`. Advanced `withholding_schedule` is employee-only
`garnishment_type`	string	One of `child_support`, `federal_tax_levy`, `state_tax_levy`, `creditor`, `student_loan`, `other`
`priority`	integer	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
`total_amount_owed`	number	Total balance owed in dollars. Omitted for open-ended orders
`total_amount_withheld`	number	Total amount withheld to date in dollars
`status`	string	One of `active`, `satisfied`, `modified`, `vacated`, `canceled`
`effective_start_date`	string	ISO date (`YYYY-MM-DD`) when withholding begins
`effective_end_date`	string	ISO date (`YYYY-MM-DD`) when withholding ends. Omitted for open-ended orders
`agency_name`	string	Name of the collecting agency
`agency_address`	string	Address of the collecting agency
`cap_amount`	number	Per-paycheck maximum withhold amount in dollars. Mutually exclusive with `withholding_schedule`
`cap_percentage`	number	Per-paycheck maximum withhold percentage of disposable earnings (`0`-`100`). Mutually exclusive with `withholding_schedule`
`withholding_schedule`	array	Advanced per-pay-frequency schedule (fixed amounts and/or disposable-earnings brackets). Employee-only — contractors have no pay frequency, so use `cap_amount` / `cap_percentage` instead. Mutually exclusive with `cap_amount` / `cap_percentage`. Money fields in dollars. On create or when sent on update, each frequency must tile `$0.00` to infinity with no gaps or overlaps, and at least one bracket must withhold. A schedule does not need to cover every pay frequency — a payment whose frequency is not listed withholds nothing. On update, sending a non-null schedule (or a non-null simple cap) clears the omitted opposite mode. See schema on Create / Update.
`garnishment_state`	string	US state code (2-letter) associated with the order
`case_id`	string	Court/agency case identifier
`order_number`	string	Court/agency order number
`custom_name`	string	Optional display name for this garnishment
`external_id`	string	Optional external identifier for your own systems
`previous_garnishmentID`	string	ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (`status: "modified"`) transition; omitted otherwise
`canceled_reason`	string	Reason provided when status is `canceled`
`satisfied_at`	string	ISO timestamp when the garnishment was fully satisfied
`created_at`	string	ISO timestamp when the garnishment was created
`updated_at`	string	ISO timestamp when the garnishment was last updated

Simple caps (cap_amount / cap_percentage):

{
  "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 (advanced withholding; employees only). Weekly uses disposable-earnings brackets; monthly uses a fixed amount. A payment whose pay frequency is not listed withholds nothing:

{
  "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"
}

Introduction

Webhooks

Zeal Components

Companies

Company Onboarding

Reserve Accounts

Customer Accounts (Early Access)

Taxable Locations

Work Locations

Employees

Employee Deduction Templates

Garnishments

Employee Onboarding

Bank Accounts

Custom Attributes

Paperwork API

Employee Checks

Contractors

Contractor Onboarding

Contractor Payment Deductions

Payment Items

Contractor Payments

Paycards

Instant Pay

Employer Checks

Preview

Embedded HR

Reports

Documents

Garnishment Object