Snapbooks logo Snapbooks Developer

Payroll Tax Cards API

Tax cards (skattekort) contain the tax withholding information for each employee, fetched from Skatteetaten (Norwegian Tax Authority). They specify how much tax should be withheld from salary payments, using either a tax table number or a fixed percentage.

Tax cards are read-only — they are fetched automatically in the background when employment contracts are created or activated, and cannot be created or modified through the API.

API Endpoints

Method Endpoint Description
GET /payroll/tax-cards List tax cards
GET /payroll/tax-cards/{id} Get a tax card
POST /payroll/tax-cards/fetch Fetch tax cards from Skatteetaten

List Tax Cards

GET /payroll/tax-cards

Retrieve a paginated list of tax cards with filtering options.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes Filter by client account ID (must be from user’s eligible accounts)
business_partner_id integer No Filter by employee (business partner) ID
tax_year integer No Filter by tax year (e.g. 2024)
page integer No Page number for pagination (default: 1)
per_page integer No Number of items per page (default: 100)
with string No Comma-separated list of relations to include

Response

{
  "data": [
    {
      "id": 1,
      "business_partner_id": 56,
      "client_account_id": 7,
      "tax_year": 2024,
      "card_type": "TABLE",
      "table_number": "04",
      "tax_percentage": "22.00",
      "free_amount": "150000.000000",
      "free_amount_remaining": "75000.000000",
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "fetched_at": "2024-01-15T10:30:45Z",
      "raw_response": { "..." : "..." },
      "created_by_id": 1,
      "created_at": "2024-01-15T10:30:45Z"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Results are sorted by id descending (most recently fetched first).

Get Tax Card

GET /payroll/tax-cards/{id}

Retrieve a single tax card by ID.

Path Parameters

Parameter Type Description
id integer Tax card ID

Query Parameters

Parameter Type Required Description
with string No Comma-separated list of relations to include

Attributes

Attribute Type Description
id integer Unique identifier (read-only)
business_partner_id integer Employee (business partner) ID
client_account_id integer Client account ID
tax_year integer Income tax year this card applies to
card_type string Type of tax card (see Card Types)
table_number string Tax table number (e.g. “04”)
tax_percentage decimal Withholding tax percentage (e.g. 22.00)
free_amount decimal Total annual free amount before withholding
free_amount_remaining decimal Remaining free amount not yet used
valid_from date Start date the card is valid
valid_to date End date the card is valid
fetched_at datetime Timestamp when the card was fetched from Skatteetaten
raw_response object Full raw JSON response from Skatteetaten (for debugging/audit)
created_by_id integer ID of the creating user (read-only)
created_at datetime Creation timestamp (read-only)

Card Types

Value Description
TABLE Tax table-based withholding
PERCENTAGE Fixed percentage withholding
EXEMPT Exempt from withholding
SOURCE_TAX Source tax
NO_TAX_CARD No tax card found at Skatteetaten
UNPROCESSED Fetched but not yet parsed

Relationships

The following related objects can be included using the with parameter:

  • business_partner - The employee associated with the tax card

Fetch Tax Cards from Skatteetaten

POST /payroll/tax-cards/fetch

Queues a background task that fetches tax cards from Skatteetaten for one or all employees in a client account. The task runs asynchronously — poll the list endpoint to see updated results.

Request Body

Field Type Required Description
client_account_id integer Yes The client account ID
income_year integer Yes The tax year to fetch cards for (e.g. 2026)
business_partner_id integer No Fetch only for this employee. If omitted, fetches for all employees with active contracts

Example Request

{
  "client_account_id": 7,
  "income_year": 2026
}

Response (202 Accepted)

{
  "message": "Tax card fetch queued"
}

Error Responses

Status Description
400 Missing or invalid client_account_id, income_year, or business_partner_id
403 No access to the client account

How Tax Cards Are Fetched

Tax cards cannot be created or updated directly through the API. They are fetched from Skatteetaten in the following scenarios:

  1. Employment contract created — A background task fetches tax cards for the current tax year.
  2. Employment contract reactivated — When a contract’s is_active changes from false to true, tax cards are fetched.
  3. Manual fetch — Tax cards can be refreshed via the fetch endpoint above (POST /payroll/tax-cards/fetch).

The fetched_at timestamp indicates when the card was last retrieved from Skatteetaten. The raw_response field contains the complete response for audit purposes.

Error Responses

Status Code Description
403 Forbidden (no access to client account)
404 Tax card not found