Snapbooks logo Snapbooks Developer

Payroll Reports

The payroll reports API provides aggregated views of payroll data. These endpoints are read-only and return calculated reports based on posted payroll runs.

Endpoints

Payroll Run Summary

GET /api/v2/payroll/runs/{run_id}/summary

Returns a detailed summary of a specific payroll run, broken down by employee.

Response

{
  "document_id": 1,
  "uploaded_file_id": 456,
  "period_from": "2024-03-01",
  "period_to": "2024-03-31",
  "payment_date": "2024-03-25",
  "is_draft": false,
  "total_gross": "45000.00",
  "total_deductions": "12500.00",
  "total_net": "32500.00",
  "total_employer_costs": "6345.00",
  "total_cost": "51345.00",
  "employees": [
    {
      "bp_id": 56,
      "name": "Ola Nordmann",
      "gross_pay": "45000.00",
      "total_deductions": "12500.00",
      "net_pay": "32500.00",
      "employer_costs": "6345.00",
      "items": [
        {
          "item_type_code": "FAST_LONN",
          "description": "Fastlønn",
          "category": "EARNING",
          "quantity": null,
          "rate": null,
          "amount": 45000.0
        },
        {
          "item_type_code": "SKATTETREKK",
          "description": "Skattetrekk",
          "category": "DEDUCTION",
          "quantity": null,
          "rate": null,
          "amount": -12500.0
        }
      ]
    }
  ]
}

Year-to-Date Report

GET /api/v2/payroll/reports/ytd

Returns year-to-date payroll totals aggregated from all posted runs in the given year.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes The client account ID
year integer Yes The reporting year

Response

{
  "year": 2024,
  "run_count": 3,
  "total_gross": "135000.00",
  "total_deductions": "37500.00",
  "total_net": "97500.00",
  "total_employer_costs": "19035.00",
  "total_cost": "154035.00",
  "item_types": [
    {
      "code": "FAST_LONN",
      "name": "Fastlønn",
      "category": "EARNING",
      "total_amount": "135000.00",
      "run_count": 3
    }
  ],
  "employees": [
    {
      "bp_id": 56,
      "name": "Ola Nordmann",
      "total_gross": "135000.00",
      "total_deductions": "37500.00",
      "total_net": "97500.00",
      "total_employer_costs": "19035.00"
    }
  ]
}

Vacation Pay Report

GET /api/v2/payroll/reports/vacation-pay

Returns vacation pay (feriepenger) accrual and payout data per employee.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes The client account ID
year integer Yes The reporting year

Response

{
  "year": 2024,
  "total_basis": "540000.00",
  "total_accrued": "64800.00",
  "total_paid_out": "0.00",
  "total_balance": "64800.00",
  "employees": [
    {
      "bp_id": 56,
      "name": "Ola Nordmann",
      "vacation_pay_basis": "540000.00",
      "accrued": "64800.00",
      "paid_out": "0.00",
      "balance": "64800.00"
    }
  ]
}

Unallocated Vacation Pay Liability

GET /api/v2/payroll/reports/vacation-pay/unallocated-liability

Returns the company-level vacation pay (feriepenger) liability on account 2940 that is not attributed to any employee.

This is the portion of the 2940 balance posted without a business partner dimension — typically an opening balance carried in from a previous accounting system. A vacation payout run only pays out balances that are dimensioned per employee, so this unallocated amount is not paid out until it is re-booked per employee. Use this endpoint to surface any such residual liability that needs to be reallocated.

The liability is measured as of 31 December of the year before the requested holiday year (ferieaar), since vacation pay accrued in one year is paid out the following year.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes The client account ID
ferieaar integer Yes The holiday year (feriepengeår) to report for. The liability is measured as of 31 December of ferieaar - 1

Response

{
  "ferieaar": 2024,
  "unallocated_liability": 12000.0
}
Field Type Description
ferieaar integer The holiday year that was requested
unallocated_liability number (decimal) The 2940 liability with no business partner dimension, as of 31 December of ferieaar - 1. 0 when everything is already allocated per employee

Employer Tax Report

GET /api/v2/payroll/reports/employer-tax

Returns employer tax (arbeidsgiveravgift) calculations, broken down by tax zone.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes The client account ID
year integer Yes The reporting year
period_from_month integer No Start month (default: 1)
period_to_month integer No End month (default: 12)

Response

{
  "year": 2024,
  "period_from": "2024-01",
  "period_to": "2024-12",
  "total_basis": "540000.00",
  "total_employer_tax": "76140.00",
  "total_employer_tax_vacation": "9136.80",
  "total_amount": "85276.80",
  "zones": [
    {
      "zone_code": "1",
      "zone_name": "Sone 1",
      "rate": "0.141",
      "employer_tax_basis": "540000.00",
      "employer_tax_amount": "76140.00",
      "employer_tax_vacation": "9136.80",
      "total": "85276.80"
    }
  ]
}

Annual Summary

GET /api/v2/payroll/reports/annual-summary

Returns a comprehensive annual payroll summary with per-employee breakdowns including item-level detail.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes The client account ID
year integer Yes The reporting year

Response

{
  "year": 2024,
  "org_name": "Snapbooks AS",
  "org_number": "123456789",
  "run_count": 12,
  "total_gross": "540000.00",
  "total_tax": "150000.00",
  "total_net": "390000.00",
  "total_employer_costs": "76140.00",
  "employees": [
    {
      "bp_id": 56,
      "name": "Ola Nordmann",
      "ssn_masked": "010190*****",
      "total_gross": "540000.00",
      "total_tax_withholding": "150000.00",
      "total_deductions": "150000.00",
      "total_net": "390000.00",
      "total_employer_costs": "76140.00",
      "vacation_pay_basis": "540000.00",
      "pension_basis": "540000.00",
      "items": [
        {
          "code": "FAST_LONN",
          "name": "Fastlønn",
          "category": "EARNING",
          "total_amount": "540000.00"
        }
      ]
    }
  ]
}

Item Categories

Payroll line items are classified into the following categories:

Value Description
EARNING Salary, wages, and other compensation
DEDUCTION Tax withholding, pension contributions, and other deductions
EMPLOYER_COST Employer-side costs (employer tax, pension employer share)
INFO Informational items (e.g. vacation day balances)

Error Responses

Status Code Description
400 Invalid request (missing year parameter)
403 Forbidden (no access to client account)
404 Payroll run not found (run summary endpoint only)