Get a payslip
Scope: accounting:payrolls.read https://api.alladdin.com/api/v2/payslips/{payslipId}
Returns a single payslip with the breakdown the payroll engine computed for it: earning lines, deductions, employer contributions, the contribution bases and the net the employee receives.
A payslip (Spanish nómina) is NOT a salary record (registro salarial), which is served by /api/v2/salary-records. Ids of both look identical, so asking this endpoint for a salary-record id returns 404 naming the resource that does serve it.
Money and rates are decimal strings. Percentages are expressed as the number, so "12.50" means 12.5%.
Parameters
Path parameters
payslipId string required
Payslip ID (24-character hexadecimal ObjectId)
Request
import requests
url = "https://api.alladdin.com/api/v2/payslips/507f1f77bcf86cd799439011"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"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",
"is_ex_employee": false,
"irpf_rate": "12.50",
"extra_payments_prorata": "0.00",
"bases": [
{
"concept": "cotizacion_contingencias_comunes",
"amount": "2000.00"
}
],
"earnings": [
{
"name": "Salario base",
"payroll_item_id": "earning.salario_base",
"units": "30.00",
"price": "50.00",
"amount": "1500.00",
"bases": [
"cotizacion_contingencias_comunes"
],
"is_remuneration": true,
"is_paid_by_company": true
}
],
"deductions": [
{
"type": "contribution",
"concept": "contingencias_comunes",
"payroll_item_id": "deduction.anticipo_semanal",
"name": "Anticipo",
"units": "string",
"price": "string",
"percentage": "4.70",
"amount": "94.00"
}
],
"company_contributions": [
{
"concept": "contingencias_comunes",
"name": "Contingencias comunes",
"base": "2000.00",
"percentage": "23.60",
"amount": "472.00"
}
],
"payments": [
{
"id": "507f1f77bcf86cd799439011",
"amount": "1450.00",
"date": "2026-02-01",
"bank_account_id": "507f1f77bcf86cd799439012"
}
]
}Success responses
200 Payslip found application/json 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 is_ex_employee boolean
Whether the employee has since left the company
irpf_rate string
Income tax rate applied, as a decimal string percentage (e.g. "12.50" means 12.5%)
extra_payments_prorata string
Share of the extra payments (pagas extra) accrued in this period, as a decimal string
bases[] object[]
Contribution and tax bases the payslip was computed on, one row per base. On a retroactive receipt (gratificacion_no_cuantificable or atrasos) they come from the bases the employee has accumulated in the months the amount accrued in, not from the lines in this payslip, so a line can feed one base while another still carries an amount.
concept string
Base identifier, the same values used by earnings[].bases
Enum: cotizacion_contingencias_comunes cotizacion_at_ep tributacion_irpf amount string
Base amount, as a decimal string
earnings[] object[]
Earning lines (percepciones). amount is the line total; units and price are only set on lines computed from a quantity.
name string
Concept name as stored on the payslip
payroll_item_id string | null
Opaque identifier of the payroll concept: treat it as a string and do not parse it. Concepts from the Alladdin catalogue use a <type>.<id> key such as earning.salario_base, and concepts an account creates are usually 24-character ObjectIds, but neither shape is guaranteed and neither tells you which of the two it is.
units string | null
Units the line is computed from, as a decimal string
price string | null
Amount per unit, as a decimal string
amount string
Line total, as a decimal string
bases[] string[]
Contribution and tax bases this line feeds
is_remuneration boolean
Whether the line is remuneration (percepción salarial)
is_paid_by_company boolean
Whether the company pays this line, as opposed to social security
deductions[] object[]
Deduction lines. Every amount is a positive magnitude to subtract, so net_salary equals the sum of earnings minus the sum of this array. type tells them apart: discount is a deduction entered on the payslip, contribution is an employee social-security contribution and retention is the income tax withheld. On a retroactive receipt (gratificacion_no_cuantificable or atrasos) an amount is the difference against what the employee already contributed in the months the amount accrued in, so it may not equal base times percentage.
type string
Deduction family
Enum: discount contribution retention concept string | null
Stable concept key. Set on contribution and retention lines, null on discount lines, which carry payroll_item_id instead.
payroll_item_id string | null
Opaque identifier of the payroll concept, set on discount lines: treat it as a string and do not parse it. It may be a <type>.<id> catalogue key or a 24-character ObjectId, and the shape is not part of the contract.
name string | null
Human-readable concept name in the account language. Null when the concept has no label available.
units string | null
Units the line is computed from, as a decimal string
price string | null
Amount per unit, as a decimal string
percentage string | null
Rate applied, as a decimal string percentage. Null when the domain exposes no rate for the concept.
amount string
Deducted amount as a positive decimal string
company_contributions[] object[]
Employer social-security contributions, one row per concept. Every row carries its own amount, so the array sums with no double counting.
concept string
Stable contribution concept key
Enum: contingencias_comunes mei accidentes_de_trabajo_y_enfermedad_profesional desempleo fogasa formacion_profesional cotizacion_solidaridad name string | null
Human-readable concept name in the account language. Null when the concept has no label available.
base string | null
Base the contribution is computed on, as a decimal string
percentage string | null
Rate applied, as a decimal string percentage. Null when the domain exposes no rate for the concept.
amount string
Contribution amount, as a decimal string
payments[] object[]
Payments registered against this payslip. Empty when nothing has been paid yet. id is the only place a payment id is exposed, and it is what DELETE /api/v2/payslips/{payslipId}/payments/{paymentId} takes. The order of this array is not part of the contract: identify a payment by its amount and date, never by its position.
id string
Payment identifier (24-character hexadecimal ObjectId)
amount string
Amount paid, as a decimal string
date string<date>
Payment date
bank_account_id string | null
Treasury account the payment is tied to. Null when the payment was registered without one.
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Payslip not found application/json 429 Rate limit exceeded application/json