GET

List payslips

Scope:accounting:payrolls.read

https://api.holded.com/api/v2/payslips

Returns payslips ordered by creation (newest first). Results are cursor-paginated: the response carries a `cursor` value and a `has_more` boolean. Pass the `cursor` to the next request to fetch the following page. A payslip (Spanish *nómina*) is the calculated payroll document produced by Holded's payroll engine for a liquidation period, with its own social-security and IRPF breakdown. It is NOT the same document as a salary record (*registro salarial*), which is the manually entered accounting record served by `/api/v2/salary-records`. This endpoint never returns salary records, and `/api/v2/salary-records` never returns payslips: pick the endpoint that matches the document the user actually named. Payslips only exist in accounts that create payroll through the Human Resources gem; an account without that gem cannot create new ones, but this endpoint keeps returning the payslips it already has. An empty list therefore means either no payslips in range or an account that never used payroll. The `start_date` / `end_date` filter applies to the accrual date, not the creation date and not the liquidation period.

Parameters

Query parameters

cursorstringoptional

Pagination cursor returned by the previous response. Omit to start from the first page.

limitintegeroptional= 50

Maximum number of payslips to return per page. Defaults to 50, maximum 200.

employee_idstringoptional

Filter by employee. Accepts the employee name, resolved server-side to its identifier.

start_datestring<date-time>optional

Accrual date lower bound (ISO 8601).

end_datestring<date-time>optional

Accrual date upper bound (ISO 8601).

kindstringoptional

Filter by payslip kind.

"nomina_ordinaria""gratificacion_no_cuantificable""finiquito"

is_draftbooleanoptional

Filter by draft state: `true` returns only unapproved payslips, `false` only approved ones. Omit to return both.

Request

python

import requests

url = "https://api.holded.com/api/v2/payslips?cursor=value&limit=50&employee_id=507f1f77bcf86cd799439012"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Responses

Response

json

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "employee_id": "507f1f77bcf86cd799439012",
      "employee_name": "Jane Doe",
      "payslip_kind": "nomina_ordinaria",
      "date": "2024-03-31",
      "period_start": "2024-03-01",
      "period_end": "2024-03-31",
      "total_days": 30,
      "description": "March 2024",
      "tags": [
        "office-madrid"
      ],
      "accounting_account_id": "507f1f77bcf86cd799439013",
      "is_draft": false,
      "net_salary": "1663.00",
      "total_company_cost": "2640.00",
      "payment_total": "1663.00",
      "payment_pending": "0.00",
      "payment_status": "PENDING"
    }
  ],
  "cursor": "string",
  "has_more": true
}

Success responses

200List of payslipsapplication/json

object

items[]object[]

idstring

Unique identifier of the payslip

employee_idstring | null

Identifier of the employee this payslip belongs to. Null when the employee has been deleted.

employee_namestring

Snapshot of the employee's full name at the time the payslip was created

payslip_kindstring

Kind of payslip: `nomina_ordinaria` (ordinary monthly payslip), `gratificacion_no_cuantificable` (non-quantifiable bonus regularisation) or `finiquito` (final settlement).

Enum:nomina_ordinariagratificacion_no_cuantificablefiniquitoatrasos

datestring<date>

Accrual date of the payslip (ISO 8601)

period_startstring<date> | null

First day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.

period_endstring<date> | null

Last day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.

total_daysinteger

Days paid in the liquidation period

descriptionstring

Free-form description of the payslip

tags[]string[]

List of tags attached to the payslip

accounting_account_idstring | null

Accounting account where the payroll expense is posted

is_draftboolean

Whether the payslip is still a draft. A draft has not been approved and is not posted to the ledger.

net_salarystring

Amount the employee receives (salario neto), as a decimal string. Equals the sum of `earnings` minus the sum of `deductions`.

total_company_coststring

Total cost for the company (gross salary plus employer contributions), as a decimal string.

payment_totalstring

Total amount already paid, as a decimal string

payment_pendingstring

Amount still pending payment, as a decimal string

payment_statusstring

Payment status of the payslip

Enum:PENDINGPAIDPARTIALLY_PAID

cursorstring | null

Opaque cursor pointing to the next page. Pass this value as the `cursor` query parameter in the next request. Null when there is no next page.

has_moreboolean

Whether more pages are available after this one

Error responses

400Bad requestapplication/json

401Invalid or missing API keyapplication/json

403Insufficient permissionsapplication/json

429Rate limit exceededapplication/json