Scope: accounting:payrolls.write https://api.alladdin.com/api/v2/salary-records

Creates a salary record (payroll) for an employee.
Provide the employee by name or code in employee_id — it is resolved automatically; if several employees match, the candidates are surfaced so the user can choose. Never fabricate an id.
The top-level accounting_account_id and the four lines (their accounts, tax keys and labels) come from the salary-record form data for that employee — read it, use its default_accounting_account_id as the top-level account (the result/counterpart account, NOT the salary expense one), and copy each default_lines entry verbatim, replacing only each amount with the value the user provides. When the employee's payroll_accounts is populated, it takes precedence over those defaults. Never invent an accounting account id and never ask the user for one — always resolve it from the form data. ALWAYS include all four lines. Deduction lines (tax, retention) are negative amounts: when the user states one as a positive number (e.g. "IRPF 150"), send it as -150. You MUST ask the user for the four amounts before creating — never leave a line at zero, never use a placeholder, and never create the record until you have a real amount for each line. Present the lines as a numbered list using each form line's EXACT label (do not paraphrase):
1. Salario
2. Total S.S.
3. Gasto S.S. Empresa
4. IRPF
Default the accrual date to today; if you ask the user, accept a plain "hoy"/"today" as the answer. Leave is_draft unset unless the user explicitly asks to finalize/post the record — the default already saves it as a draft.

Request body

object employee_id string required

The employee this salary record belongs to (must be active in the same account). Accepts the employee name or code — resolved automatically to the internal id.

date string<date> required

Accrual date of the salary record (ISO 8601, YYYY-MM-DD).

accounting_account_id string required

Top-level accounting account where the net payable is posted (result/counterpart account, e.g. "465 Remuneraciones pendientes de pago").

is_draft boolean optional

When true (the default), the record is saved as a draft and is NOT posted to the ledger. When false, it is finalized immediately.

default: true description string | null optional

On creation this field is ignored and left empty — the system always generates the localized default description. Do not set it.

tags[] string[] | null optional

Optional list of tags to attach to the record.

lines[] object[] | null optional

Payroll line breakdown: earning and deduction lines. A standard payroll includes all four line types — salary and companytax (positive), tax and retention (negative).

type string required

Line type. A standard payroll uses salary, tax, companytax and retention; see the enum for all supported values.

Enum: salary tax companytax retention extra result advance wage_garnishment pago_delegado_it salary_in_kind salary_in_kind_retention salary_in_kind_income amount object required

Line amount as a decimal string (use negative values for deductions, e.g. "-150.00"). Prefer the string form: it avoids floating-point precision loss. A plain JSON number is also accepted.

accounting_account_id string required

Accounting account for this line.

tax_key string | null optional

Optional tax key applied to this line.

description string | null optional

Line description shown as the concept label.

Request

import requests

url = "https://api.alladdin.com/api/v2/salary-records"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

payload = {
    "employee_id": "Pablo Díaz",
    "date": "2024-03-15",
    "accounting_account_id": "see the salary-record form data",
    "is_draft": true,
    "description": "March 2024 payroll",
    "tags": [
        "bonus",
        "q1"
    ],
    "lines": [
        {
            "type": "salary",
            "amount": "1500.00",
            "accounting_account_id": "see the salary-record form data",
            "tax_key": "e_salario",
            "description": "Salario"
        }
    ]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201 Salary record created application/json object id string

Error responses

400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 409 Accounting period is locked application/json object type string title string status integer detail string 429 Rate limit exceeded application/json

Next →Update a salary record →