Trekkpålegg API
This page describes a new interface between the IT systems of the Norwegian Tax Administration and liable parties/employers. The target audience is developers and IT architects at system providers who deliver payroll and HR systems (or end-user systems) to employers. These systems are hereafter referred to as End-User Systems, abbreviated as SBS.
A new interface will be established to transmit withholding orders from the Tax Administration to employers with employees who are subject to wage garnishment. This new interface will eventually replace the existing interface for withholding communication, but initially, it will be introduced alongside the current one. The new interface will first be available in a test environment, then in pilot projects, and finally in full production.
Key features of the new interface
• The interface is a machine-to-machine interface that transmits withholding orders from the Tax Administration to employers using SBS systems. • It follows a RESTful design and provides an API. • SBS systems must poll the interface to check for new withholding orders. • Eventually, a separate interface will be available, allowing SBS systems to receive notifications (events) when the Tax Administration issues a new withholding order to an employer. • SBS must present a token in the interface that contains the organization number of the liable employer. • The token is obtained by connecting to Maskinporten with a specified scope. • Withholding orders are delivered in JSON format.
For general informastion about the services; see pages (Norwegian) for:
Scope
The following scope is to be used when authenticating in Maskinporten: skatteetaten:trekkpaalegg
Delegation
Tilgang til dette API-et kan delegeres i Altinn, f.eks. dersom leverandør benyttes for den tekniske oppkoblingen. Søk
opp følgende tjeneste i Altinn for å delegere tilgangen: Trekkpålegg API - På vegne av
Technical specification
The Norwegian Tax Administration provides an API to retrieve withholding orders. The Open API specification is available here: Open API spesifikasjonen on SwaggerHub.
Trekkpålegg API
All URIs are relative to: • https://api-test.sits.no (test) • --- (production)
| Method | HTTP Request | Description |
|---|---|---|
| Get all active | GET /api/trekkpaalegg/v1 | Retrieve all current trekkpålegg for the liable party |
| Get version | GET /api/trekkpaalegg/v1/trekkid/trekkversjon | Retrieve a specific version of a trekkpålegg |
Data catalog
This API is currently not in the common data catalog
Access to the Service
Access is managed through Maskinporten. To obtain a token from Maskinporten, the payroll system must use its enterprise certificate to specify which organization number it represents. This organization number must be approved by the Norwegian Tax Administration. To use the services for Trekkpålegg, the following scope must be specified during authentication with Maskinporten: skatteetaten:trekkpaalegg The API supports two types of authentication via Maskinporten, as described below:
Option 1 – System Provider is the Liable Party
If the system provider is only receiving withholding orders for its own organization, traditional authentication via Maskinporten can be used. More information is available [here].
Option 2 – System User
If the system provider wants to offer functionality where another organization (a customer of the provider) uses the system to receive Trekkpålegg, Altinn’s new “system user” functionality must be used. More information is available in Altinn System User for SBS and the System User Roadmap. To support system user functionality, the provider must register in Maskinporten and the Altinn test environment.