List payslips
Scope: accounting:payrolls.read https://api.alladdin.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 Alladdin'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
cursor string optional
Pagination cursor returned by the previous response. Omit to start from the first page.
limit integer optional = 50
Maximum number of payslips to return per page. Defaults to 50, maximum 200.
employee_id string optional
Filter by employee. Accepts the employee name, resolved server-side to its identifier.
start_date string<date-time> optional
Accrual date lower bound (ISO 8601).
end_date string<date-time> optional
Accrual date upper bound (ISO 8601).
kind string optional
Filter by payslip kind.
"nomina_ordinaria" "gratificacion_no_cuantificable" "finiquito" "atrasos" is_draft boolean optional
Filter by draft state: true returns only unapproved payslips, false only approved ones. Omit to return both.
Request
import requests
url = "https://api.alladdin.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
{
"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
200 List of payslips application/json object items[] object[] id string
Unique identifier of the payslip
employee_id string | null
Identifier of the employee this payslip belongs to. Null when the employee has been deleted.
employee_name string
Snapshot of the employee's full name at the time the payslip was created
payslip_kind string
Kind of payslip: nomina_ordinaria (ordinary monthly payslip), gratificacion_no_cuantificable (non-quantifiable bonus regularisation), finiquito (final settlement) or atrasos (back pay for months already settled, typically a retroactive collective-agreement increase).
Enum: nomina_ordinaria gratificacion_no_cuantificable finiquito atrasos date string<date>
Accrual date of the payslip (ISO 8601)
period_start string<date> | null
First day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.
period_end string<date> | null
Last day of the liquidation period covered by the payslip. Null on payslips created before periods were stored.
total_days integer
Days paid in the liquidation period
description string
Free-form description of the payslip
tags[] string[]
List of tags attached to the payslip
accounting_account_id string | null
Accounting account where the payroll expense is posted
is_draft boolean
Whether the payslip is still a draft. A draft has not been approved and is not posted to the ledger.
net_salary string
Amount the employee receives (salario neto), as a decimal string. Equals the sum of earnings minus the sum of deductions.
total_company_cost string
Total cost for the company (gross salary plus employer contributions), as a decimal string.
payment_total string
Total amount already paid, as a decimal string
payment_pending string
Amount still pending payment, as a decimal string
payment_status string
Payment status of the payslip
Enum: PENDING PAID PARTIALLY_PAID cursor string | 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_more boolean
Whether more pages are available after this one
Error responses
400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 429 Rate limit exceeded application/json