> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Payrolls (v2)

> Payrolls with branch: query by branch and assign a payroll's branch

**Required permission:** `hr.payrolls` (query) · `hr.payrolls.write` ([assign branch](#assign-branch))

Reads are the same as in [v1](https://docs.filexpress.app/en/docs/api/rrhh/planillas.md) (only **processed** or **paid** payrolls) and add `branch_id` to each payroll. Branch assignment only exists in v2 (`https://api.filexpress.app/api/external/v2`).

> [!NOTE]
>
> **Payrolls by branch** is a business HR setting (HR → Payrolls). With the setting on, each payroll belongs to a branch and the per-branch indicators (for example, **Net profit** on the home page) only count that branch's payrolls. With the setting off, `branch_id` can be `null` and the payroll counts for the whole business.

## List payrolls

```http theme={null}
GET /hr/payrolls?start_date=2026-10-01&end_date=2026-10-31&branch_id=7c1d4e2a-9b3f-4a6e-8d5c-0f2a1b3c4d5e
```

| Parameter | Required | Description |
| - | - | - |
| `start_date`, `end_date` | Yes | Payrolls whose period overlaps the range (maximum 370 days). |
| `status` | No | `processed` or `paid`. |
| `branch_id` | No | Only the payrolls of that branch. |

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "5f0e8d1a-3c2b-4a7e-9d4f-6b1c2a3e4f50",
      "name": "Primera quincena octubre 2026",
      "start_date": "2026-10-01",
      "end_date": "2026-10-15",
      "status": "paid",
      "employees": 12,
      "total_net_amount": 4820.35,
      "branch_id": "7c1d4e2a-9b3f-4a6e-8d5c-0f2a1b3c4d5e",
      "cost_center_id": null
    }
  ]
}
```

## Get a payroll

```http theme={null}
GET /hr/payrolls/{id}
```

Same response as in [v1](https://docs.filexpress.app/en/docs/api/rrhh/planillas.md#payroll-detail), with `branch_id` at the payroll level.

## Assign branch

```http theme={null}
PUT /hr/payrolls/{id}/branch
```

```json theme={null}
{ "branch_id": "7c1d4e2a-9b3f-4a6e-8d5c-0f2a1b3c4d5e" }
```

Send `branch_id: null` to leave the payroll as business-wide (only if the business does not require a branch).

```json theme={null}
{
  "status": true,
  "data": { "id": "5f0e8d1a-3c2b-4a7e-9d4f-6b1c2a3e4f50", "branch_id": "7c1d4e2a-9b3f-4a6e-8d5c-0f2a1b3c4d5e" }
}
```

| Response | `code` | When |
| - | - | - |
| `404` | `payroll_not_found` | The payroll does not exist or belongs to another business. |
| `422` | `validation_error` | The `branch_id` field is missing (it must be sent, even if `null`). |
| `422` | `invalid_branch` | The branch does not belong to the business, or the business requires a branch and you sent `null`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.