Payroll Contracts API

Employment contracts represent the formal employment agreements between a company and its employees. Each contract captures salary details, working arrangements, pension configuration, and is used as the basis for payroll runs and A-melding reporting to Norwegian tax authorities.

API Endpoints

List Employment Contracts

GET /payroll/contracts

Retrieve a paginated list of employment contracts with filtering options.

Query Parameters

Response

{
  "data": [
    {
      "id": 1,
      "business_partner_id": 56,
      "client_account_id": 7,
      "employment_type": "EMPLOYED",
      "start_date": "2024-01-15",
      "end_date": null,
      "job_title": "Accountant",
      "occupation_code_lv": "2511102",
      "employment_form": "PERMANENT",
      "work_time_arrangement_lv": "ikkeSkift",
      "work_percentage": "100.00",
      "weekly_hours": "37.50",
      "salary_type": "MONTHLY_FIXED",
      "monthly_salary": "45000.000000",
      "hourly_rate": null,
      "vacation_pay_rate": "0.1200",
      "pension_rate": "0.0200",
      "employee_pension_rate": "0.0200",
      "pension_provider_id": null,
      "union_dues_amount": null,
      "car_registration_number": null,
      "car_list_price": null,
      "is_primary_employer": true,
      "is_active": true,
      "is_payroll_default": true,
      "arbeidsforhold_id": "a1b2c3d4e5f6g7h8i9j0",
      "created_by_id": 7,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Get Employment Contract

GET /payroll/contracts/{id}

Retrieve a single employment contract by ID.

Path Parameters

Query Parameters

Create Employment Contract

POST /payroll/contracts

Creates a new employment contract. Automatically triggers a background task to fetch tax cards from Skatteetaten for the current tax year.

Request Body

Example Request

{
  "client_account_id": 7,
  "business_partner_id": 56,
  "employment_type": "EMPLOYED",
  "start_date": "2024-01-15",
  "salary_type": "MONTHLY_FIXED",
  "monthly_salary": "45000.00",
  "job_title": "Accountant",
  "occupation_code_lv": "2511102",
  "employment_form": "PERMANENT",
  "work_time_arrangement_lv": "ikkeSkift",
  "work_percentage": "100.00",
  "weekly_hours": "37.50",
  "vacation_pay_rate": "0.1200",
  "pension_rate": "0.0200",
  "is_primary_employer": true,
  "is_payroll_default": true
}

Local values

Fields ending in _lv hold a code from a national code list exactly as the authority writes it, rather than a Snapbooks enum:

• occupation_code_lv: the 7-digit code from SSB’s yrkeskatalog, e.g. 2511102.
• work_time_arrangement_lv: one of Skatteetaten’s arbeidstidsordning codes: ikkeSkift, andreSkift, skift365, doegnkontinuerligSkiftOgTurnus355, helkontinuerligSkiftOgAndreOrdninger336 or offshore336.

When a create or update request includes job_title for an EMPLOYED contract that has no occupation_code_lv, Snapbooks looks the code up from the title, the company’s industry and its size before saving. This adds a few seconds to that request. A code that is already set is never replaced; to look it up again, send occupation_code_lv: null together with job_title. If no code fits, the contract is saved without one.

An EMPLOYED contract is reported to Skatteetaten as an ordinary arbeidsforhold, which needs occupation_code_lv, work_percentage, weekly_hours, work_time_arrangement_lv, employment_form and last_salary_change_date. Without them the a-melding is accepted but flagged for correction.

Response

Returns the created employment contract with status 201 Created.

Reference Ownership

business_partner_id and pension_provider_id are taken from the request body, so both are checked against the client account before the contract is stored. Each must name a business partner owned by client_account_id; anything else fails with 400 Bad Request. An id that does not exist is rejected the same way as one owned by another client account, so the response cannot be used to probe for existing ids.

Update Employment Contract

POST/PUT /payroll/contracts/{id}

Updates an existing employment contract. Both POST and PUT methods are accepted. Only provided fields are updated.

Path Parameters

Request Body

Same fields as create, except client_account_id and business_partner_id which cannot be changed after creation.

pension_provider_id is re-checked against the ownership rule above only when the field is present in the request body. A contract that already carries a pension provider you are not entitled to can therefore still be edited or deactivated without first correcting that field.

Side Effects

• Setting is_active from false to true triggers a background task to fetch tax cards.
• Setting is_active from true to false triggers an A-melding submission to Skatteetaten with the end date.

Response

Returns the updated employment contract.

Attributes

Relationships

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

• business_partner - The employee associated with the contract

Validation Rules

• business_partner_id is required, and must name a business partner in the same client account
• client_account_id is required
• pension_provider_id, if provided, must name a business partner in the same client account
• employment_type is required
• start_date is required
• salary_type must be MONTHLY_FIXED, HOURLY or COMMISSION
• When salary_type is MONTHLY_FIXED, monthly_salary is required
• When salary_type is HOURLY, hourly_rate is required
• When salary_type is COMMISSION, monthly_salary and hourly_rate must be empty
• vacation_pay_rate, pension_rate and employee_pension_rate are fractions below 1
• work_percentage is between 0 and 100; weekly_hours is above 0 and at most 168

Error Responses

Related Resources

• Payroll Runs
• Payroll Leaves
• Payroll Tax Cards
• Business Partners