Snapbooks logo Snapbooks Developer

Payroll Garnishments

Garnishments (utleggstrekk) represent legally mandated wage deduction orders for employees. These are fetched from Skatteetaten and are read-only in the API. Each garnishment specifies a deduction amount or percentage, a creditor, and validity dates.

Endpoints

Method Endpoint Description
GET /payroll/garnishments List garnishments
GET /payroll/garnishments/{id} Get a garnishment
POST /payroll/garnishments/fetch Fetch garnishments from Skatteetaten

List Garnishments

GET /api/v2/payroll/garnishments

Retrieves a paginated list of employee garnishments. Results are ordered by priority and then by ID.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes ID of the client account
business_partner_id integer No Filter by employee (business partner) ID
status string No Filter by status (e.g. ACTIVE, EXPIRED, CANCELLED)

Response

{
  "data": [
    {
      "id": 1,
      "created_by_id": 1,
      "created_at": "2024-06-01T12:00:00Z",
      "business_partner_id": 56,
      "client_account_id": 7,
      "external_id": "UTL-2024-001",
      "garnishment_type": "utleggstrekk",
      "deduction_type": "FIXED",
      "amount": "5000.000000",
      "percentage": null,
      "priority": 1,
      "creditor_id": 102,
      "creditor_bank_account_id": 45,
      "payment_reference": "12345678901",
      "valid_from": "2024-06-01",
      "valid_to": "2025-06-01",
      "status": "ACTIVE",
      "case_number": "2024/12345",
      "external_version": 1,
      "sequence_number": 1,
      "raw_response": null
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 25,
    "records": 1
  }
}

Get a Garnishment

GET /api/v2/payroll/garnishments/{id}

Retrieves a single garnishment by its ID.

Path Parameters

Parameter Type Description
id integer The garnishment ID

Response

Returns a single garnishment object (same shape as the list response data items).

Attributes

Attribute Type Description
id integer Unique identifier (read-only)
created_by_id integer ID of the creating user or system user (read-only)
created_at datetime Creation timestamp (read-only)
business_partner_id integer Employee (business partner) ID
client_account_id integer Client account ID
external_id string External identifier from Skatteetaten
garnishment_type string Type of garnishment (e.g. utleggstrekk)
deduction_type string How the deduction is calculated: FIXED (fixed amount) or PERCENTAGE
amount decimal Fixed deduction amount per pay period. Set when deduction_type is FIXED
percentage decimal Deduction percentage of net pay. Set when deduction_type is PERCENTAGE
priority integer Processing priority. Lower numbers are deducted first
creditor_id integer Business partner ID of the creditor receiving the deducted funds
creditor_bank_account_id integer Bank account ID for creditor payment
payment_reference string Payment reference (KID) for creditor payment
valid_from date Start date of the garnishment
valid_to date End date of the garnishment
status string Current status: ACTIVE, EXPIRED, or CANCELLED
case_number string Case number from the enforcement authority (namsmannen)
external_version integer Version number from the external system
sequence_number integer Sequence number when multiple garnishments exist for the same employee
raw_response object Raw response from Skatteetaten (for debugging)

Fetch Garnishments from Skatteetaten

POST /payroll/garnishments/fetch

Queues a background task that fetches current garnishment orders from Skatteetaten for 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

Example Request

{
  "client_account_id": 7
}

Response (202 Accepted)

{
  "message": "Garnishment fetch queued"
}

Error Responses

Status Description
400 Missing client_account_id
403 No access to the client account

Notes

  • Garnishments are read-only. They are fetched from Skatteetaten and cannot be created, updated, or deleted via the API. Use the fetch endpoint above to refresh them.
  • Active garnishments are automatically applied during payroll processing.
  • The priority field determines the order in which garnishments are applied when an employee has multiple active garnishments.

Error Responses

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