Skip to main content
POST
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.

Authorizations

​
Authorization
string
header
required

Body

application/json
​
companyID
string
required

Company ID of employer

​
workerID
string
required

Employee or contractor ID

​
workerType
enum<string>
required

Whether the worker is an employee or contractor. withholding_schedule is supported for employees only.

Available options:
employee,
contractor
​
garnishment_type
enum<string>
required

Type of garnishment order

Available options:
child_support,
federal_tax_levy,
state_tax_levy,
creditor,
student_loan,
other
​
effective_start_date
string
required

ISO date (YYYY-MM-DD) when withholding begins

​
agency_name
string
required

Name of the collecting agency

​
agency_address
string
required

Address of the collecting agency

​
case_id
string
required

Court/agency case identifier

​
order_number
string
required

Court/agency order number

​
priority
integer

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.

Required range: x >= 0
​
total_amount_owed
number

Total balance owed in dollars. Omit for open-ended orders. When set, must be greater than or equal to total_amount_withheld.

Required range: x >= 0
​
total_amount_withheld
number

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.

Required range: x >= 0
​
effective_end_date
string

ISO date (YYYY-MM-DD) when withholding ends. Must be after effective_start_date.

​
cap_amount
number

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.

Required range: x >= 0
​
cap_percentage
number

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.

Required range: 0 <= x <= 100
​
garnishment_state
string

US state code (2-letter) associated with the order

​
custom_name
string

Optional display name for this garnishment

​
external_id
string

Optional external identifier for your own systems

​
withholding_schedule
object[]

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

Minimum array length: 1

Response

201

​
success
boolean
default:true
Example:

true

​
data
object