Payroll History

Returns the list of payroll runs for a payroll policy, one entry per run, with the run's pay period, pay day, and summary totals. Use it to find the runId of a past run, or to show a payroll history table in your own application. To get the full detail of one run, or to download its reports, pass its runId to Payroll Reports.

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

Endpoint

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

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`, as returned when you create the company. Path parameter.
`POLICY_ID`	integer	Yes	The payroll policy's `id`. Find it in the `payrollPolicies` array returned by Get a company. A company can have more than one payroll policy; this endpoint returns the runs for the one policy you pass. Path parameter. You can also get it by calling`GET /wep/companies/{companyId}/policies`
`Take`	integer (int32)	No	How many items to return. Query parameter.
`Skip`	integer (int32)	No	How many items to skip. Defaults to `0`. Query parameter.

No request body is required.

Paging through the history

Use Take and Skip together to page through the list. For example, to get the first 10 runs, then the next 10:

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}/history?Take=10&Skip=0
GET https://api.worklio.com/wep/companies/{CLIENT_ID}/policies/{POLICY_ID}/history?Take=10&Skip=10

The response is a plain array and doesn't include a total count. Keep increasing Skip by Take until a call returns fewer than Take items.

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 the company's payrollPolicies array
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/policies/${POLICY_ID}/history`;

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

getPayrollHistory();

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

[
  {
    "runId": 1002108,
    "policyId": 1087,
    "policyName": "DEFAULT",
    "payrollType": 0,
    "payDay": "2026-09-18",
    "periodStart": "2026-09-12",
    "periodEnd": "2026-09-18",
    "startedOn": "2026-09-11",
    "totalChecksAmount": 0,
    "printedChecksCount": 0,
    "totalEarnings": 37195.62,
    "totalAmount": 96885,
    "totalEETaxes": 52804.38,
    "totalERTaxes": 20404.72,
    "totalDeductions": 0,
    "autoStarted": false
  },
  {
    "runId": 1002107,
    "policyId": 1087,
    "policyName": "DEFAULT",
    "payrollType": 0,
    "payDay": "2026-09-11",
    "periodStart": "2026-09-05",
    "periodEnd": "2026-09-11",
    "startedOn": "2026-09-11",
    "totalChecksAmount": 0,
    "printedChecksCount": 0,
    "totalEarnings": 9974.38,
    "totalAmount": 24980.45,
    "totalEETaxes": 12525.62,
    "totalERTaxes": 5860.16,
    "totalDeductions": 0,
    "autoStarted": false
  }
]

The response is an array with one object per payroll run.

Response fields

Field	Type	Description
`runId`	integer	Unique identifier of the payroll run. Use it with Payroll Reports to get the run's overview and download its reports.
`policyId`	integer	The payroll policy's `id`. Matches `POLICY_ID` in the request path.
`policyName`	string	The payroll policy's name, e.g. `"DEFAULT"`.
`payrollType`	integer (enum)	The type of payroll run. `0` is a regular scheduled run, `2` is an off-cycle run. See Payroll Types for all values.
`payDay`	string (date, `YYYY-MM-DD`)	The date employees are paid for the run.
`periodStart`	string (date, `YYYY-MM-DD`)	First day of the run's pay period.
`periodEnd`	string (date, `YYYY-MM-DD`)	Last day of the run's pay period.
`startedOn`	string (date, `YYYY-MM-DD`)	The date the run was started.
`totalChecksAmount`	number	Total amount of the run's checks.
`printedChecksCount`	integer	Number of the run's checks that have been printed.
`totalEarnings`	number	Total earnings for the run.
`totalAmount`	number	Total amount for the run.
`totalEETaxes`	number	Total employee taxes for the run.
`totalERTaxes`	number	Total employer taxes for the run.
`totalDeductions`	number	Total deductions for the run.
`autoStarted`	boolean	Whether the run was started automatically.

Notes

The example response above was returned without Take or Skip.
Each entry belongs to one payroll policy. If the company has several payroll policies, call this endpoint once per policy.
A run can be returned with all totals at 0, as the second entry in the example above shows.
The response doesn't include per-employee detail or the run's reports. Use the runId with Payroll Reports for those.