Payroll Policy

A payroll policy is a company's pay schedule. It sets how often employees are paid (weekly, biweekly, semimonthly, or monthly), the dates of the first pay period and pay day, and whether the pay day moves when it falls on a weekend or holiday. From these settings Worklio works out each upcoming pay period, pay day, and processing deadline, and returns them on the policy in the next* fields.

A company can have more than one payroll policy. Other endpoints refer to a policy by its id, passed as POLICY_ID — for example, Payroll History returns the payroll runs for one policy. If you include a payrollPolicy object when you create the company, Worklio creates the company's first policy for you, named DEFAULT. Use the endpoints on this page to list that policy, add more, rename them, turn autoRun on or off, or delete them.

Requires a bearer access token (see How to Get API Access). CLIENT_ID is the company identifier returned as id when you create the company.

Endpoints overview

Method	Name	Endpoint
GET	List Payroll Policies	`https://api.worklio.com/wep/companies/{CLIENT_ID}/policies`
GET	Get Payroll Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}`
POST	Create Payroll Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/policies`
PATCH	Update Payroll Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}`
DELETE	Delete Payroll Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}`

POLICY_ID is the policy identifier returned as id when you create a policy. You can also find it in the payrollPolicies array returned by Get a company.

The payroll policy object

Every endpoint that returns a policy uses this shape. List returns an array of these objects; Get, Create, and Update return a single object.

Field	Type	Description
`id`	integer	Unique identifier of the payroll policy.
`companyId`	integer	The company's `id`. Matches `CLIENT_ID` in the request path.
`name`	string	The policy's name, e.g. `"DEFAULT"`.
`frequency`	integer (enum)	How often employees are paid. Same value as `payFrequency` in the create request. See Pay frequency values.
`nextPeriodStart`	string (date, `YYYY-MM-DD`)	First day of the next pay period.
`nextPeriodEnd`	string (date, `YYYY-MM-DD`)	Last day of the next pay period.
`nextNumInMonth`	integer	Position of the next pay period within its month.
`nextPayDay`	string (date, `YYYY-MM-DD`)	The date employees are paid for the next pay period.
`nextRunDay`	string (date, `YYYY-MM-DD`)	The date the next payroll is scheduled to run.
`daysToProcessPayments`	integer	Number of days allowed to process payments before the pay day.
`deadline`	string (date-time, UTC)	Deadline for the next payroll.
`autoRun`	boolean	Whether payroll runs for this policy start automatically. `false` for a new policy. Can be changed with Update.
`initialSetup`	object	The schedule settings the policy was created with. See below.

`initialSetup` object

Field	Type	Description
`payFrequency`	integer (enum)	Pay frequency the policy was created with. See Pay frequency values.
`firstPayPeriodEndDate`	string (date, `YYYY-MM-DD`)	End date of the first pay period.
`firstPayDate`	string (date, `YYYY-MM-DD`)	Date employees are paid for the first pay period.
`movePayDayOnHolidaysAndWeekends`	integer (enum)	How the pay day moves when it falls on a weekend or holiday. See Pay day adjustment values.
`autoRun`	boolean	Payroll will be started and processed automatically
`lastDayOfMonth`	boolean	When true, monthly / semi-monthly period ends use the last calendar day of the month.

Pay frequency values

Value	Name
1	Weekly
2	BiWeekly
3	SemiMonthly
4	Monthly

Pay day adjustment values

Value	Meaning
0	Move the pay day to after the holiday or weekend.
1	Move the pay day to before the holiday or weekend.

List Payroll Policies

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/policies

Example request

require("dotenv").config();

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

async function listPayrollPolicies() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

listPayrollPolicies();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/policies" \
  -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" | jq .

Example response

