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"
    }
  ]
}

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)