Payroll Reports

Every payroll run generates a set of reports (payroll register, cash requirements, direct deposit register, and others) once it's created. This page covers how to list the reports available for a payroll run and download one.

The run must be finalized before its reports are available — see Run Payroll. Reports aren't generated for a run that's still in progress.

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. RUN_ID is the runId returned when you start a payroll run.

Downloading a report is a three-call sequence:

1. Get the run's report list, which includes a fileToken per report.
2. Exchange the fileToken for a short-lived downloadToken.
3. Download the file with the downloadToken.

Because the downloadToken from step 2 is short-lived, do steps 2 and 3 back to back in the same request flow rather than storing the token for later — see the combined example below.

Get the payroll run's reports

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/history/overview

Returns a full overview of a finalized payroll run — pay period dates, totals, tax breakdown, and the reports array this page focuses on. (The rest of the overview response is out of scope for this page.)

reports fields

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const RUN_ID = 1002124; // a finalized payroll run's runId
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/payroll/${RUN_ID}/history/overview`;

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

getPayrollOverview();

curl -s "https://api.worklio.com/wep/companies/$CLIENT_ID/payroll/1002124/history/overview" \
  -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

{
  "periodStart": "2026-09-11",
  "periodEnd": "2026-09-17",
  "payDay": "2026-09-18",
  "totalGrossPay": 180000,
  "totalNetPay": 74243.06,
  "reports": [
    {
      "caption": "Cash Requirements",
      "description": "",
      "fileToken": "FDtDR0GnOcsIYc7FUqzZhYVbiG-q-f5ZyjNpQ3UFkhYukjLAyr0zo70Npil1J-yCUdtb1eYHiFeSjpCvJnymn2TDQq8UUkkdaBd-QtXRPRdHkjwq9rBbw",
      "reportType": "CashRequirements"
    },
    {
      "caption": "Payroll Register",
      "description": "",
      "fileToken": "o50Iv4rU05f4S-P9BFAbwWyxXyPqTL_RrxxUG3ViwNSZYUuMb7b55kHiElCXeA27GuqGJtjWuX-eubGHKYE70P4R17q992udvvvjcFc2aFNaDYaipnxDO",
      "reportType": "PayrollRegister"
    }
  ]
}

The full response also includes payStatements, eeAndERTaxes, dedsAndContribs, immediateTransactions and every other report you generate.

Report types

The following reportType values were returned for the payroll run used throughout this guide:

Download a report

Pass a report's fileToken to the download flow described in Downloading Documents. This example finds the Payroll Register in a run and saves it. downloadFile is the function defined on that page.

Reports are PDFs.

Notes

• fileToken values are specific to one payroll run and one report. Call the overview endpoint again to get current fileToken values instead of reusing old ones. They also change with each GET call.