[
  {
    "id": 1084,
    "companyId": 1028,
    "name": "DEFAULT",
    "frequency": 1,
    "nextPeriodStart": "2026-09-18",
    "nextPeriodEnd": "2026-09-24",
    "nextNumInMonth": 4,
    "nextPayDay": "2026-09-25",
    "nextRunDay": "2026-09-24",
    "daysToProcessPayments": 4,
    "deadline": "2026-09-21T21:00:00Z",
    "autoRun": false,
    "initialSetup": {
      "payFrequency": 1,
      "firstPayPeriodEndDate": "2026-09-10",
      "firstPayDate": "2026-09-12",
      "movePayDayOnHolidaysAndWeekends": 1,
      "autoRun": false,
      "lastDayOfMonth": false
    }
  }
]

Get Payroll Policy

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}

Returns a single payroll policy by id. The response is one policy object, not an array.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const POLICY_ID = 1084; // a payroll policy's id, from List Payroll Policies
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/policies/${POLICY_ID}`;

async function getPayrollPolicy() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

getPayrollPolicy();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/policies/1084" \
  -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" | jq .

Example response

{
  "id": 1084,
  "companyId": 1028,
  "name": "DEFAULT",
  "frequency": 1,
  "nextPeriodStart": "2026-09-18",
  "nextPeriodEnd": "2026-09-24",
  "nextNumInMonth": 4,
  "nextPayDay": "2026-09-25",
  "nextRunDay": "2026-09-24",
  "daysToProcessPayments": 4,
  "deadline": "2026-09-21T21:00:00Z",
  "autoRun": false,
  "initialSetup": {
    "payFrequency": 1,
    "firstPayPeriodEndDate": "2026-09-10",
    "firstPayDate": "2026-09-12",
    "movePayDayOnHolidaysAndWeekends": 1,
    "autoRun": false,
    "lastDayOfMonth": false
  }
}

Create Payroll Policy

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/policies

Creates a payroll policy for the company and returns it, including the calculated next* schedule fields.

Request fields

Field	Type	Required	Description
`name`	string	No	Name of the policy.
`payFrequency`	integer (enum)	Yes	How often employees are paid. See Pay frequency values.
`firstPayPeriodEndDate`	string (date, `YYYY-MM-DD`)	Yes	End date of the first pay period.
`firstPayDate`	string (date, `YYYY-MM-DD`)	Yes	Date employees are paid for the first pay period.
`movePayDayOnHolidaysAndWeekends`	integer (enum)	Yes	How the pay day moves when it falls on a weekend or holiday. See Pay day adjustment values.
`lastDayOfMonth`	bool	No	When true monthly/semi-monthly pay periods use last calendar day of the month
`autoRun`	bool	No	Payroll will start and be processed automatically.

Example request

The example creates a monthly policy. The first pay period ends on October 31, 2026, and employees are paid for it on Monday, November 2, 2026.

require("dotenv").config();

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

const payload = {
  name: "Monthly Salaried",
  payFrequency: 4, // Monthly
  firstPayPeriodEndDate: "2026-10-31",
  firstPayDate: "2026-11-02",
  movePayDayOnHolidaysAndWeekends: 1 // 0 = after, 1 = before
};

async function createPayrollPolicy() {
  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);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

createPayrollPolicy();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/policies" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/merge-patch+json" \
  -H "x-api-version: 2.0" \
  -d '{
    "name": "Monthly Salaried",
    "payFrequency": 4,
    "firstPayPeriodEndDate": "2026-10-31",
    "firstPayDate": "2026-11-02",
    "movePayDayOnHolidaysAndWeekends": 1
  }' | jq .

Example response

{
  "id": 1122,
  "companyId": 1028,
  "name": "Monthly Salaried",
  "frequency": 4,
  "nextPeriodStart": "2026-10-01",
  "nextPeriodEnd": "2026-10-31",
  "nextNumInMonth": 1,
  "nextPayDay": "2026-11-02",
  "nextRunDay": "2026-10-30",
  "daysToProcessPayments": 4,
  "deadline": "2026-10-29T21:00:00Z",
  "autoRun": false,
  "initialSetup": {
    "payFrequency": 4,
    "firstPayPeriodEndDate": "2026-10-31",
    "firstPayDate": "2026-11-02",
    "movePayDayOnHolidaysAndWeekends": 1,
    "autoRun": false,
    "lastDayOfMonth": false
  }
}

id is the new policy's unique identifier. Save it — it is the POLICY_ID for the Get, Update, and Delete calls below.

In this example, firstPayPeriodEndDate of 2026-10-31 on a monthly policy gives a first pay period of 2026-10-01 to 2026-10-31, shown in nextPeriodStart and nextPeriodEnd.

Update Payroll Policy

PATCH https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}

Updates a payroll policy and returns the updated policy. Send only the fields you want to change; fields you leave out keep their current values.

Only name and autoRun can be changed. The pay frequency and the schedule dates set at creation can't be updated.

Request fields

Field	Type	Required	Description
`name`	string	No	New name for the policy.
`autoRun`	boolean	No	Whether payroll runs for this policy start automatically.

If the request body includes any other field, the API ignores it.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const POLICY_ID = 1122; // the id returned by Create Payroll Policy
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/policies/${POLICY_ID}`;

