Menu

Employees

Payroll roster: CRUD with personnummer masking on list endpoints.

Endpoints


GET /api/v1/companies/:companyId/employees

employees.list · scope payroll:read

List employees for a company.

Returns active employees in created-first order. Pass ?include_inactive=true to include soft-deleted (is_active=false) rows. Use ?search to match against first or last name. Personnummer is masked (birthdate visible, last-4 hidden); use GET /employees/{id} for the full value.

Use when: You need a roster: for building a UI picker, resolving employee_id before adding to a salary run, or syncing an external HR system.

Don't use for: Fetching a single employee you already know the id of: use GET /api/v1/companies/{companyId}/employees/{id}. Salary calculations live on /salary-runs/{id}.

Pitfalls

  • Inactive employees are hidden by default; soft-delete via DELETE sets is_active=false (BFL 7 kap retention).
  • personnummer is masked in the list response (GDPR Art.5(1)(c) data minimisation). The detail endpoint returns the full value.
  • salary_type drives which field is meaningful: monthly_salary for monthly, hourly_rate for hourly. The other is null.
  • personnel_category decides the wage account series for employment_type employee only: arbetare book 70xx (7010/7082/7090), tjansteman 72xx. Owners and board members keep their own accounts whatever it says.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
employment_type"employee" | "company_owner" | "board_member"noOnly employees with this employment type.
personnel_category"arbetare" | "tjansteman"noOnly employees in this personnel category (arbetare or tjansteman).
searchstringnoCase-insensitive match anywhere in the first or last name, 1-200 characters.
include_inactive"true" | "false"notrue also returns inactive employees. Default: active only.
cursorstringnoOpaque cursor from the previous page's meta.next_cursor. Omit for the first page.
limitnumbernoPage size, 1-100 (default 50). Larger values are clamped to 100.

Response fields

NameTypeDescription
[].idstring
[].handlestring (optional)Typed handle of this employee: emp_ plus its id as 32 lowercase hex. Accepted wherever the id is.
[].first_namestring
[].last_namestring
[].personnummer_maskedstring
[].employment_type"employee" | "company_owner" | "board_member"
[].personnel_category"arbetare" | "tjansteman"
[].employment_startstring
[].employment_endstring | null
[].salary_type"monthly" | "hourly"
[].monthly_salarynumber | null
[].hourly_ratenumber | null
[].f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"
[].is_activeboolean
[].created_atstring

Example response

