Guides
  1. Employee

Employee Pay Allocation

A pay allocation tells Worklio how to split an employee's net pay across one or more destinations — a paper check or a direct deposit to a bank account. An employee can have multiple pay allocations; together they determine where each pay period's net pay goes.

This is a follow-up step after creating an employee — you need the employee's id.

There are two ways to create a pay allocation, depending on whether the destination bank account already exists in Worklio:

  • Reference an existing bank account by its bankAccountId, if one was already added for the employee.
  • Provide the bank account details directly in the request, if the account hasn't been added yet.

How allocations are calculated

Allocations are calculated against the employee's full net pay for the pay period — not against a running balance left over from higher-priority allocations. A fixed-amount allocation (allocatedBy: 1) takes its exact dollar amount; a percentage allocation (allocatedBy: 2) takes that percentage of the full net pay.

order determines priority for when net pay isn't enough to cover every allocation for that period — lower numbers are funded first. It does not change how an individual allocation's amount is calculated.

If you create an allocation using an order value that's already in use, the existing allocation (and any after it) shifts back by one. For example, if allocations at order: 1 and order: 2 already exist and you create a new one at order: 1, the existing order: 1 allocation becomes order: 2, and the existing order: 2 allocation becomes order: 3. If the last allocation order is order: 3 and you try to create one with order: 100 it gets shifted down to the closest order so in this case it would became order: 4.

Auth

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

Option 1: Reference an existing bank account

Use this when a bank account has already been added for the employee through a separate endpoint, and you have its bankAccountId.

Endpoint

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/payallocations/account

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.

Required fields:

FieldTypeRequiredDescription
orderintegerYesPriority for this allocation. See "How allocations are calculated" above.
payMethodintegerYesHow this allocation is paid out. See Pay Method values below.
allocatedByintegerYesWhether amount is a flat dollar amount or a percentage. See Allocated By values below.
amountnumberYesThe dollar amount or percentage to allocate, depending on allocatedBy.
bankAccountIdintegerYesThe id of a bank account already added for this employee.

Pay Method values:

ValueMeaning
1Check
2Direct deposit

Allocated By values:

ValueMeaning
1Fixed amount — amount is a flat dollar amount
2Percentage — amount is a percentage of full net pay

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}/payallocations/account`;

const payload = {
  order: 1,
  payMethod: 2, // direct deposit
  allocatedBy: 1, // fixed amount
  amount: 300,
  bankAccountId: 319
};

async function createPayAllocation() {
  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());
}

createPayAllocation();
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/payallocations/account" \
  -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 '{
    "order": 1,
    "payMethod": 2,
    "allocatedBy": 1,
    "amount": 300,
    "bankAccountId": 319
  }' | jq .

Example response

{
  "id": 1899,
  "order": 7,
  "payMethod": 2,
  "allocatedBy": 1,
  "amount": 300,
  "accountNumber": "000123456791",
  "routingNumber": "133456789",
  "accountHolderName": "Account 2",
  "accountType": 2
}

id is the pay allocation's unique identifier.

Error response — invalid bankAccountId

{
  "status": 0,
  "code": "404",
  "errorCode": null,
  "message": "9/15/2026 - 12:14:53 PM : Record not found or invalid.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

Returned when bankAccountId doesn't match an existing bank account for this employee.

Option 2: Provide bank account details directly

Use this when the destination bank account hasn't been added for the employee yet — you send the account details along with the allocation in one call.

Endpoint

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

Required fields:

FieldTypeRequiredDescription
orderintegerYesPriority for this allocation. See "How allocations are calculated" above.
payMethodintegerYesHow this allocation is paid out. See Pay Method values above.
allocatedByintegerYesWhether amount is a flat dollar amount or a percentage. See Allocated By values above.
amountnumberYesThe dollar amount or percentage to allocate, depending on allocatedBy.
accountHolderNamestringYesName on the bank account.
accountTypeintegerYesThe account type.
routingNumberstringYesThe bank's routing number.
accountNumberstringYesThe bank account number.

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}/payallocations`;

const payload = {
  order: 2,
  payMethod: 2, // direct deposit
  allocatedBy: 2, // percentage
  amount: 20,
  accountHolderName: "Michael Brown",
  accountType: 2, // savings
  routingNumber: "071000505",
  accountNumber: "000123456792"
};

async function createPayAllocation() {
  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());
}

createPayAllocation();
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/payallocations" \
  -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 '{
    "order": 2,
    "payMethod": 2,
    "allocatedBy": 2,
    "amount": 20,
    "accountHolderName": "Michael Brown",
    "accountType": 2,
    "routingNumber": "071000505",
    "accountNumber": "000123456792"
  }' | jq .

Example response

{
  "id": 1900,
  "order": 8,
  "payMethod": 2,
  "allocatedBy": 2,
  "amount": 20,
  "accountNumber": "000123456792",
  "routingNumber": "071000505",
  "accountHolderName": "Michael Brown",
  "accountType": 2
}

Error response — invalid amount

{
  "status": 0,
  "code": "400",
  "errorCode": "WEP_BadRequest",
  "message": "9/15/2026 - 12:15:25 PM : SharedResource.AmountIsNotInRange.en-US",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

Returned when a single percentage-based allocation (allocatedBy: 2) has an amount over 100. Applies to both endpoints above.

Updated 38 minutes ago

Did this page help you?