const payload = {
  name: "Monthly Office Staff",
  autoRun: true
};

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

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

updatePayrollPolicy();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/policies" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/merge-patch+json" \
  -H "x-api-version: 2.0" \
  -d '{
    "name": "Monthly Salaried",
    "payFrequency": 4,
    "firstPayPeriodEndDate": "2026-10-31",
    "firstPayDate": "2026-11-02",
    "movePayDayOnHolidaysAndWeekends": 1
  }' | jq .

Example response

{
  "id": 1122,
  "companyId": 1028,
  "name": "Monthly Office Staff",
  "frequency": 4,
  "nextPeriodStart": "2026-10-01",
  "nextPeriodEnd": "2026-10-31",
  "nextNumInMonth": 1,
  "nextPayDay": "2026-11-02",
  "nextRunDay": "2026-10-30",
  "daysToProcessPayments": 4,
  "deadline": "2026-10-29T21:00:00Z",
  "autoRun": true,
  "initialSetup": {
    "payFrequency": 4,
    "firstPayPeriodEndDate": "2026-10-31",
    "firstPayDate": "2026-11-02",
    "movePayDayOnHolidaysAndWeekends": 1,
    "autoRun": true,
    "lastDayOfMonth": false
  }
}

name and autoRun changed. initialSetup.autoRun changed to true with autoRun; every other field is unchanged.

Delete Payroll Policy

DELETE https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}

Deletes a payroll policy. This endpoint takes no query parameters and no request body.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const POLICY_ID = 1122; // the id of the policy to delete
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/policies/${POLICY_ID}`;

async function deletePayrollPolicy() {
  const response = await fetch(url, {
    method: "DELETE",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "x-api-version": "2.0"
    },
  });

  // A successful delete returns 204 with no body, so there is nothing to parse.
  console.log(response.status);
}

deletePayrollPolicy();

curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "https://api.worklio.com/wep/companies/$CLIENT_ID/policies/1122" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "x-api-version: 2.0"

Example response

204 No Content

A successful delete returns 204 with no response body. Don't parse the body of a 204 response as JSON.

You can't delete the company's DEFAULT policy, or a policy that has employees assigned to it.

Notes

The payrollPolicies array on the company object returned by Get a company is a summary: id, companyId, name, frequency, autoRun, and initialSetup. It doesn't include the next* fields, daysToProcessPayments, or deadline. Use List or Get Payroll Policy to read the full schedule.
The next* fields, daysToProcessPayments, and deadline are calculated by Worklio from the policy's schedule settings.
These endpoints manage payroll policies only. Time off policies are a separate resource — see Time Off Policies.

Endpoints overview

The payroll policy object

initialSetup object

Pay frequency values

Pay day adjustment values

List Payroll Policies

Example request

Example response

Get Payroll Policy

Example request

Example response

Create Payroll Policy

Request fields

Example request

Example response

Update Payroll Policy

Request fields

Example request

Example response

Delete Payroll Policy

Example request

Example response

Notes

`initialSetup` object