{
  "data": [
    {
      "id": "a8f1…",
      "first_name": "Anna",
      "last_name": "Andersson",
      "personnummer_masked": "YYYYMMDD-XXXX",
      "employment_type": "employee",
      "personnel_category": "tjansteman",
      "employment_start": "2024-01-15",
      "employment_end": null,
      "salary_type": "monthly",
      "monthly_salary": 35000,
      "hourly_rate": null,
      "f_skatt_status": "a_skatt",
      "is_active": true,
      "created_at": "2024-01-15T08:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

GET /api/v1/companies/:companyId/employees/:id

employees.get · scope payroll:read

Get a single employee.

Returns the full employee record including the 12-digit personnummer, bank details, tax configuration, and contact info. This is the deliberate drill-in for an id you already know: list calls mask personnummer.

Use when: You have an employee id and need every field (tax table, bank account, vacation rule): typically to render an edit form or to construct a payroll calculation input.

Don't use for: Rosters or pickers (use the list endpoint: personnummer is masked there).

Pitfalls

  • The response includes the full personnummer. Treat it as a national identifier (GDPR Art.5(1)(c)): do not propagate it to logs or external systems beyond what your integration strictly requires.
  • Inactive (soft-deleted) employees are returned by the detail endpoint; check is_active if your flow should skip them.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this employee: emp_ plus its id as 32 lowercase hex. Accepted wherever the id is.
first_namestring
last_namestring
personnummerstring
employment_type"employee" | "company_owner" | "board_member"
personnel_category"arbetare" | "tjansteman"
employment_startstring
employment_endstring | null
employment_degreenumber
hours_per_weeknumber
workdays_per_weeknumber
salary_type"monthly" | "hourly"
monthly_salarynumber | null
hourly_ratenumber | null
tax_table_numbernumber | null
tax_columnnumber | null
tax_municipalitystring | null
is_sidoinkomstboolean
f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"
clearing_numberstring | null
bank_account_numberstring | null
vacation_rulestring
vacation_days_per_yearnumber
semestertillagg_ratenumber
vacation_pay_ratenumber | null
emailstring | null
phonestring | null
address_line1string | null
postal_codestring | null
citystring | null
fora_fok_idstring | null
fora_fok_start_datestring | null
vaxa_stod_eligibleboolean
vaxa_stod_startstring | null
vaxa_stod_endstring | null
jamkning_percentagenumber | null
jamkning_valid_fromstring | null
jamkning_valid_tostring | null
extra_tax_amountnumber | null
extra_tax_percentagenumber | null
default_dimensionsobject
is_activeboolean
created_atstring
updated_atstring

Example response

{
  "data": {
    "id": "a8f1…",
    "first_name": "Anna",
    "last_name": "Andersson",
    "personnummer": "YYYYMMDDNNNN",
    "employment_type": "employee",
    "personnel_category": "tjansteman",
    "employment_start": "2024-01-15",
    "employment_end": null,
    "salary_type": "monthly",
    "monthly_salary": 35000,
    "f_skatt_status": "a_skatt",
    "is_active": true
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/absence

employees.absence.list · scope payroll:read

List absence days for an employee in a date range.

Returns per-day absence rows (sick, vab, parental, ...) between ?from and ?to (inclusive, max 92 days). No cursor pagination: the bounded range is the page. Optional ?type filter.

Use when: You need an employee's registered absence: to reconcile with an external time-tracking system, to verify what the salary engine will derive, or to display a calendar.

Don't use for: The derived pay impact (karensavdrag, sjuklön lines): that lives on the payslip detail after :calculate. Worked hours for hourly staff: separate register, not on v1 yet.

Pitfalls

  • Ranges over 92 days return 400 ABSENCE_RANGE_TOO_LARGE: iterate quarters instead.
  • A day can carry multiple rows with different absence_type values (e.g. half-day sick + half-day vab).
  • Rows may reference the salary run that consumed them via salary_run_employee_id.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
fromstringyesYYYY-MM-DD. First day of the range (inclusive). Required.
tostringyesYYYY-MM-DD. Last day of the range (inclusive), not before from. Required.
type"sick" | "vab" | "parental" | "pregnancy" | "care_relative" | "study" | "unpaid_leave" | "other_leave"noOnly days of this absence type. Default: every type.

Response fields

NameType
[].salary_absence_day_idstring
[].absence_datestring
[].absence_type"sick" | "vab" | "parental" | "pregnancy" | "care_relative" | "study" | "unpaid_leave" | "other_leave"
[].hoursnumber
[].notesstring | null
[].salary_run_employee_idstring | null
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "salary_absence_day_id": "abs_91d2…",
      "absence_date": "2026-03-03",
      "absence_type": "sick",
      "hours": 8,
      "notes": null
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/benefits

employees.benefits.list · scope payroll:read

List the benefits (förmåner) registered on an employee.

Returns every benefit row on the employee, active and inactive, newest validity window first (valid_from descending, then created_at). Optional ?active=true|false filter. No cursor pagination: an employee carries a handful of rows.

Use when: You need to see which förmåner the salary engine will derive for an employee (bilförmån, kostförmån, cykelförmån, bostad, friskvård, annat), reconcile against an HR system, or find the employee_benefit_id to update or remove.

Don't use for: The derived payslip line and its tax effect: that lives on the salary run after :calculate. Standing deductions (bruttolöneavdrag, fackavgift): the recurring-lines register.

Pitfalls

  • The monthly förmånsvärde is added to the tax and arbetsgivaravgift basis when a run is calculated (POST /salary-runs/{id}/calculate); it is never paid out.
  • A run picks a row up when is_active is true and valid_from <= payment_date <= valid_to (valid_to null = open-ended). Rows outside that window are listed here but derive nothing.
  • annual_market_value is populated for bike benefits only (read from the stored calculation inputs); other types carry null.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
active"true" | "false"notrue returns only rows with is_active=true, false only inactive rows. Default: both.

Response fields

NameType
[].employee_benefit_idstring
[].benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other"
[].descriptionstring
[].monthly_valuenumber
[].annual_market_valuenumber | null
[].valid_fromstring
[].valid_tostring | null
[].is_activeboolean
[].metadataobject
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "employee_benefit_id": "ben_4f2a…",
      "benefit_type": "car",
      "description": "Bilförmån Volvo XC40",
      "monthly_value": 4275,
      "annual_market_value": null,
      "valid_from": "2026-01-01",
      "valid_to": null,
      "is_active": true,
      "metadata": {},
      "created_at": "2026-01-05T09:12:00Z",
      "updated_at": "2026-01-05T09:12:00Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/opening-balances

employees.opening-balances.get · scope payroll:read

Get an employee's payroll cutover opening balances.

Returns the opening balances set for a mid-year migration (YTD gross/tax/net, the five vacation pools Betalda/Sparade per år/Obetalda/Förskott/Extra betalda with their as-of date, opening semesterlöneskuld and förskottsskuld, karens adjustment) plus the lock state: locked=true once the employee has a booked salary run. ytd_net is null when the previous system could not export historical net pay.

Use when: Verifying cutover state before the first calculated run, or checking whether balances can still be edited (locked=false).

Don't use for: The live vacation liability (GET /reports/vacation-liability includes the opening terms). Pre-cutover absence history: GET /employees/{id}/absence.

Pitfalls

  • 404 NOT_FOUND when no opening balances have been set: distinct from an all-zeros row.
  • locked_by_run_id names the booked run that froze the row; correcting that run unlocks it.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameType
employee_opening_balances_idstring | null
employee_idstring
cutover_datestring
ytd_grossnumber
ytd_taxnumber
ytd_netnumber | null
vacation_paid_days_remainingnumber
vacation_days_taken_this_yearnumber
vacation_saved_days_by_yearobject
opening_semester_liabilitynumber
opening_semester_liability_avgifternumber
karens_periods_adjustmentnumber
vacation_as_of_datestring | null
vacation_unpaid_days_remainingnumber
vacation_advance_days_remainingnumber
vacation_extra_paid_days_remainingnumber
opening_advance_vacation_debtnumber
lockedboolean
locked_by_run_idstring | null

Example response

{
  "data": {
    "employee_id": "emp_77b2…",
    "cutover_date": "2026-07-01",
    "ytd_gross": 210000,
    "vacation_paid_days_remaining": 12.5,
    "locked": false
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/recurring-lines

employees.recurring-lines.list · scope payroll:read

List recurring payslip lines for an employee.

Returns the employee's standing monthly payslip rows (gross and net deductions such as a benefit bike bruttolöneavdrag, a union fee, or a net deduction for a benefit the employee pays for, and text rows explaining the payslip), newest valid_from first. Both active and deactivated lines are returned unless ?active filters them.

Use when: You need to see what the salary engine will derive for an employee every month, to reconcile with an HR system, or to find the employee_recurring_line_id to update or delete.

Don't use for: The derived payslip rows of one run: those are on the salary run detail after :calculate. Taxable benefits in kind (bilförmån, kostförmån): use the employee benefits endpoints.

Pitfalls

  • Rows are re-derived on every :calculate for runs whose payment_date falls inside valid_from..valid_to (valid_to null = open-ended). Hand edits to a derived payslip row are overwritten by the next :calculate.
  • The amount follows the item type: a deduction is negative (e.g. -670.17 for a benefit bike bruttolöneavdrag), and a text row (item_type text) has none: omit amount (0 is accepted) and put the words in description, e.g. how the salary is built up. The API rejects the wrong sign, or an amount on a text row, with 400 VALIDATION_ERROR on field amount.
  • Recurring additions (a personligt tillägg next to Grundlön, a cash allowance) are not supported: proration, absence deductions, sjuklön, semestertillägg and the OB rate read only monthly_salary, so a standing tillägg row would be paid in full through sick leave. Put a standing raise on the employee's monthly_salary and explain the split with a text row.
  • account_number overrides the default BAS account for the derived payslip row; null lets the engine use its item-type mapping. A text row has no account: account_number is ignored.
  • Draft-only per-run edits (a one-off change on one payslip) still go through the salary-runs lines endpoints, not through recurring lines.
  • Deactivated lines (is_active=false) are listed too: a line that a booked run derived from cannot be deleted, only deactivated, so history keeps it.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
active"true" | "false"notrue returns active lines only, false deactivated lines only. Default: every line.

Response fields

NameType
[].employee_recurring_line_idstring
[].item_type"gross_deduction_pension" | "gross_deduction_other" | "net_deduction_union" | "net_deduction_benefit_payment" | "net_deduction_other" | "text"
[].descriptionstring
[].amountnumber
[].account_numberstring | null
[].valid_fromstring
[].valid_tostring | null
[].is_activeboolean
[].metadataobject
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "employee_recurring_line_id": "erl_5b1c…",
      "item_type": "gross_deduction_other",
      "description": "Förmånscykel bruttolöneavdrag",
      "amount": -670.17,
      "account_number": null,
      "valid_from": "2026-01-01",
      "valid_to": null,
      "is_active": true,
      "metadata": {}
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/vacation-balance

employees.vacation-balance.get · scope payroll:read

Get an employee's current vacation balance.

Returns the open vacation-ledger row (recomputed on every booking): entitled/taken/remaining paid days, sparade dagar still held per origin year (Semesterlagen 5-year rule; saved_days_taken shows what saved vacation lines consumed this year), the unpaid (Obetalda) and advance (Förskott) pools from the cutover import, forced-payout days from expired savings, and a computed SEK estimate of the individual semesterlöneskuld.

Use when: Answering "how many vacation days does Anna have left", pre-payroll review, or preparing the year-close.

Don't use for: The company-wide liability report: GET /reports/vacation-liability. Closing the year: POST /salary/vacation-year-close.

Pitfalls

  • 404 VACATION_BALANCE_NOT_FOUND until the first booking (or year-close) touches the employee: the ledger seeds lazily.
  • remaining_days can go negative if more days were taken than entitled: surface it, do not clamp.
  • The days are paid semesterdagar. remaining_days_off is the days the employee can still take off: equal to remaining_days at five workdays a week or more, fewer below (25 paid days are 20 days off at four days a week, Semesterlagen 12 a §).
  • The SEK estimate uses the year-close day valuation (simplified BFNAR 2016:10); the booked 2920 is reconciled only at year-close.
  • unpaid_days and advance_days are the cutover pools minus unpaid/advance vacation lines in booked runs; both read 0 for companies that never loaded categorized balances and outside the cutover year (unpaid days lapse at close, förskott is a one-time grant).

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameType
employee_vacation_balance_idstring
employee_idstring
vacation_year_startstring
entitled_daysnumber
accrued_daysnumber
taken_daysnumber
remaining_daysnumber
remaining_days_offnumber
saved_daysobject
saved_days_totalnumber
saved_days_takenobject
unpaid_daysnumber
advance_daysnumber
forced_payout_daysnumber
estimated_liability_seknumber

Example response

{
  "data": {
    "employee_id": "emp_77b2…",
    "vacation_year_start": "2026-01-01",
    "entitled_days": 25,
    "taken_days": 10,
    "remaining_days": 15,
    "saved_days": {
      "2025": 5
    },
    "saved_days_total": 5,
    "estimated_liability_sek": 31151.4
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/employees/:id/worked-days

employees.worked-days.list · scope payroll:read

List worked days (hours per date) for an employee in a date range.

Returns the per-day worked-hours rows (tidrapport) between ?from and ?to (inclusive, max 92 days): hours, optional shift window (start_time/end_time) and notes. No cursor pagination: the bounded range is the page.

Use when: You need what is registered for an hourly employee before running payroll, to reconcile with an external time-tracking system, or to verify the hours the salary engine will pick up.

Don't use for: Absence (sick, vab, parental): GET /employees/{id}/absence. The derived pay (hourly gross, OB lines): that lives on the run after POST /salary-runs/{id}/calculate.

Pitfalls

  • Ranges over 92 days return 400 VALIDATION_ERROR with details.max_days = 92: iterate quarters instead.
  • POST /salary-runs/{id}/calculate reads these rows by the run's deviation window (deviation_period_start..deviation_period_end), not the pay month: register hours on the dates they were worked and check the run's window.
  • One row per date: an hourly employee with two shifts on the same day has ONE row with the combined hours (and the shift window of the OB-relevant one).

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
fromstringyesYYYY-MM-DD. First day of the range (inclusive). Required.
tostringyesYYYY-MM-DD. Last day of the range (inclusive), not before from. Required.

Response fields

NameType
[].salary_worked_day_idstring
[].work_datestring
[].hoursnumber
[].start_timestring | null
[].end_timestring | null
[].notesstring | null
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "salary_worked_day_id": "wd_91d2…",
      "work_date": "2026-03-02",
      "hours": 8,
      "start_time": "22:00:00",
      "end_time": "06:00:00",
      "notes": null
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/salary-runs/:id/employees

salary-runs.employees.list · scope payroll:read

List per-employee results of a salary run.

Returns one row per employee in the run with the calculated aggregates: gross salary, tax withheld, net pay, arbetsgivaravgifter, vacation accrual, and absence day counts. All aggregate fields are 0 until POST /calculate has run. Cursor pagination on (created_at, id).

Use when: You need the per-employee outcome of a run: to review before approval, to reconcile against an external system, or to pick an employee_id for the payslip drill-in.

Don't use for: Payslip line items or the step-by-step calculation breakdown: use GET /salary-runs/{id}/employees/{employeeId}. The employee master record: use GET /employees/{id}.

Pitfalls

  • Aggregates are 0 until POST /calculate has advanced the run to review.
  • effective is what is booked, declared and paid; the plain columns are the calculation's values. tax_withheld_override / avgifter_amount_override are review-stage manual adjustments: a tax override also moves the net payout, and an avgifter override is ignored for an F-skatt payee, so do not apply the overrides yourself.
  • personnummer is masked on all payslip-shaped responses (GDPR Art.5(1)(c)); the employee detail endpoint returns the full value.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
cursorstringnoOpaque cursor from the previous page's meta.next_cursor. Omit for the first page.
limitnumbernoPage size, 1-100 (default 50). Larger values are clamped to 100.

Response fields

NameTypeDescription
[].salary_run_employee_idstring
[].employee_idstring
[].first_namestring
[].last_namestring
[].personnummer_maskedstring
[].salary_typestring
[].employment_degreenumber
[].monthly_salarynumber | null
[].hours_workednumber | null
[].gross_salarynumber
[].taxable_incomenumber
[].tax_withheldnumber
[].tax_withheld_overridenumber | null
[].net_salarynumber
[].avgifter_basisnumber
[].avgifter_amountnumber
[].avgifter_amount_overridenumber | null
[].avgifter_categorystring | null
[].vacation_accrualnumber
[].sick_daysnumber
[].vab_daysnumber
[].parental_daysnumber
[].vacation_days_takennumber
[].effectiveobjectThe figures the booking, the AGI and the bank file use once the review overrides apply: tax = the tax override when set; extra_tax_withheld = the employee-requested förhöjt skatteavdrag inside that tax, 0 under a tax override; net moves by the same amount; avgifter = the avgifter override when set, except for an F-skatt payee (no avgifter underlag, the override is ignored); employer_cost = gross + avgifter + vacation accrual and its avgifter.
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "salary_run_employee_id": "sre_a8f1…",
      "employee_id": "emp_77b2…",
      "first_name": "Anna",
      "last_name": "Andersson",
      "personnummer_masked": "YYYYMMDD-XXXX",
      "salary_type": "monthly",
      "gross_salary": 35000,
      "tax_withheld": -8200,
      "net_salary": 26800,
      "avgifter_amount": 10997
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

GET /api/v1/companies/:companyId/salary-runs/:id/employees/:employeeId

salary-runs.employees.get · scope payroll:read

Get one employee's payslip in a salary run.

Returns the full payslip for one employee in a run: gross/tax/net aggregates, arbetsgivaravgifter with category, vacation accrual, YTD accumulators, every payslip line item (grundlön, tillägg, avdrag, förmåner), and the step-by-step calculation_breakdown recorded by the engine.

Use when: You need to verify how a specific employee's pay was computed: reviewing a run before approval, answering "why is the tax this amount", or rendering a payslip in an external system.

Don't use for: The rendered PDF payslip: use GET /salary-runs/{id}/payslips/{employeeId}/pdf. Editing line items: POST/PATCH/DELETE on the lines endpoints.

Pitfalls

  • calculation_breakdown is null and aggregates are 0 until POST /calculate has run.
  • line_items include engine-derived rows (absence, benefits) that are regenerated on every :calculate; manual rows survive recalculation.
  • effective is what is booked, declared and paid; the plain columns are the calculation's values. A tax override also moves the net payout, and an avgifter override is ignored for an F-skatt payee, so read effective instead of applying the overrides yourself.
  • personnummer is masked here (GDPR Art.5(1)(c)); GET /employees/{id} is the identity drill-in.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Response fields

NameTypeDescription
salary_run_employee_idstring
salary_run_idstring
employee_idstring
first_namestring
last_namestring
personnummer_maskedstring
salary_typestring
employment_degreenumber
monthly_salarynumber | null
hours_workednumber | null
gross_salarynumber
gross_deductionsnumber
benefit_valuesnumber
taxable_incomenumber
tax_withheldnumber
extra_tax_withheldnumber
tax_withheld_overridenumber | null
net_deductionsnumber
net_salarynumber
avgifter_ratenumber
avgifter_basisnumber
avgifter_amountnumber
avgifter_basis_overridenumber | null
avgifter_amount_overridenumber | null
avgifter_categorystring | null
override_reasonstring | null
vacation_accrualnumber
vacation_accrual_avgifternumber
tax_table_numbernumber | null
tax_columnnumber | null
tax_table_yearnumber | null
sick_daysnumber
vab_daysnumber
parental_daysnumber
vacation_days_takennumber
ytd_grossnumber
ytd_taxnumber
ytd_netnumber
effectiveobjectThe figures the booking, the AGI and the bank file use once the review overrides apply: tax = the tax override when set; extra_tax_withheld = the employee-requested förhöjt skatteavdrag inside that tax, 0 under a tax override; net moves by the same amount; avgifter = the avgifter override when set, except for an F-skatt payee (no avgifter underlag, the override is ignored); employer_cost = gross + avgifter + vacation accrual and its avgifter.
calculation_breakdownunknown (optional)
line_itemsobject[]
created_atstring
updated_atstring

Example response

{
  "data": {
    "salary_run_employee_id": "sre_a8f1…",
    "employee_id": "emp_77b2…",
    "first_name": "Anna",
    "last_name": "Andersson",
    "personnummer_masked": "YYYYMMDD-XXXX",
    "gross_salary": 35000,
    "tax_withheld": -8200,
    "net_salary": 26800,
    "line_items": [
      {
        "salary_line_item_id": "sli_31c9…",
        "item_type": "monthly_salary",
        "description": "Grundlön",
        "amount": 35000
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/employees

employees.create · scope payroll:write

Create an employee.

Creates a new employee for the company. Requires Idempotency-Key (UUID). Supports ?dry_run=true for input validation without committing. The personnummer in the request body must be 12 digits (ÅÅÅÅMMDDNNNN); the response echoes a masked form (birthdate + XXXX): GDPR Art.5(1)(c).

Use when: You need to register a new employee before adding them to a salary run. Use dry-run first to catch validation errors (missing tax table, salary amount, F-skatt mismatch) before committing.

Don't use for: Updating an existing employee (PATCH instead). Soft-deactivating (DELETE: sets is_active=false). Hard-deleting (the API does not expose hard delete; BFL 7 kap retention).

Pitfalls

  • Idempotency-Key is mandatory: calls without it return 400 VALIDATION_ERROR.
  • personnummer must be exactly 12 digits with the YYYYMMDD prefix (not the short 10-digit form).
  • Duplicate personnummer within a company returns 409 EMPLOYEE_DUPLICATE_PERSONNUMMER. Personnummer is unique per (company_id, personnummer).
  • For A-skatt employees who are not sidoinkomst, tax_table_number is required (29-42).
  • salary_type drives which salary field is required: monthly_salary for monthly, hourly_rate for hourly.
  • personnel_category defaults to tjansteman (72xx wage accounts). Set arbetare for kollektivanställda so their wages book on 7010, vacation pay on 7082 and the vacation liability change on 7090. Ignored for company_owner and board_member.
  • A worker reported to Fora every month (Avtalspension SAF-LO) needs fora_fok_id (FOK plus six digits, from Fora's Mina sidor) together with fora_fok_start_date; never on company_owner or board_member (400).
  • The response masks personnummer; never echo back the supplied value. Detail endpoint (deliberate drill-in) returns the full value.
  • vaxa_stod_eligible never lowers the arbetsgivaravgifter: from redovisningsperiod 202601 (Lag 2025:1334) the AGI declares the full avgifter and the company applies to Skatteverket for the refund after filing. A salary run paid inside vaxa_stod_start..vaxa_stod_end (end optional; never past the 24th calendar month counted from the start month) notes the expected refund per employee and warns to apply.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
first_namestringyes
last_namestringyes
personnummerstringyes
employment_type"employee" | "company_owner" | "board_member"no
personnel_category"arbetare" | "tjansteman"no
employment_startstringyes
employment_endstringno
employment_degreenumberno
hours_per_weeknumberno
workdays_per_weeknumberno
salary_type"monthly" | "hourly"no
monthly_salarynumberno
hourly_ratenumberno
tax_table_numbernumberno
tax_columnnumberno
tax_municipalitystringno
is_sidoinkomstbooleanno
f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"no
clearing_numberstringno
bank_account_numberstringno
vacation_rule"procentregeln" | "sammaloneregeln" | "none" | "semesterersattning"no
vacation_days_per_yearnumberno
semestertillagg_ratenumberno
vacation_pay_ratenumber | nullno
fora_fok_idstringno
fora_fok_start_datestringno
emailstringno
phonestringno
address_line1stringno
postal_codestringno
citystringno
vaxa_stod_eligiblebooleanno
vaxa_stod_startstringno
vaxa_stod_endstringno
jamkning_percentagenumber | nullno
jamkning_valid_fromstring | nullno
jamkning_valid_tostring | nullno
extra_tax_amountnumber | nullno
extra_tax_percentagenumber | nullno
default_dimensionsobjectno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this employee: emp_ plus its id as 32 lowercase hex. Accepted wherever the id is.
first_namestring
last_namestring
personnummer_maskedstring
employment_type"employee" | "company_owner" | "board_member"
personnel_category"arbetare" | "tjansteman"
employment_startstring
employment_endstring | null
employment_degreenumber
salary_type"monthly" | "hourly"
monthly_salarynumber | null
hourly_ratenumber | null
tax_table_numbernumber | null
tax_columnnumber | null
tax_municipalitystring | null
is_sidoinkomstboolean
f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"
vacation_rulestring
vacation_days_per_yearnumber
is_activeboolean
created_atstring

Example request

{
  "first_name": "Anna",
  "last_name": "Andersson",
  "personnummer": "YYYYMMDDNNNN",
  "employment_type": "employee",
  "employment_start": "2024-01-15",
  "salary_type": "monthly",
  "monthly_salary": 35000,
  "tax_table_number": 33,
  "tax_column": 1,
  "tax_municipality": "Stockholm"
}

Example response

{
  "data": {
    "id": "a8f1…",
    "first_name": "Anna",
    "last_name": "Andersson",
    "personnummer_masked": "YYYYMMDD-XXXX",
    "employment_type": "employee",
    "personnel_category": "tjansteman",
    "employment_start": "2024-01-15",
    "employment_end": null,
    "employment_degree": 100,
    "salary_type": "monthly",
    "monthly_salary": 35000,
    "hourly_rate": null,
    "tax_table_number": 33,
    "tax_column": 1,
    "tax_municipality": "Stockholm",
    "is_sidoinkomst": false,
    "f_skatt_status": "a_skatt",
    "vacation_rule": "procentregeln",
    "vacation_days_per_year": 25,
    "is_active": true,
    "created_at": "2024-01-15T08:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/employees/:id/benefits

employees.benefits.create · scope payroll:write

Register a benefit (förmån) on an employee.

Creates a standing monthly förmånsvärde row. benefit_type is one of bike, car, meals, housing, wellness, other. Every type except bike takes monthly_value: the schablon value you already know. bike takes annual_market_value and the server derives monthly_value = max(0, annual_market_value - 3000) / 12 (Skatteverket schablon, 3 000 kr/year tax-free), storing the inputs in metadata. Mandatory Idempotency-Key. Dry-runnable: the preview is the row that would be inserted, with the derived values.

Use when: "Anna gets a company car from January": register the schablon value once and every run inside the window derives the line. Also when migrating an employee register from another payroll system.

Don't use for: Computing a bilförmån from the car (nybilspris, miljöbil, fordonsskatt): do that with Skatteverket's calculator and send the result. Standing deductions such as a bruttolöneavdrag for the same car: the recurring-lines register. One-off taxable additions: edit the payslip lines on the run.

Pitfalls

  • The förmånsvärde is added to the employee's tax and arbetsgivaravgift basis when the run is calculated (POST /salary-runs/{id}/calculate): skatteavdrag and avgifter go up, nothing is paid out. Registering a benefit does not recompute an open run; call :calculate afterwards.
  • car (bilförmån) is supplied as the monthly schablon value you computed (Skatteverket's bilförmånsberäkning, including miljöbil and 30 000 km reductions); the API does not compute it from the car.
  • bike takes annual_market_value, not monthly_value: the server derives the monthly value with the 3 000 kr/year tax-free allowance. A monthly_value sent next to annual_market_value on a bike row is ignored.
  • valid_from / valid_to gate which runs pick the row up: a run derives the line when valid_from <= payment_date <= valid_to (valid_to omitted = open-ended). Both dates are inclusive; valid_to before valid_from is 400 VALIDATION_ERROR.
  • To stop a benefit that already fed a calculated run, PATCH is_active=false or set valid_to; DELETE on such a row keeps and deactivates it rather than removing it. Either way the derived line stays on a draft run until POST /salary-runs/{id}/calculate is called again, which drops it (#2695).

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other"yes
descriptionstringyes
monthly_valuenumberno
annual_market_valuenumberno
valid_fromstringyes
valid_tostringno
metadataobjectno
is_activebooleanno

Response fields

NameType
employee_benefit_idstring
benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other"
descriptionstring
monthly_valuenumber
annual_market_valuenumber | null
valid_fromstring
valid_tostring | null
is_activeboolean
metadataobject
created_atstring
updated_atstring

Example request

{
  "benefit_type": "bike",
  "description": "Cykelförmån",
  "annual_market_value": 15000,
  "valid_from": "2026-03-01"
}

Example response

{
  "data": {
    "employee_benefit_id": "ben_91d2…",
    "benefit_type": "bike",
    "description": "Cykelförmån",
    "monthly_value": 1000,
    "annual_market_value": 15000,
    "valid_from": "2026-03-01",
    "valid_to": null,
    "is_active": true,
    "metadata": {
      "annual_market_value": 15000,
      "annual_taxable": 12000,
      "tax_free_portion": 3000
    },
    "created_at": "2026-02-20T10:00:00Z",
    "updated_at": "2026-02-20T10:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/employees/:id/recurring-lines

employees.recurring-lines.create · scope payroll:write

Create a recurring payslip line for an employee.

Adds a standing monthly payslip row. From the next :calculate on, every salary run whose payment_date falls inside valid_from..valid_to derives a payslip line from it, with flags (taxable, avgift basis, gross vs net deduction) fixed by item_type. Amounts are kept to whole öre. A text row (item_type text) carries words only (no amount, account or flags) and is printed under the base salary on every payslip, without reaching tax, AGI or the booking. Requires an Idempotency-Key header.

Use when: An employee starts a benefit bike bruttolöneavdrag, a union fee, a monthly net deduction for a benefit they pay for, or any other deduction that repeats every month until further notice; or every payslip should explain how the salary is built up (item_type text).

Don't use for: One-off deductions on a single payslip: add a line on the salary run instead. Additions (a personligt tillägg, a monthly allowance paid in cash): not supported as recurring lines; a standing raise goes on monthly_salary (PATCH /employees/{id}) and a one-off addition on the salary run. Taxable benefits in kind: use the employee benefits endpoints.

Pitfalls

  • Rows are re-derived on every :calculate for runs whose payment_date falls inside valid_from..valid_to (valid_to null = open-ended). Hand edits to a derived payslip row are overwritten by the next :calculate.
  • The amount follows the item type: a deduction is negative (e.g. -670.17 for a benefit bike bruttolöneavdrag), and a text row (item_type text) has none: omit amount (0 is accepted) and put the words in description, e.g. how the salary is built up. The API rejects the wrong sign, or an amount on a text row, with 400 VALIDATION_ERROR on field amount.
  • Recurring additions (a personligt tillägg next to Grundlön, a cash allowance) are not supported: proration, absence deductions, sjuklön, semestertillägg and the OB rate read only monthly_salary, so a standing tillägg row would be paid in full through sick leave. Put a standing raise on the employee's monthly_salary and explain the split with a text row.
  • account_number overrides the default BAS account for the derived payslip row; null lets the engine use its item-type mapping. A text row has no account: account_number is ignored.
  • Draft-only per-run edits (a one-off change on one payslip) still go through the salary-runs lines endpoints, not through recurring lines.
  • valid_to must be on or after valid_from (inclusive); omit it for an open-ended line.
  • Creating a line does not recompute an open salary run: call POST /salary-runs/{id}/calculate afterwards.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
item_type"gross_deduction_pension" | "gross_deduction_other" | "net_deduction_union" | "net_deduction_benefit_payment" | "net_deduction_other" | "text"yes
descriptionstringyes
amountnumberno
account_numberstringno
benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other"nonet_deduction_benefit_payment only: the benefit this payment is for. Required when the employee has several benefit types.
valid_fromstringyes
valid_tostringno
metadataobjectno
is_activebooleanno

Response fields

NameType
employee_recurring_line_idstring
item_type"gross_deduction_pension" | "gross_deduction_other" | "net_deduction_union" | "net_deduction_benefit_payment" | "net_deduction_other" | "text"
descriptionstring
amountnumber
account_numberstring | null
valid_fromstring
valid_tostring | null
is_activeboolean
metadataobject
created_atstring
updated_atstring

Example request

{
  "item_type": "gross_deduction_other",
  "description": "Förmånscykel bruttolöneavdrag",
  "amount": -670.17,
  "valid_from": "2026-01-01"
}

Example response

{
  "data": {
    "employee_recurring_line_id": "erl_5b1c…",
    "item_type": "gross_deduction_other",
    "description": "Förmånscykel bruttolöneavdrag",
    "amount": -670.17,
    "account_number": null,
    "valid_from": "2026-01-01",
    "valid_to": null,
    "is_active": true,
    "metadata": {}
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/employees

salary-runs.employees.add · scope payroll:write

Add an employee to a draft salary run.

Attaches an active employee to a draft run: snapshots their pay configuration (salary, degree, tax table) onto the run and seeds the base salary line (Grundlön/Timlön). For hourly employees, pass hours_worked.

Use when: The run was created without this employee (e.g. hired after the run was drafted), or you create runs empty and attach employees one by one from an external system.

Don't use for: Changing an attached employee's pay for this month (internal per-run PATCH; not on v1). Re-attaching after removal is fine: the snapshot is retaken.

Pitfalls

  • Draft-only: 400 SALARY_RUN_EMPLOYEES_NOT_DRAFT once the run has advanced.
  • Attaching twice returns 409 SALARY_RUN_EMPLOYEE_DUPLICATE.
  • The snapshot freezes salary/degree/tax-table at attach time: later employee edits do not flow into this run.
  • Inactive (soft-deleted) employees cannot be attached: 404 EMPLOYEE_NOT_FOUND.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
employee_idstringyes
hours_workednumberno

Response fields

NameType
salary_run_employee_idstring | null
employee_idstring
salary_typestring
employment_degreenumber
monthly_salarynumber
hours_workednumber | null
tax_table_numbernumber | null
tax_columnnumber | null

Example request

{
  "employee_id": "emp_77b2…"
}

Example response

{
  "data": {
    "salary_run_employee_id": "sre_a8f1…",
    "employee_id": "emp_77b2…",
    "salary_type": "monthly",
    "monthly_salary": 35000
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/employees/:employeeId/lines

salary-runs.lines.create · scope payroll:write

Add a payslip line to an employee in a draft salary run.

Creates a salary_line_items row (bonus, overtime, gross/net deduction, benefit, traktamente, text row, ...) for one employee in a draft run. account_number is an override only: omit it and the line returns account_number null and books on the default the booking resolves from item_type, the employee's employment_type and personnel_category (an arbetare's wages on 7010, a tjänsteman's on 7210, an owner's on 7220). Amounts are rounded to whole öre, and every line but a text row needs a non-zero amount (a vacation line may carry only its days). The row's flags (is_taxable, is_avgift_basis, is_vacation_basis, is_gross_deduction, is_net_deduction) follow from item_type and come back in the answer; flags in the body are ignored. A text row (item_type text, Textrad) carries words only: no amount, quantity or unit_price and no account, so it explains the payslip without reaching tax, AGI or the booking. one_off_tax_percent (engångsskatt) taxes the line at that verified flat percentage instead of the monthly table; allowed on a positive taxable bonus, commission, other, correction or semesterersattning line. A vacation line (item_type vacation, quantity = days) may carry vacation_category to say which pool the days come from: paid (Betalda, the default), extra_paid (Extra betalda), saved (Sparade, optionally one origin year in vacation_saved_year), unpaid (Obetalda) or advance (Förskott).

Use when: You need to add a one-off pay component before calculating: a bonus, an expense reimbursement, a union fee, or a manual correction line. A bonus or final-settlement semesterersättning that Skatteverket taxes as an engångsbelopp: send one_off_tax_percent with the percentage you verified for the employee. Vacation days taken: an item_type vacation line with quantity = days and, when they are not this year's paid days, vacation_category. Words on this payslip without money (how the salary is built up): an item_type text line.

Don't use for: Editing the base monthly salary (PATCH the run-employee via the internal surface; not on v1 yet). Absence: register absence days instead (PUT /employees/{id}/absence); the engine derives sick/VAB lines itself.

Pitfalls

  • Draft-only: returns 400 SALARY_RUN_LINE_NOT_DRAFT once the run has advanced.
  • Line edits do not recompute tax or totals: call POST /salary-runs/{id}/calculate afterwards. Until then the calculation is stale, and approve and book refuse the run.
  • A bruttolöneavdrag carries a negative amount; a positive one returns 400 VALIDATION_ERROR (details.field amount): pay handed back is a correction line. A nettolöneavdrag withholds at a negative amount and repays the employee at a positive one. A skattefri ersättning or a förmån is positive; a negative one returns 400 VALIDATION_ERROR.
  • A 0 kr line is refused with 400 VALIDATION_ERROR (details.field amount), also when the amount rounds to 0 at whole öre, and so is a line without amount: every line but a text row needs a non-zero amount, except a vacation line carrying its days in quantity. For words without money use item_type text.
  • A text row (item_type text): description is the whole row, at most 200 characters, line breaks become spaces. Omit amount (0 is accepted), quantity and unit_price, otherwise 400 VALIDATION_ERROR. account_number is ignored: the row is stored with account_number null. A standing text on every payslip is a recurring line (POST /employees/{id}/recurring-lines).
  • Engine-derived lines (absence, benefits, the semesterersättning row under vacation_rule semesterersattning) are regenerated on every :calculate; manual lines survive, including a semesterersattning line you add yourself.
  • The pay type prices the base salary itself: a monthly_salary line on a monthly-paid employee or an hourly_salary line on an hourly-paid one returns 400 VALIDATION_ERROR (details.field item_type). Extra hours at timlön on a monthly-paid employee are an hourly_salary line (quantity = hours, amount = hours × timlön), paid like an other line.
  • The calculation owns the absence types (sick_karens, sick_day2_14, sick_day15_plus, vab, parental_leave, unpaid_leave) and the shift-premium types (overtime_50, overtime_100, ob_weekday_evening, ob_weekend, ob_night, ob_holiday): a line of those types returns 400 SALARY_LINE_CALCULATED. Register absence or worked hours instead, or put a one-off övertid or OB amount on item_type overtime or other.
  • one_off_tax_percent is the percentage YOU verified against Skatteverket's engångsbelopp table for the employee's yearly income; the API never estimates it. It is refused (400) on deductions, benefits, non-taxable rows and non-positive amounts. A valid jämkning decision on the employee overrides it. Equal percentages are summed before the öre are dropped, so splitting one bonus over two rows never changes the withholding.
  • vacation_category is only valid on item_type vacation (400 VALIDATION_ERROR otherwise) and vacation_saved_year only with category saved. Omitted category = paid. The vacation ledger splits the booked run's days by category: saved consumes the named origin year, or the oldest saved year first when omitted; unpaid and advance consume their own cutover pools.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
item_type"monthly_salary" | "hourly_salary" | "overtime" | "overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday" | "bonus" | "commission" | "gross_deduction_pension" | "gross_deduction_other" | "benefit_car" | "benefit_housing" | "benefit_meals" | "benefit_wellness" | "benefit_bike" | "benefit_other" | "sick_karens" | "sick_day2_14" | "sick_day15_plus" | "vab" | "parental_leave" | "vacation" | "semesterersattning" | "traktamente_taxfree" | "traktamente_taxable" | "mileage_taxfree" | "mileage_taxable" | "expense_reimbursement" | "net_deduction_advance" | "net_deduction_union" | "net_deduction_benefit_payment" | "net_deduction_other" | "correction" | "other" | "text"yes
descriptionstringyes
quantitynumberno
unit_pricenumberno
amountnumberno
account_numberstringno
sort_ordernumberno
one_off_tax_percentnumber | nullno
vacation_category"paid" | "extra_paid" | "saved" | "unpaid" | "advance" | nullno
vacation_saved_yearstring | nullno

Response fields

NameType
salary_line_item_idstring | null
salary_run_employee_idstring
item_typestring
descriptionstring
quantitynumber | null
unit_pricenumber | null
amountnumber
is_taxableboolean
is_avgift_basisboolean
is_vacation_basisboolean
is_gross_deductionboolean
is_net_deductionboolean
account_numberstring | null
sort_ordernumber
one_off_tax_percentnumber | null (optional)
vacation_categorystring | null (optional)
vacation_saved_yearstring | null (optional)

Example request

{
  "item_type": "bonus",
  "description": "Kvartalsbonus Q2",
  "amount": 5000,
  "one_off_tax_percent": 30
}

Example response

{
  "data": {
    "salary_line_item_id": "sli_31c9…",
    "item_type": "bonus",
    "description": "Kvartalsbonus Q2",
    "amount": 5000,
    "account_number": null,
    "one_off_tax_percent": 30
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/employees/:id

employees.update · scope payroll:write

Update an employee.

Partial update of an employee. Only the fields supplied in the body are changed: an omitted key is left unchanged, and an explicit null clears a nullable field (employment_end, salary amounts, tax table and municipality, bank details, contact details, Växa-stöd and jämkning dates). is_active: true reactivates a soft-deleted employee, and is_active: false deactivates one exactly as DELETE does. Supports ?dry_run=true to validate the merged record without committing. Personnummer changes are NOT permitted via this endpoint: the natural-person identity is immutable post-creation.

Use when: You need to change tax configuration, bank details, salary amount, or contact info on an existing employee, or to reactivate an employee that was soft-deleted.

Don't use for: Changing personnummer (not supported: create a new employee if the natural-person identity changes, which is a rare edge case).

Pitfalls

  • is_active only decides whether the employee is on active rosters and picked up by NEW salary runs. Reactivating does not add the employee to a salary run that already exists: add them to a draft run with POST /salary-runs/{id}/employees. A run also leaves out an employee whose employment_end is before the pay period, active or not.
  • personnummer in the body is ignored by this endpoint. To change it you must DELETE and recreate.
  • salary_type changes require the matching salary field in the same request: switching to monthly without monthly_salary returns 400.
  • A cleared field is checked against the stored row: nulling monthly_salary on a monthly employee, tax_table_number on an A-skatt employee without sidoinkomst, vaxa_stod_start while Växa-stöd is on, or only one of clearing_number/bank_account_number returns 400. To end an ongoing employment set employment_end; to reopen it send employment_end: null.
  • tax_table_number changes only take effect on future salary runs; runs already in review or beyond use a frozen snapshot.
  • extra_tax_amount and extra_tax_percentage are exclusive: setting one while the other is stored returns 400, so send the other as null in the same PATCH. A draft run picks the change up at its next calculation.
  • personnel_category (arbetare or tjansteman) is read when a salary run is booked: every unbooked run, including one already approved or paid, books on the new category. A booked run keeps the category it was booked with.
  • fora_fok_id (FOK plus six digits, from Fora's Mina sidor) and fora_fok_start_date go together: one without the other returns 400, and so does a code on company_owner or board_member. Changing employment_type away from employee needs fora_fok_id: null in the same PATCH. With a code the employee is in the monthly Fora report (GET /salary/fora-report).
  • An enskild firma cannot employ its owner or board: employment_type company_owner or board_member returns 400 VALIDATION_ERROR on employment_type (the owner takes eget uttag, not salary).
  • Changing employment_degree on a sammaloneregeln employee returns 400 EMPLOYEE_SAMMALONEREGELN_DEGREE_CHANGED (semesterlagen 16 § second paragraph points 3-4 then calculates holiday pay under procentregeln). Send vacation_rule: "procentregeln" in the same PATCH, or sammaloneregeln_kollektivavtal_confirmed: true when a central kollektivavtal keeps sammalöneregeln (2 a §); the confirmation is recorded in the audit trail. hours_per_week and workdays_per_week do not trigger it.
  • vaxa_stod_eligible never lowers the arbetsgivaravgifter: from redovisningsperiod 202601 (Lag 2025:1334) the AGI declares the full avgifter and the company applies to Skatteverket for the refund after filing. A salary run paid inside vaxa_stod_start..vaxa_stod_end (end optional; never past the 24th calendar month counted from the start month) notes the expected refund per employee and warns to apply.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
first_namestringno
last_namestringno
personnummerstringno
employment_type"employee" | "company_owner" | "board_member"no
personnel_category"arbetare" | "tjansteman"no
employment_startstringno
employment_endstring | nullno
employment_degreenumberno
hours_per_weeknumberno
workdays_per_weeknumberno
salary_type"monthly" | "hourly"no
monthly_salarynumber | nullno
hourly_ratenumber | nullno
tax_table_numbernumber | nullno
tax_columnnumberno
tax_municipalitystring | nullno
is_sidoinkomstbooleanno
f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"no
clearing_numberstring | nullno
bank_account_numberstring | nullno
vacation_rule"procentregeln" | "sammaloneregeln" | "none" | "semesterersattning"no
vacation_days_per_yearnumberno
semestertillagg_ratenumberno
vacation_pay_ratenumber | nullno
fora_fok_idstring | nullno
fora_fok_start_datestring | nullno
emailstring | nullno
phonestring | nullno
address_line1string | nullno
postal_codestring | nullno
citystring | nullno
vaxa_stod_eligiblebooleanno
vaxa_stod_startstring | nullno
vaxa_stod_endstring | nullno
jamkning_percentagenumber | nullno
jamkning_valid_fromstring | nullno
jamkning_valid_tostring | nullno
extra_tax_amountnumber | nullno
extra_tax_percentagenumber | nullno
default_dimensionsobjectno
is_activebooleanno
sammaloneregeln_kollektivavtal_confirmedbooleanno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this employee: emp_ plus its id as 32 lowercase hex. Accepted wherever the id is.
first_namestring
last_namestring
employment_type"employee" | "company_owner" | "board_member"
personnel_category"arbetare" | "tjansteman"
employment_startstring
employment_endstring | null
employment_degreenumber
hours_per_weeknumber
workdays_per_weeknumber
salary_type"monthly" | "hourly"
monthly_salarynumber | null
hourly_ratenumber | null
tax_table_numbernumber | null
tax_columnnumber | null
tax_municipalitystring | null
is_sidoinkomstboolean
f_skatt_status"a_skatt" | "f_skatt" | "fa_skatt" | "not_verified"
clearing_numberstring | null
bank_account_numberstring | null
vacation_rulestring
vacation_days_per_yearnumber
semestertillagg_ratenumber
vacation_pay_ratenumber | null
emailstring | null
phonestring | null
address_line1string | null
postal_codestring | null
citystring | null
fora_fok_idstring | null
fora_fok_start_datestring | null
vaxa_stod_eligibleboolean
vaxa_stod_startstring | null
vaxa_stod_endstring | null
jamkning_percentagenumber | null
jamkning_valid_fromstring | null
jamkning_valid_tostring | null
extra_tax_amountnumber | null
extra_tax_percentagenumber | null
default_dimensionsobject
is_activeboolean
created_atstring
updated_atstring
personnummer_maskedstring

Example request

{
  "monthly_salary": 38000,
  "tax_municipality": "Göteborg"
}

Example response

{
  "data": {
    "id": "a8f1…",
    "monthly_salary": 38000
  }
}

PATCH /api/v1/companies/:companyId/employees/:id/benefits/:benefitId

employees.benefits.update · scope payroll:write

Partially update a benefit (förmån) on an employee.

Patches the supplied fields: description, monthly_value, valid_from, valid_to (null clears it), is_active, metadata, and for bike rows annual_market_value (the server re-derives monthly_value). benefit_type is not patchable: delete and recreate to change the kind. Mandatory Idempotency-Key. Dry-runnable: the preview is the merged row.

Use when: The förmånsvärde changes (new schablon for the year, a new bike price), the benefit ends (set valid_to), or you want to pause it without losing the row (is_active=false).

Don't use for: Changing the benefit kind (delete + create). Editing the derived line on one specific run: edit the payslip line on that run instead, the register stays as is.

Pitfalls

  • Idempotency-Key is mandatory; calls without it return 400.
  • valid_from and valid_to are checked against the MERGED stored+patched pair: a valid_to-only patch that predates the stored valid_from is 400 VALIDATION_ERROR (field valid_to).
  • annual_market_value is accepted on bike rows only (400 otherwise) and overrides any monthly_value in the same body.
  • The förmånsvärde is added to the tax and arbetsgivaravgift basis at :calculate; a change here does not recompute an open run. Call POST /salary-runs/{id}/calculate afterwards.
  • To stop a benefit that a calculated run already consumed, set is_active=false or valid_to here; DELETE on such a row also keeps and deactivates it rather than removing it. Either way the derived line stays on a draft run until POST /salary-runs/{id}/calculate is called again, which drops it (#2695).

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
descriptionstringno
monthly_valuenumberno
annual_market_valuenumberno
valid_fromstringno
valid_tostring | nullno
metadataobjectno
is_activebooleanno

Response fields

NameType
employee_benefit_idstring
benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other"
descriptionstring
monthly_valuenumber
annual_market_valuenumber | null
valid_fromstring
valid_tostring | null
is_activeboolean
metadataobject
created_atstring
updated_atstring

Example request

{
  "valid_to": "2026-06-30"
}

Example response

{
  "data": {
    "employee_benefit_id": "ben_4f2a…",
    "benefit_type": "car",
    "description": "Bilförmån Volvo XC40",
    "monthly_value": 4275,
    "annual_market_value": null,
    "valid_from": "2026-01-01",
    "valid_to": "2026-06-30",
    "is_active": true,
    "metadata": {},
    "created_at": "2026-01-05T09:12:00Z",
    "updated_at": "2026-06-02T14:40:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/employees/:id/recurring-lines/:lineId

employees.recurring-lines.update · scope payroll:write

Update a recurring payslip line.

Patches description, amount, account_number, valid_from, valid_to, is_active or metadata on a recurring line. The amount sign is re-checked against the stored item_type and the validity period against the merged (stored + patched) dates. A text row keeps no amount (anything but 0 is refused) and no account (account_number is ignored). item_type cannot change: delete and recreate instead. Requires an Idempotency-Key header.

Use when: The monthly deduction changed (new bike lease amount), the line ends on a known date (set valid_to), or it should pause without losing history (is_active=false).

Don't use for: Changing the kind of line (gross to net deduction): DELETE and POST a new one. Fixing one payslip only: edit the salary run line instead.

Pitfalls

  • Rows are re-derived on every :calculate for runs whose payment_date falls inside valid_from..valid_to (valid_to null = open-ended). Hand edits to a derived payslip row are overwritten by the next :calculate.
  • The amount follows the item type: a deduction is negative (e.g. -670.17 for a benefit bike bruttolöneavdrag), and a text row (item_type text) has none: omit amount (0 is accepted) and put the words in description, e.g. how the salary is built up. The API rejects the wrong sign, or an amount on a text row, with 400 VALIDATION_ERROR on field amount.
  • Recurring additions (a personligt tillägg next to Grundlön, a cash allowance) are not supported: proration, absence deductions, sjuklön, semestertillägg and the OB rate read only monthly_salary, so a standing tillägg row would be paid in full through sick leave. Put a standing raise on the employee's monthly_salary and explain the split with a text row.
  • account_number overrides the default BAS account for the derived payslip row; null lets the engine use its item-type mapping. A text row has no account: account_number is ignored.
  • Draft-only per-run edits (a one-off change on one payslip) still go through the salary-runs lines endpoints, not through recurring lines.
  • A patch that leaves valid_to before valid_from on the merged row is rejected with 400 VALIDATION_ERROR on field valid_to; send valid_to: null to make the line open-ended again.
  • Runs already calculated keep their derived rows until they are recalculated; booked runs are never touched.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
descriptionstringno
amountnumberno
account_numberstring | nullno
benefit_type"bike" | "car" | "meals" | "housing" | "wellness" | "other" | nullno
valid_fromstringno
valid_tostring | nullno
metadataobjectno
is_activebooleanno

Response fields

NameType
employee_recurring_line_idstring
item_type"gross_deduction_pension" | "gross_deduction_other" | "net_deduction_union" | "net_deduction_benefit_payment" | "net_deduction_other" | "text"
descriptionstring
amountnumber
account_numberstring | null
valid_fromstring
valid_tostring | null
is_activeboolean
metadataobject
created_atstring
updated_atstring

Example request

{
  "amount": -700,
  "valid_to": "2026-12-31"
}

Example response

{
  "data": {
    "employee_recurring_line_id": "erl_5b1c…",
    "item_type": "gross_deduction_other",
    "description": "Förmånscykel bruttolöneavdrag",
    "amount": -700,
    "account_number": null,
    "valid_from": "2026-01-01",
    "valid_to": "2026-12-31",
    "is_active": true,
    "metadata": {}
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/salary-runs/:id/employees/:employeeId

salary-runs.employees.set-salary · scope payroll:write

Set this run's base salary for one employee.

Sets the per-run base salary (salary_run_employees.monthly_salary) that the calculation engine reads for this run. The employee master record is untouched, so each month's gross can differ from the employee's standard pay (variable owner salary). Draft-only; 0 is a valid nollkörning.

Use when: The employee's pay this month differs from their configured fixed salary: owners taking salary by need and capacity, one-off adjustments, or a deliberate zero month.

Don't use for: Changing the employee's standard salary going forward: PATCH /employees/{id}. Editing individual payslip lines (tillägg/avdrag): the lines endpoints. Tax/avgifter overrides in review: not exposed on v1 yet.

Pitfalls

  • Draft-only: 400 SALARY_RUN_EMPLOYEES_NOT_DRAFT once the run has advanced.
  • Run POST /calculate afterwards: gross, tax and totals reflect the new salary only after recalculation.
  • Do NOT edit the monthly_salary line item instead: recalculation rebuilds base salary lines from this per-run value.
  • For hourly employees the value is stored but gross derives from hours worked; the salary_type field in the response tells you which applies.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
monthly_salarynumberyes

Response fields

NameType
salary_run_employee_idstring
employee_idstring
salary_typestring
employment_degreenumber
previous_monthly_salarynumber
monthly_salarynumber

Example request

{
  "monthly_salary": 45000
}

Example response

{
  "data": {
    "salary_run_employee_id": "sre_a8f1…",
    "employee_id": "emp_77b2…",
    "salary_type": "monthly",
    "employment_degree": 100,
    "previous_monthly_salary": 30000,
    "monthly_salary": 45000
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PUT /api/v1/companies/:companyId/employees/:id/absence

employees.absence.upsert · scope payroll:write

Register absence for an employee over a date range.

Expands [from, to] (max 92 days) to per-day rows and upserts them on the natural key (employee, date, type). Weekends are skipped unless include_weekends=true. Single day = from == to. Idempotent by construction: replaying the same PUT converges on the same rows.

Use when: "Anna was sick 3-7 March": one call registers the whole event. Also for pre-cutover history backfill when migrating from another payroll system (any past date is legal; imported sick days feed the karensavdrag lookback).

Don't use for: Vacation day REQUESTS/approval workflows (out of scope). Editing hours on one existing day inside a range: PUT the single day (from == to) with the new hours.

Pitfalls

  • Weekends are skipped by default: pass include_weekends=true for schedules that span them.
  • Upsert REPLACES the (date, type) rows in the range: hours/notes are overwritten, not merged.
  • A day whose combined absence + worked hours exceed 24h returns 409 ABSENCE_HOURS_CONFLICT and the whole range is rejected (atomic).
  • Dates inside the avvikelseperiod (deviation window, deviation_period_start..deviation_period_end, NULL = the pay month) of a run that is already calculated (review), approved, paid or booked are locked: 409 SALARY_REGISTER_DATES_LOCKED_BY_RUN naming the run (details.salary_run_id, details.status, details.locked_dates), nothing written, dry runs included. The way out is to revert that run to draft (dashboard) or, for a booked run, POST /salary-runs/{id}/correct and register the days against the correction run. Draft runs never lock.
  • Registering absence does not recompute a draft salary run: call POST /salary-runs/{id}/calculate afterwards.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
fromstringyes
tostringyes
absence_type"sick" | "vab" | "parental" | "pregnancy" | "care_relative" | "study" | "unpaid_leave" | "other_leave"yes
hours_per_daynumbernoHours each day. Omitted: one scheduled day of the employee (hours_per_week / workdays_per_week).
notesstringno
include_weekendsbooleanno

Response fields

NameType
countnumber
daysobject[]

Example request

{
  "from": "2026-03-03",
  "to": "2026-03-07",
  "absence_type": "sick"
}

Example response

{
  "data": {
    "count": 5,
    "days": [
      {
        "absence_date": "2026-03-03",
        "absence_type": "sick",
        "hours": 8
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PUT /api/v1/companies/:companyId/employees/:id/opening-balances

employees.opening-balances.set · scope payroll:write

Set an employee's payroll cutover opening balances.

Full-replace upsert of the cutover state: YTD gross/tax/net for the cutover year, the vacation pools in the previous system's own terms (vacation_paid_days_remaining = Betalda, vacation_saved_days_by_year = Sparade per år, vacation_unpaid_days_remaining = Obetalda, vacation_advance_days_remaining = Förskott, vacation_extra_paid_days_remaining = Extra betalda), paid days already taken this vacation year, vacation_as_of_date (the day those pools are struck per), opening semesterlöneskuld SEK (+avgifter), opening_advance_vacation_debt (förskottsskuld SEK), and karens periods not covered by imported absence rows. cutover_date must be the first of a month in the current or previous year, on/after employment_start.

Use when: Onboarding one employee during a mid-year migration from Fortnox/Azets/Visma/etc. For whole-company onboarding, prefer the bulk PUT /employees/opening-balances.

Don't use for: SIE opening balances on the LEDGER (2920/2940 arrive via the SIE import). Ongoing sick cases: import pre-cutover days via PUT /employees/{id}/absence instead.

Pitfalls

  • Full replace: omitted numeric fields reset to 0 (their defaults) and an omitted vacation_as_of_date resets to null. Send the complete state every time.
  • vacation_as_of_date defaults to the day before cutover_date. Booked runs whose avvikelseperiod ends on or before it are treated as already inside the balance and not deducted again, so with salary_deviation_period = previous_month send the last day BEFORE the month the first run deducts (cutover 2026-09-01, first run deducts August: send 2026-07-31) or August's leave is never deducted.
  • ytd_net: send null when the previous system cannot export historical net pay; the payslip prints "Underlag saknas" instead of a false 0. Never send gross minus tax as net.
  • 409 OPENING_BALANCES_LOCKED once the employee has a booked run; correcting that run unlocks.
  • The opening liability and the förskottsskuld are NOT booked by Accounted: they only feed the vacation-liability report (the förskottsskuld as its own row, subtracted from the net liability).
  • Extra betalda join the paid pool: the ledger's entitled days = Betalda + Extra betalda + days already taken. Obetalda lapse at the vacation-year close; Förskott days taken reduce the next year's entitlement.
  • YTD affects payslip display and reports only; per-month tax and avgifter caps never read it.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
cutover_datestringyes
ytd_grossnumberno
ytd_taxnumberno
ytd_netnumber | nullno
vacation_paid_days_remainingnumberno
vacation_days_taken_this_yearnumberno
vacation_saved_days_by_yearobjectno
opening_semester_liabilitynumberno
opening_semester_liability_avgifternumberno
karens_periods_adjustmentnumberno
vacation_as_of_datestring | nullno
vacation_unpaid_days_remainingnumberno
vacation_advance_days_remainingnumberno
vacation_extra_paid_days_remainingnumberno
opening_advance_vacation_debtnumberno

Response fields

NameType
employee_opening_balances_idstring | null
employee_idstring
cutover_datestring
ytd_grossnumber
ytd_taxnumber
ytd_netnumber | null
vacation_paid_days_remainingnumber
vacation_days_taken_this_yearnumber
vacation_saved_days_by_yearobject
opening_semester_liabilitynumber
opening_semester_liability_avgifternumber
karens_periods_adjustmentnumber
vacation_as_of_datestring | null
vacation_unpaid_days_remainingnumber
vacation_advance_days_remainingnumber
vacation_extra_paid_days_remainingnumber
opening_advance_vacation_debtnumber
lockedboolean
locked_by_run_idstring | null

Example request

{
  "cutover_date": "2026-09-01",
  "ytd_gross": 280000,
  "ytd_tax": 64000,
  "ytd_net": 216000,
  "vacation_as_of_date": "2026-07-31",
  "vacation_paid_days_remaining": 12.5,
  "vacation_days_taken_this_year": 10,
  "vacation_extra_paid_days_remaining": 2,
  "vacation_saved_days_by_year": {
    "2025": 5
  },
  "vacation_unpaid_days_remaining": 0,
  "vacation_advance_days_remaining": 3,
  "opening_semester_liability": 42000,
  "opening_semester_liability_avgifter": 13196.4,
  "opening_advance_vacation_debt": 4500,
  "karens_periods_adjustment": 1
}

Example response

{
  "data": {
    "employee_id": "emp_77b2…",
    "cutover_date": "2026-07-01",
    "locked": false
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PUT /api/v1/companies/:companyId/employees/:id/worked-days

employees.worked-days.upsert · scope payroll:write

Register worked hours per day for an employee (bulk upsert).

Upserts 1..92 explicit per-day rows on the natural key (employee, work_date) in one atomic statement. A date already registered is overwritten with the new hours, shift window and notes (omitted optional fields are cleared, not carried forward). Idempotent by construction: replaying the same PUT converges on the same rows. Each work_date may appear once per request.

Use when: An external time-tracking or payroll system pushes an hourly employee's tidrapport for a period, including shift start/end times for OB (obekväm arbetstid) premiums, before the salary run is calculated.

Don't use for: Absence: PUT /employees/{id}/absence. Monthly-salaried staff without OB rules: their gross comes from the employee profile, not from this register.

Pitfalls

  • POST /salary-runs/{id}/calculate reads these rows by the run's deviation window (deviation_period_start..deviation_period_end), not the pay month: register the hours on the dates they were actually worked, and check the run's window before calculating.
  • For hourly employees the run's gross is derived from these rows (hourly_rate x sum(hours)): PATCH /salary-runs/{id}/employees/{employeeId} monthly_salary is irrelevant for them.
  • start_time/end_time feed the OB/shift-premium rules: a row without them is priced as an assumed 08:00-17:00 day, so a night or weekend shift earns no premium. Times are HH:MM or HH:MM:SS; end_time before start_time means the shift crosses midnight.
  • Worked hours plus absence hours on one date may not exceed 24 (DB trigger, shared with absence): the whole PUT is rejected with 409 ABSENCE_HOURS_CONFLICT, nothing is written.
  • Dates inside the avvikelseperiod (deviation window, deviation_period_start..deviation_period_end, NULL = the pay month) of a run that is already calculated (review), approved, paid or booked are locked: 409 SALARY_REGISTER_DATES_LOCKED_BY_RUN naming the run (details.salary_run_id, details.status, details.locked_dates), nothing written, dry runs included. The way out is to revert that run to draft (dashboard) or, for a booked run, POST /salary-runs/{id}/correct and register the days against the correction run. Draft runs never lock.
  • Registering hours does not recompute a draft salary run: call POST /salary-runs/{id}/calculate afterwards.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
daysobject[]yes

Response fields

NameType
countnumber
daysobject[]

Example request

{
  "days": [
    {
      "work_date": "2026-03-02",
      "hours": 8,
      "start_time": "22:00",
      "end_time": "06:00"
    },
    {
      "work_date": "2026-03-03",
      "hours": 4,
      "notes": "Halvdag"
    }
  ]
}

Example response

{
  "data": {
    "count": 2,
    "days": [
      {
        "salary_worked_day_id": "wd_91d2…",
        "work_date": "2026-03-02",
        "hours": 8,
        "start_time": "22:00:00",
        "end_time": "06:00:00",
        "notes": null
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PUT /api/v1/companies/:companyId/employees/opening-balances

employees.opening-balances.bulk-set · scope payroll:write

Bulk-set payroll cutover opening balances (atomic).

Upserts opening balances for up to 200 employees in one call. Validation is all-or-nothing: any invalid item (unknown/inactive employee, cutover before employment_start, locked by a booked run) fails the WHOLE request with a per-item error list and zero writes.

Use when: Onboarding a whole company mid-year from another payroll system: one call per migration file instead of N sequential PUTs.

Don't use for: Single-employee corrections after go-live: PUT /employees/{id}/opening-balances. Ledger opening balances (SIE import).

Pitfalls

  • Atomic: one bad item fails everything. The error details carry item_errors[{index, employee_id, code, message}]: fix and resubmit the full set.
  • Full replace per employee: resubmitting with fewer fields resets the omitted ones to 0 (vacation_as_of_date to null).
  • Duplicate employee_id within items is rejected outright.
  • Vacation pools map one to one onto Fortnox/Azets: vacation_paid_days_remaining = Betalda, vacation_saved_days_by_year = Sparade per år, vacation_unpaid_days_remaining = Obetalda, vacation_advance_days_remaining = Förskott, vacation_extra_paid_days_remaining = Extra betalda; opening_advance_vacation_debt is the förskottsskuld in SEK.
  • vacation_as_of_date is the day the pools are struck per (default: the day before cutover_date). Under salary_deviation_period = previous_month the first run deducts the month before cutover, so send the last day before that month or its leave is treated as already deducted.
  • ytd_net: null when the previous system cannot export historical net pay (payslip prints "Underlag saknas"); never gross minus tax.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
itemsobject[]yes

Response fields

NameType
countnumber
rowsobject[]

Example request

{
  "items": [
    {
      "employee_id": "emp_77b2…",
      "cutover_date": "2026-09-01",
      "ytd_gross": 280000,
      "ytd_tax": 64000,
      "ytd_net": null,
      "vacation_as_of_date": "2026-07-31",
      "vacation_paid_days_remaining": 12.5,
      "vacation_days_taken_this_year": 10,
      "vacation_saved_days_by_year": {
        "2025": 5
      },
      "vacation_unpaid_days_remaining": 0,
      "vacation_advance_days_remaining": 3,
      "vacation_extra_paid_days_remaining": 2,
      "opening_advance_vacation_debt": 4500
    }
  ]
}

Example response

{
  "data": {
    "count": 1,
    "rows": [
      {
        "employee_id": "emp_77b2…",
        "cutover_date": "2026-07-01",
        "locked": false
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/employees/:id

employees.delete · scope payroll:write

Soft-delete an employee.

Sets is_active=false. The row is preserved because past salary runs reference it via salary_run_employees and those verifikationer are räkenskapsinformation under BFL 7 kap (BFL retention attaches to the verifikationer themselves, not strictly to the personnummer attribute on the master row). Hard delete is never exposed.

Use when: An employee has left the company and should no longer appear in active rosters or default to new salary runs.

Don't use for: Reactivating later (PATCH is_active=true instead). Hard-deleting (not supported: retention).

Pitfalls

  • Idempotent: deleting an already-inactive employee returns 204 No Content (the same as the first call).
  • The row is NOT removed from the database: re-creating with the same personnummer returns 409 EMPLOYEE_DUPLICATE_PERSONNUMMER even after soft-delete.
  • Past salary runs still reference this employee; their data continues to surface in GET /salary-runs/{id} and SIE exports.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Example response

{
  "data": null
}

DELETE /api/v1/companies/:companyId/employees/:id/absence

employees.absence.delete · scope payroll:write

Delete absence days for an employee in a date range.

Deletes per-day absence rows between ?from and ?to (inclusive), optionally filtered by ?type. Returns deleted_count (200, not 204) so callers can verify how many rows went.

Use when: An absence event was registered by mistake or ended early: "Anna came back Thursday, delete Thu-Fri sick days".

Don't use for: Correcting hours on a day: PUT the day again instead. Rows a calculated, approved, paid or booked run has already read: the delete is refused (409 SALARY_REGISTER_DATES_LOCKED_BY_RUN); use the run correction flow.

Pitfalls

  • Without ?type, ALL absence types in the range are deleted.
  • deleted_count: 0 with a 200 means nothing matched: not an error.
  • Dates inside the avvikelseperiod (deviation window, deviation_period_start..deviation_period_end, NULL = the pay month) of a run that is already calculated (review), approved, paid or booked are locked: 409 SALARY_REGISTER_DATES_LOCKED_BY_RUN naming the run (details.salary_run_id, details.status, details.locked_dates), nothing written, dry runs included. The way out is to revert that run to draft (dashboard) or, for a booked run, POST /salary-runs/{id}/correct and register the days against the correction run. Draft runs never lock.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
fromstringyesYYYY-MM-DD. First day of the range (inclusive). Required.
tostringyesYYYY-MM-DD. Last day of the range (inclusive), not before from. Required.
type"sick" | "vab" | "parental" | "pregnancy" | "care_relative" | "study" | "unpaid_leave" | "other_leave"noOnly days of this absence type. Default: every type.
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
deleted_countnumber

Example response

{
  "data": {
    "deleted_count": 2
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/employees/:id/benefits/:benefitId

employees.benefits.delete · scope payroll:write

Remove a benefit (förmån) from an employee.

Removes the benefit from the employee, the same operation the dashboard performs. A row that no payslip line derives from is hard-deleted; a row that a calculated run already derived a line from is kept and switched off (is_active=false) so the line keeps its provenance. Answers 200 with the outcome, 404 NOT_FOUND when no such row exists on the employee. Mandatory Idempotency-Key. Dry-runnable: the preview is the row that would be removed.

Use when: A benefit was registered by mistake, or it ends and you do not need it listed as active any more. If it has been used by a calculated run it is deactivated rather than deleted.

Don't use for: Ending a benefit on a date while keeping it active until then: PATCH valid_to. Removing the derived line from one run: edit that run's payslip lines.

Pitfalls

  • Idempotency-Key is mandatory.
  • Answers 200 with { employee_benefit_id, deleted, deactivated }. A benefit that a payslip line already derives from is never hard-deleted: it is kept and switched off (deleted=false, deactivated=true), so the chain from a booked verifikat back to its förmån stays intact (BFL 5 kap 6-7 §). A second DELETE of a gone id returns 404 NOT_FOUND; a second DELETE of a deactivated row answers deactivated=true again.
  • Removing or deactivating a benefit does not recompute an open run: the derived line stays on a draft run until POST /salary-runs/{id}/calculate is called again, which drops it (#2695). A booked run is never changed.

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
employee_benefit_idstring
deletedboolean
deactivatedboolean

Example response

{
  "data": {
    "employee_benefit_id": "ben_9c2e…",
    "deleted": true,
    "deactivated": false
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/employees/:id/recurring-lines/:lineId

employees.recurring-lines.delete · scope payroll:write

Delete a recurring payslip line, or deactivate it if a run already used it.

Removes the line when no salary run has derived a payslip row from it. Once a run has (the derived row references the line), the database refuses the delete and the line is deactivated instead (is_active=false): the payslip row keeps its provenance, the next :calculate of a draft run drops the derived row, and nothing is re-derived. Returns 200 with deleted: true or deleted: false + deactivated: true so the caller knows which happened. Requires an Idempotency-Key header.

Use when: The deduction ends and there is no end date to keep (a union fee stops, the bike lease is returned), or the line was created by mistake.

Don't use for: Ending a line on a future date: PATCH valid_to instead, so the remaining months still derive. Removing a derived row from one draft payslip: DELETE the salary run line.

Pitfalls

  • Rows are re-derived on every :calculate for runs whose payment_date falls inside valid_from..valid_to (valid_to null = open-ended). Hand edits to a derived payslip row are overwritten by the next :calculate.
  • The amount follows the item type: a deduction is negative (e.g. -670.17 for a benefit bike bruttolöneavdrag), and a text row (item_type text) has none: omit amount (0 is accepted) and put the words in description, e.g. how the salary is built up. The API rejects the wrong sign, or an amount on a text row, with 400 VALIDATION_ERROR on field amount.
  • Recurring additions (a personligt tillägg next to Grundlön, a cash allowance) are not supported: proration, absence deductions, sjuklön, semestertillägg and the OB rate read only monthly_salary, so a standing tillägg row would be paid in full through sick leave. Put a standing raise on the employee's monthly_salary and explain the split with a text row.
  • account_number overrides the default BAS account for the derived payslip row; null lets the engine use its item-type mapping. A text row has no account: account_number is ignored.
  • Draft-only per-run edits (a one-off change on one payslip) still go through the salary-runs lines endpoints, not through recurring lines.
  • deleted: false with deactivated: true is a success, not an error: a run already derived from the line, so it is kept for history and switched off.
  • A lineId under another employee or company answers 404 NOT_FOUND.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
employee_recurring_line_idstring
deletedboolean
deactivatedtrue (optional)

Example response

{
  "data": {
    "employee_recurring_line_id": "erl_5b1c…",
    "deleted": true
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/employees/:id/worked-days

employees.worked-days.delete · scope payroll:write

Delete worked days for an employee in a date range.

Deletes the per-day worked-hours rows between ?from and ?to (inclusive). Returns deleted_count (200, not 204) so callers can verify how many rows went. Single day = from == to.

Use when: Hours were pushed for the wrong employee or the wrong dates, or a time-tracking re-sync needs a clean period before a fresh PUT.

Don't use for: Correcting hours on a day: PUT the day again instead. Rows a calculated, approved, paid or booked run has already read: the delete is refused (409 SALARY_REGISTER_DATES_LOCKED_BY_RUN); use the run correction flow.

Pitfalls

  • deleted_count: 0 with a 200 means nothing matched: not an error.
  • Dates inside the avvikelseperiod (deviation window, deviation_period_start..deviation_period_end, NULL = the pay month) of a run that is already calculated (review), approved, paid or booked are locked: 409 SALARY_REGISTER_DATES_LOCKED_BY_RUN naming the run (details.salary_run_id, details.status, details.locked_dates), nothing written, dry runs included. The way out is to revert that run to draft (dashboard) or, for a booked run, POST /salary-runs/{id}/correct and register the days against the correction run. Draft runs never lock.
  • Hours a draft run has already summed stay in the run until POST /salary-runs/{id}/calculate is called again.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
fromstringyesYYYY-MM-DD. First day of the range (inclusive). Required.
tostringyesYYYY-MM-DD. Last day of the range (inclusive), not before from. Required.
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
deleted_countnumber

Example response

{
  "data": {
    "deleted_count": 2
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/salary-runs/:id/employees/:employeeId

salary-runs.employees.remove · scope payroll:write

Remove an employee from a draft salary run.

Detaches the employee from the run and cascades away their payslip line items. Draft-only. The employee master record is untouched: this only affects the run roster.

Use when: An employee should not be paid this period (unpaid leave the whole month, employment ended) but was auto-added when the run was created.

Don't use for: Deactivating the employee entirely: DELETE /employees/{id} (soft-delete). Zero-salary months: keep them in the run with a 0 base instead if you want a nollkörning on record.

Pitfalls

  • Draft-only: 400 SALARY_RUN_EMPLOYEES_NOT_DRAFT once the run has advanced.
  • Cascade-deletes the employee's line items in this run, including manual ones.
  • Re-attaching later retakes the pay snapshot from the employee master.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Example response

{
  "data": null
}