Create garnishment case

POST/payroll/garnishments

Records a new court-ordered wage garnishment for an employee. The system applies garnishment withholding automatically during payroll calculation according to jurisdiction rules and priority ordering. Supply arrears to track total owed until satisified.

Request

Request body

Content type application/json (required).

Field	Type	Required	Description
id	integer	No	Auto-incremented primary key (present on responses, omit on create).
order_reference	string	Yes	Unique court order reference number (e.g. case number from the issuing court). Max length: 120
employee_id	integer	Yes	ID of the employee subject to this garnishment.
jurisdiction	string	Yes	ISO 3166-1 alpha-2 country code of the issuing jurisdiction (e.g. "GH", "US"). Max length: 10
start_date	string (date)	Yes	Date from which garnishment withholding begins.
end_date	string (date), nullable	No	Date on which garnishment ends. Null for open-ended orders satisfied when arrears reach zero.
priority	integer, nullable	No	Priority ordering when multiple garnishments apply (lower number = higher priority).
max_withholding_type	string	Yes	Whether the maximum withholding limit is expressed as a percentage of disposable income ("percent") or a fixed monetary amount ("fixed"). One of: "percent", "fixed"
max_withholding_value	number (float)	Yes	The maximum withholding amount or percentage per pay period.
arrears	number (float), nullable	No	Total outstanding balance owed. The garnishment is automatically closed when cumulative withholdings satisfy the arrears.
status	string	No	Current status of the garnishment case (present on responses). One of: "active", "satisfied", "cancelled", "expired"

Example

{
  "order_reference": "COURT-ACC-2026-00141",
  "employee_id": 42,
  "jurisdiction": "GH",
  "start_date": "2026-03-01",
  "priority": 1,
  "max_withholding_type": "percent",
  "max_withholding_value": 20.0,
  "arrears": 1500.0
}

Responses

201 Garnishment case created and will be applied from the next payroll run

Content type application/json, object · GarnishmentOrderV1.

Field	Type	Required	Description
id	integer	No	Auto-incremented primary key (present on responses, omit on create).
order_reference	string	Yes	Unique court order reference number (e.g. case number from the issuing court). Max length: 120
employee_id	integer	Yes	ID of the employee subject to this garnishment.
jurisdiction	string	Yes	ISO 3166-1 alpha-2 country code of the issuing jurisdiction (e.g. "GH", "US"). Max length: 10
start_date	string (date)	Yes	Date from which garnishment withholding begins.
end_date	string (date), nullable	No	Date on which garnishment ends. Null for open-ended orders satisfied when arrears reach zero.
priority	integer, nullable	No	Priority ordering when multiple garnishments apply (lower number = higher priority).
max_withholding_type	string	Yes	Whether the maximum withholding limit is expressed as a percentage of disposable income ("percent") or a fixed monetary amount ("fixed"). One of: "percent", "fixed"
max_withholding_value	number (float)	Yes	The maximum withholding amount or percentage per pay period.
arrears	number (float), nullable	No	Total outstanding balance owed. The garnishment is automatically closed when cumulative withholdings satisfy the arrears.
status	string	No	Current status of the garnishment case (present on responses). One of: "active", "satisfied", "cancelled", "expired"

422 Validation failed — check max_withholding_type, jurisdiction, or employee_id

Example request

curl -X POST "https://{tenant}.faciotech.net/api/v1/payroll/garnishments" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_reference": "COURT-ACC-2026-00141", "employee_id": 42, "jurisdiction": "GH", "start_date": "2026-03-01", "priority": 1, "max_withholding_type": "percent", "max_withholding_value": 20.0, "arrears": 1500.0}'