---
updatedAt: 2026-10-26T09:12:51.000Z
agentTools:
  projectIndex: https://apidocs.worklio.com/llms.txt
---

# Run Payroll

Runs a payroll for a company. This is the last step of the core integration flow — after you've [created a company](https://apidocs.worklio.com/docs/create-a-company) and [added employees](https://apidocs.worklio.com/docs/create-an-employee) — and it's a three-call sequence: start the run, advance it, then finalize it.

Requires a bearer access token (see [How to Get API Access](https://apidocs.worklio.com/docs/getting-an-api-access)). `CLIENT_ID` is the company identifier returned as `id` when you [create the company](https://apidocs.worklio.com/docs/create-a-company).

## 1. Start a payroll run

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

No request body is required.

### Example request

```javascript Node.js
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}/payroll`;

async function runPayroll() {
  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"
    },
  });

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

runPayroll();
```
```curl cURL
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/payroll" \
  -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 .
```
```python
import os

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll"


def run_payroll():
    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
    )

    print(response.status_code)
    print(response.text)

    return response


if __name__ == "__main__":
    run_payroll()

```

### Example response

```json 200 Response
{
  "companyId": 1031,
  "runId": 1002109,
  "payrollType": 0,
  "startedOn": "2026-09-11",
  "payDay": "2026-09-25",
  "periodStart": "2026-09-19",
  "periodEnd": "2026-09-25",
  "daysToProcessPayments": 4,
  "deadline": "2026-09-21T21:00:00Z",
  "currentUIStep": 0,
  "currentProcStep": 501,
  "currentProcStepDesc": "Payroll Engine Activated",
  "currentProcStepProgress": 0,
  "currentProcStepStatus": 1,
  "direction": 0,
  "isPayrollBlocked": false,
  "canUserOverride": false,
  "errors": [],
  "warnings": []
}
```

`runId` identifies this payroll run — save it, you'll need it for the `next` and `finalize` calls below.

Calling this endpoint again while a run is already in progress doesn't start a second run — it returns the same run state shown above.

## 2. Advance the payroll run

```
POST https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{runId}/next
```

`runId` is the id returned by the start call above.

Call this endpoint to advance the run to its next processing step. Once there's nothing left to advance automatically, it responds with an error telling you to finalize instead of advance further — see the example below.

### Example request

```javascript Node.js
require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const RUN_ID = 1002109; // from the runId returned by the start call
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/payroll/${RUN_ID}/next`;

async function advancePayroll() {
  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"
    },
  });

  console.log(response.status);
  console.log(await response.text());
}

advancePayroll();
```
```curl
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/payroll/$RUN_ID/next" \
  -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 .
```
```python
import os

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
RUN_ID = 1002109 
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/next"


def advancePayroll():
    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
    )

    print(response.status_code)
    print(response.text)

    return response


if __name__ == "__main__":
    advancePayroll()

```

### Example response

```json 200 Response
{
  "companyId": 1031,
  "runId": 1002109,
  "payrollType": 0,
  "startedOn": "2026-09-11",
  "payDay": "2026-09-25",
  "periodStart": "2026-09-19",
  "periodEnd": "2026-09-25",
  "daysToProcessPayments": 4,
  "deadline": "2026-09-21T21:00:00Z",
  "currentUIStep": 0,
  "currentProcStep": 701,
  "skipUISteps": [],
  "currentProcStepDesc": "Crunching time entry data …",
  "currentProcStepProgress": 0,
  "currentProcStepStatus": 1,
  "direction": 0,
  "isPayrollBlocked": false,
  "canUserOverride": false,
  "errors": [],
  "warnings": []
}
```
```json 500 Response — no more steps to advance
{
  "status": 0,
  "code": "500",
  "errorCode": null,
  "message": "9/11/2026 - 1:14:57 PM : Missing localization for key: Worklio.Business.WEP.Logic.PayrollLogic.Next step operation is not allowed.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}
```

<Callout icon="🚧" theme="warn">
  ### The message text above ("Missing localization for key: ...") is what the API actually returns — it's a broken/untranslated error string, not a copy-paste mistake in this guide. Treat the HTTP 500 plus this message as the signal that the run has no more steps to advance and is ready to finalize.
</Callout>

## 3. Finalize the payroll run

```
POST https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{runId}/finalize
```

Call this once `next` (above) tells you there are no more steps to advance. This is the last call in the sequence — it finalizes the run.

### Example request

```javascript Node.js
require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const RUN_ID = 1002109; // from the runId returned by the start call
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/payroll/${RUN_ID}/finalize`;

async function finalizePayroll() {
  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"
    },
  });

  console.log(response.status);
  console.log(await response.text());
}

finalizePayroll();
```
```curl
curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/payroll/$RUN_ID/finalize" \
  -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 .
```
```python
import os

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
RUN_ID = 1002109 
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/payroll/{RUN_ID}/finalize"


def finalizePayroll():
    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
    )

    print(response.status_code)
    print(response.text)

    return response


if __name__ == "__main__":
    finalizePayroll()

```

### Example response

```json 204 Response
No body
```