Downloading Documents

Files in the Worklio API, such as employee documents and payroll reports, are not returned directly. Each file has a fileToken. To download a file, exchange its fileToken for a short-lived download link, then request the link.

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

Where to get a `fileToken`

Source	Where the `fileToken` is returned
Employee documents	The `fileToken` field in List employee documents and Upload a document.
Payroll reports	The `fileToken` field of each item in the `reports` array. See Payroll Reports.

Download flow

Call the file info endpoint with the fileToken. It returns a downloadToken and a downloadUri.
Request the downloadUri to get the file.

The downloadToken and downloadUri are short-lived. Do both calls back to back instead of storing them. A fileToken is specific to one file. Get a current one from the list or report endpoint instead of reusing an old one.

1. Get a download link

GET https://api.worklio.com/wep/files/{fileToken}/info

Parameter	Type	Required	Description
`fileToken`	string	Yes	The file's token. Path parameter.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const FILE_TOKEN = "o50Iv4rU05f4S-P9BFAbwWyxXyPqTL_RrxxUG3ViwNSZYUuMb7b55kHiElCXeA27GuqGJtjWuX-eubGHKYE70P4R17q992udvvvjcFc2aFNaDYaipnxDO";
const url = `https://api.worklio.com/wep/files/${FILE_TOKEN}/info`;

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

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

getDownloadInfo();

curl --request GET \
  --url "https://api.worklio.com/wep/files/$FILE_TOKEN/info" \
  --header "accept: application/json" \
  --header "api-version: 2.0" \
  --header "authorization: Bearer $API_KEY" \
  --header "x-api-version: 2.0"

Example response

{
  "downloadToken": "6vFtymsuYibYxqEzo8lko9GByuxeLQdXtf4-UaufkkibHmhjn_j_ilo0eiUFcHsmdtHJLQ-qSwk_DkRD36cymWlSKbnxI5NT_CIaADvtOwQJYHJ2C3w46Yw@@",
  "downloadUri": "https://api.worklio.com/wep/files/6vFtymsuYibYxqEzo8lko9GByuxeLQdXtf4-UaufkkibHmhjn_j_ilo0eiUFcHsmdtHJLQ-qSwk_DkRD36cymWlSKbnxI5NT_CIaADvtOwQJYHJ2C3w46Yw@@/download",
  "previewUri": "https://api.worklio.com/wep/files/6vFtymsuYibYxqEzo8lko9GByuxeLQdXtf4-UaufkkibHmhjn_j_ilo0eiUFcHsmdtHJLQ-qSwk_DkRD36cymWlSKbnxI5NT_CIaADvtOwQJYHJ2C3w46Yw@@/preview"
}

Field	Type	Description
`downloadToken`	string	Short-lived token for this download.
`downloadUri`	string	Full URL that returns the file. Use it as is.
`previewUri`	string	Opens the file in browser without downloading it.

2. Download the file

GET https://api.worklio.com/wep/files/{downloadToken}/download

Request the downloadUri from step 1. The response body is the file.

Putting it together

This function takes a fileToken and a path to save the file to. Choose a file extension that matches the document type.

require("dotenv").config();
const fs = require("fs");

const TOKEN = process.env.API_KEY;

const headers = {
  accept: "application/json",
  "api-version": "2.0",
  authorization: `Bearer ${TOKEN}`,
  "x-api-version": "2.0"
};

async function downloadFile(fileToken, outPath) {
  // 1. Exchange the fileToken for a short-lived download link
  const infoRes = await fetch(
    `https://api.worklio.com/wep/files/${fileToken}/info`,
    { method: "GET", headers }
  );
  if (!infoRes.ok) {
    throw new Error(`Could not get download link: ${infoRes.status}`);
  }
  const { downloadUri } = await infoRes.json();

  // 2. Download the file right away, while the downloadToken is still valid
  const fileRes = await fetch(downloadUri, { method: "GET", headers });
  if (!fileRes.ok) {
    throw new Error(`Download failed: ${fileRes.status}`);
  }

  fs.writeFileSync(outPath, Buffer.from(await fileRes.arrayBuffer()));
  console.log(`Saved ${outPath}`);
}

downloadFile(process.env.FILE_TOKEN, "W9-2026.pdf");

Error responses

Expired Token will result in 400 error Download token is expired.

{
  status: 0,
  code: '400',
  errorCode: 'WEP_BadRequest',
  message: '10/12/2026 - 1:59:53 PM : Download token is expired!',
  stackTrace: '',
  pagination: {
    pageNo: 0,
    pageSize: 0,
    totalRecords: 0,
    totalPages: 0,
    dataToken: ''
  },
  validationErrors: null
}

{
  status: 0,
  code: '400',
  errorCode: 'WEP_BadRequest',
  message: '10/12/2026 - 2:01:33 PM : Download token is invalid!',
  stackTrace: '',
  pagination: {
    pageNo: 0,
    pageSize: 0,
    totalRecords: 0,
    totalPages: 0,
    dataToken: ''
  },
  validationErrors: null
}

Where to get a fileToken