> ## 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.

# Garnishment Object

> The Garnishment Object represents a court or agency withholding order applied to an employee or contractor.

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`):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.