Miscellaneous

A miscellaneous deduction is a catch-all for one-off or system-generated withholdings that aren't a recurring benefit election (see Benefits) and aren't a legally ordered garnishment. Typical uses: correcting an overpayment, recouping a cash advance, taking a deduction against an employee's final paycheck only, offsetting imputed income, or clawing back an expense reimbursement.

Auth

Requires a bearer access token (see How to Get API Access).

Endpoint

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/deductions/misc

CLIENT_ID is the company identifier returned as id when you create the company. EMPLOYEE_ID is the employee identifier returned as id when you create the employee.

Request fields

Field	Type	Required	Description
`description`	string	Yes	What this deduction is for, e.g. `"Cash advance recoupment"`.
`startDate`	string (ISO date-time)	Yes	Date the deduction becomes effective.
`endDate`	string (ISO date-time) \| null	No	Date the deduction stops being taken. Leave unset for a deduction with no fixed end date.
`note`	string \| null	No	Free-text note, for your own records.
`code`	string \| null	No	A short deduction code. Defaults to `"MISC"` if not specified.
`paymentMethod`	integer (enum)	No	How the withheld amount is disbursed. See Payment Method values below.
`bankAccountNumber`	string \| null	Only if `paymentMethod` is `1` (ACH)	Destination bank account number. Not used for any other payment method.
`routingNumber`	string \| null	Only if `paymentMethod` is `1` (ACH)	Destination bank routing number. Not used for any other payment method.
`accountType`	integer (enum)	Only if `paymentMethod` is `1` (ACH)	The destination account type. See Account Type values below. Not used for any other payment method.
`schedule`	integer (enum)	No	Which pay periods this deduction applies to. See Schedule values below.
`lifetimeGoal`	number ≥ 0 \| null	No	Total amount to withhold over the life of the deduction.
`annualLimit`	number ≥ 0 \| null	No	Cap on the amount withheld from this deduction within a calendar year.
`employeeDeduction`	object \| null	No*	The amount withheld from the employee's pay each period. See "Deduction/contribution object" below. *Not enforced by the API, but if you omit it the deduction is created with nothing to withhold — include it if you want the deduction to actually take money out of pay.
`employerContribution`	object \| null	No	An employer-side contribution amount associated with this deduction. Same shape as `employeeDeduction` — see below.

Payment Method values

Value	Name	Meaning
0	`None`	The amount is withheld from pay only; nothing is disbursed elsewhere.
1	`ACH`	The withheld amount is disbursed via direct deposit to the bank account given in `bankAccountNumber`/`routingNumber`/`accountType`.

Account Type values

Value	Meaning
1	Checking
2	Savings

Schedule values

Value	Name	Meaning
0	`AllPayPeriods`	Every pay period.
1	`FirstEachMonth`	First pay period each month.
2	`SecondEachMonth`	Second pay period each month.
3	`ThirdEachMonth`	Third pay period each month.
4	`FourthEachMonth`	Fourth pay period each month.
5	`FifthEachMonth`	Fifth pay period each month.
6	`LastEachMonth`	Last pay period each month.
7	`SameNumberEachMonth`	Same number of pay periods each month.
8	`FirstEachYear`	First pay period each year.
9	`FirstEachQuarter`	First pay period each quarter.
10	`FirstEachHalfYear`	First pay period each half-year.

Deduction/contribution object

employeeDeduction and employerContribution share the same shape:

Field	Type	Description
`type`	integer (enum)	`1` = flat amount — `amount` is a dollar amount. `2` = percentage — `amount` is a percentage.
`amount`	number	The dollar amount or percentage, depending on `type`.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = process.env.EMPLOYEE_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}/deductions/misc`;

const payload = {
  description: "Cash advance",
  startDate: "2026-09-15T00:00:00.000Z",
  note: "Recovering $600 cash advance issued 2026-08-01, per employee agreement.",
  employeeDeduction: {
    type: 1, // flat amount
    amount: 75
  },
  lifetimeGoal: 600
};

async function createMiscDeduction() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  console.log(await response.text());
}

createMiscDeduction();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/deductions/misc" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "description": "Cash advance",
    "startDate": "2026-09-15T00:00:00.000Z",
    "note": "Recovering $600 cash advance issued 2026-08-01, per employee agreement.",
    "employeeDeduction": {
      "type": 1,
      "amount": 75
    },
    "lifetimeGoal": 600
  }' | jq .

Example response

{
  "id": 578,
  "code": "MISC",
  "paymentMethod": 0,
  "bankAccountNumber": "",
  "routingNumber": "",
  "schedule": 0,
  "lifetimeGoal": 600,
  "employeeDeduction": {
    "type": 1,
    "amount": 75
  },
  "description": "Cash advance",
  "startDate": "2026-09-15",
  "note": "$600 cash advance issued 2026-08-01, per employee agreement."
}

id is the deduction's unique identifier.

Notes

If code is omitted, it defaults to "MISC".
bankAccountNumber, routingNumber, and accountType only apply when paymentMethod is 1 (ACH). Leave them unset for paymentMethod: 0 (the default disbursement, withheld from pay only).
employeeDeduction isn't required by the API, but a deduction created without it has nothing configured to withhold — set it if you want the deduction to actually reduce the employee's pay.