Payroll Leaves API

Employee leaves track absences such as sick leave, parental leave, care days, and other types of leave. The API enforces Norwegian labor law constraints, including limits on self-certified sick leave (egenmelding).

API Endpoints

List Employee Leaves

GET /payroll/leaves

Retrieve a paginated list of employee leaves with filtering options.

Query Parameters

When filtering by year, the API returns all leaves that overlap the specified calendar year — leaves where the start date is before the end of the year and the end date is either null (ongoing) or on/after January 1 of that year.

Response

{
  "data": [
    {
      "id": 1,
      "business_partner_id": 56,
      "client_account_id": 7,
      "contract_id": 12,
      "leave_type": "SICK_SELF_CERTIFIED",
      "start_date": "2024-03-18",
      "end_date": "2024-03-20",
      "leave_percentage": "100.00",
      "source_reference": null,
      "status": "COMPLETED",
      "note": "Influenza",
      "created_by_id": 7,
      "created_at": "2024-03-18T08:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 100,
    "records": 1
  }
}

Results are sorted by start_date descending (newest first).

Get Employee Leave

GET /payroll/leaves/{id}

Retrieve a single employee leave by ID.

Path Parameters

Query Parameters

Create Employee Leave

POST /payroll/leaves

Creates a new employee leave record.

Request Body

Example Request

{
  "client_account_id": 7,
  "business_partner_id": 56,
  "leave_type": "PARENTAL",
  "start_date": "2024-04-01",
  "end_date": "2024-06-30",
  "contract_id": 12,
  "leave_percentage": "50.00",
  "note": "Paternity leave, 50% schedule"
}

Response

Returns the created leave with status 201 Created.

Reference Ownership

business_partner_id and contract_id are taken from the request body, so both are checked against the client account before the leave is stored:

• business_partner_id must name a business partner owned by client_account_id.
• contract_id, when supplied, must name an employment contract owned by client_account_id and belonging to the same employee as business_partner_id. The employee pairing matters because A-melding and NAV refund payloads group leaves by contract — a leave on another employee’s contract would be reported under the wrong person.

Both checks fail 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 Employee Leave

POST/PUT /payroll/leaves/{id}

Updates an existing employee leave. Both POST and PUT 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.

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

Response

Returns the updated leave.

Cancel Employee Leave

DELETE /payroll/leaves/{id}

Cancels an employee leave. This is a soft delete — the record remains in the database with status set to CANCELLED.

Path Parameters

Response

Returns the cancelled leave with status set to CANCELLED.

Attributes

Leave Types

Status Values

Self-Certified Sick Leave Rules

Norwegian labor law imposes specific limits on self-certified sick leave (egenmelding). The API enforces these automatically:

• Maximum duration: 3 calendar days per episode, counting both the first and the last day. If end_date is provided it must therefore be at most 2 days after start_date. A leave with no end_date is not duration-checked.
• Maximum frequency: 4 episodes per calendar year. The API counts ACTIVE and COMPLETED self-certified leaves whose start_date falls in the same calendar year as the leave being saved, excluding the record itself — so editing an existing episode does not count it twice.

Attempting to exceed these limits returns a 400 Bad Request error.

Relationships

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

• business_partner - The employee associated with the leave

Validation Rules

• business_partner_id is required, and must name a business partner in the same client account
• client_account_id is required
• contract_id, if provided, must name an employment contract in the same client account belonging to the same employee
• leave_type must be a valid leave type value
• start_date is required
• end_date must be on or after start_date (if provided)
• leave_percentage must be between 1 and 100 (if provided)
• status must be a valid status value (if provided)
• Self-certified sick leave has additional duration and frequency limits (see above)

Error Responses

Related Resources

• Payroll Contracts
• Payroll Runs
• Payroll Tax Cards
• Business Partners