Menu

Salary runs

Payroll lifecycle: create, calculate, approve, mark paid, book, generate AGI XML, and close the vacation year.

Endpoints


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

salary-runs.list · scope payroll:read

List salary runs.

Returns salary runs in created-first order with their lifecycle status (draft|review|approved|paid|booked|corrected) and denormalised totals. Filters: ?period_year=YYYY, ?status=draft.

Use when: You need an overview of payroll activity: for building a list view, finding the current open run, or resolving a salary_run_id before invoking a lifecycle verb.

Don't use for: Per-employee details (those live on the detail endpoint). Salary journal report (use GET /reports/salary-journal in Phase 5 PR-3).

Pitfalls

  • A company has at most one salary run per (period_year, period_month). The unique constraint is at the DB layer.
  • Totals are denormalised: they are 0 until POST /calculate runs.
  • corrected status is reached via the internal /correct route (not yet exposed on v1): Phase 5 PR-1 ships create/calculate/approve/mark-paid/book/generate-agi only.

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

Query parameters

NameTypeRequiredDescription
period_yearnumbernoOnly runs for this payroll year (2020-2100).
status"draft" | "review" | "approved" | "paid" | "booked" | "corrected"noOnly runs in this status.
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 salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
[].period_yearnumber
[].period_monthnumber
[].payment_datestring
[].deviation_period_startstring | null
[].deviation_period_endstring | null
[].status"draft" | "review" | "approved" | "paid" | "booked" | "corrected"
[].voucher_seriesstring
[].total_grossnumber
[].total_taxnumber
[].total_netnumber
[].total_avgifternumber
[].total_employer_costnumber
[].agi_generated_atstring | null
[].agi_submitted_atstring | null
[].approved_atstring | null
[].paid_atstring | null
[].booked_atstring | null
[].created_atstring

Example response

{
  "data": [
    {
      "id": "run_a8f1…",
      "period_year": 2026,
      "period_month": 5,
      "payment_date": "2026-05-25",
      "status": "draft",
      "voucher_series": "A",
      "total_gross": 0,
      "total_tax": 0,
      "total_net": 0,
      "total_avgifter": 0,
      "total_employer_cost": 0
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

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

salary-runs.get · scope payroll:read

Get a salary run.

Returns the salary run's lifecycle state, denormalised totals (gross/tax/net/avgifter/vacation/employer_cost), and references to the journal entries it produced (once :book has run).

Use when: You have a salary_run_id and need its current status: typically to decide which lifecycle verb to call next, or to display the run header in a UI.

Don't use for: Per-employee breakdown: use GET /salary-runs/{id}/employees (list) or /salary-runs/{id}/employees/{employeeId} (payslip detail). Salary journal report: use GET /reports/salary-journal.

Pitfalls

  • salary_entry_id / avgifter_entry_id / vacation_entry_id are null until POST /book has run. They reference the journal_entries table.
  • total_* fields are 0 until POST /calculate has run.

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

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
period_yearnumber
period_monthnumber
payment_datestring
deviation_period_startstring | null
deviation_period_endstring | null
status"draft" | "review" | "approved" | "paid" | "booked" | "corrected"
voucher_seriesstring
total_grossnumber
total_taxnumber
total_netnumber
total_avgifternumber
total_vacation_accrualnumber
total_employer_costnumber
salary_entry_idstring | null
avgifter_entry_idstring | null
vacation_entry_idstring | null
agi_generated_atstring | null
agi_submitted_atstring | null
calculation_paramsunknown (optional)
approved_bystring | null
approved_atstring | null
paid_atstring | null
booked_atstring | null
booked_bystring | null
notesstring | null
created_atstring
updated_atstring

Example response

{
  "data": {
    "id": "run_a8f1…",
    "period_year": 2026,
    "period_month": 5,
    "payment_date": "2026-05-25",
    "status": "approved",
    "total_gross": 105000,
    "total_tax": -28500,
    "total_net": 76500,
    "total_avgifter": 32991,
    "total_employer_cost": 137991
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/salary-runs/:id/payment-files

salary-runs.payment-files.list · scope payroll:read

List the archived bank payment files of a salary run.

Returns every payment file generated for the run (ISO 20022 pain.001 or Bankgirot LB), newest first, with the file content inline. Each row is an immutable archive copy written when the file was generated (BFL 7 kap. 1 §, seven-year retention): what was handed to the bank, byte for byte. sha256 and byte_size are over content encoded as charset (UTF-8 for pain001, ISO 8859-1 for bg_lb). Cursor pagination on (generated_at, id), newest first.

Use when: You need the file that was actually generated earlier (to re-upload, to verify a checksum against the bank portal, or to audit what the bank received) rather than a fresh build from the run's current data.

Don't use for: Generating a file: use POST /salary-runs/{id}/payment-file. Marking the run paid (:mark-paid) or booking it (:book). Supplier payment batches: use the supplier-invoice payment batch endpoints.

Pitfalls

  • An empty list means no file has been generated for the run yet (or the run predates the archive): generate one with POST /salary-runs/{id}/payment-file.
  • Rows are immutable and never deleted; a regeneration adds a new row. The newest row is not necessarily the one uploaded to the bank: compare sha256 with the checksum of the file you actually sent.
  • Write content to disk in charset (pain001 as UTF-8, bg_lb as ISO 8859-1 with CRLF line endings, exactly as returned); sha256 and byte_size describe those bytes, not the JSON string.
  • Every row carries the full file content, so page size matters for runs with many regenerations: use limit and the cursor.

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

NameType
[].payment_file_idstring
[].format"pain001" | "bg_lb"
[].filenamestring
[].content_type"application/xml" | "text/plain"
[].charset"utf-8" | "iso-8859-1"
[].sha256string
[].byte_sizenumber
[].payment_datestring
[].employee_countnumber
[].total_amountnumber
[].generated_atstring
[].versionnumber
[].previous_not_approved_confirmedboolean
[].contentstring

Example response

{
  "data": [
    {
      "payment_file_id": "f0f0f0f0-f0f0-4f0f-8f0f-f0f0f0f0f0f0",
      "format": "pain001",
      "filename": "pain001_lon_2026-05.xml",
      "content_type": "application/xml",
      "charset": "utf-8",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "byte_size": 2731,
      "payment_date": "2026-05-25",
      "employee_count": 3,
      "total_amount": 76500,
      "generated_at": "2026-05-20T08:00:00.000Z",
      "version": 1,
      "previous_not_approved_confirmed": false,
      "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn>…</CstmrCdtTrfInitn></Document>"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

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

salary-runs.payslip.pdf · scope payroll:read

Download one employee's payslip as PDF.

Returns the rendered payslip (lönespecifikation) as application/pdf, byte-equivalent to the dashboard download. Content-Disposition is attachment with a filename derived from the period and employee name.

Use when: You need the payslip document itself: archiving, forwarding to the employee outside the Accounted send flow (pass audience=employee), or attaching to an external HR system.

Don't use for: The payslip DATA (amounts, line items): use GET /salary-runs/{id}/employees/{employeeId}, which is cheaper and structured. Emailing payslips to employees: POST /salary-runs/{id}/send-payslips sends each a secure link.

Pitfalls

  • The PDF renders whatever the run currently holds: for a draft run that has not been calculated, amounts are 0.
  • PDF rendering takes a few hundred milliseconds; cache on the client if requesting repeatedly.
  • Without audience the PDF is the employer view and always prints Arbetsgivarkostnad and Beräkningsunderlag. A PDF you forward to the employee should use audience=employee, so it matches the emailed payslip link and honours the company's section switches.
  • audience=employee on an approved, paid or booked run, from a key that also holds payroll:write on a company it may write, issues the payslip: the first employee copy of the run (or the payslip email, whichever comes first) fixes which sections it prints, and every later employee copy of that run prints the same sections even after the company changes its switches. A key with only payroll:read (or a read-only membership or connection) never fixes anything: it gets the sections the run was issued with, or the current switches while the run is not issued yet. On a draft or review run the employee copy follows the current switches and fixes nothing.

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

Query parameters

NameTypeRequiredDescription
audience"employer" | "employee"noemployer (default): every section, the employer's own view. employee: the copy the employee receives; Arbetsgivarkostnad and Beräkningsunderlag follow salary_payslip_show_employer_cost / salary_payslip_show_breakdown (GET /salary/settings).

Example response

{
  "_note": "Returns application/pdf binary stream."
}

GET /api/v1/companies/:companyId/salary/fora-report

salary-runs.fora-report.get · scope payroll:read

The Fora monthly report for a payment month: each coded worker, their FOK code and the pay Fora is told about.

Employers with workers under Avtalspension SAF-LO (usually arbetare) report each worker's cash gross pay to Fora every month, by the last day of the month after the payment month, by uploading a JSON file on Fora's Mina sidor. This answers what that file says for one payment month: every employee with a Fora code (fora_fok_id on the employee) who was employed or paid in the month, their code, the pay in whole kronor and the employment end date, plus warnings to look at before uploading. The month is the payment month (payment_date), like the AGI; approved, paid and booked salary runs count. Pay is the bruttolön minus taxable traktamente and taxable car allowance, which Fora leaves out. Nothing is stored: a regenerated file replaces the month at Fora.

Use when: The user asks what to report to Fora for a month, why a worker is missing from the Fora file, or whether the Fora figures match the payroll.

Don't use for: Getting the file itself (the user opens "Fora-fil" in the salary run page's menu and downloads it there), the yearly total for tjänstemän (GET /reports/salary-journal groupTotals), or Fora's premiums (Fora invoices them).

Pitfalls

  • An employee is only reported with a Fora code: set fora_fok_id and fora_fok_start_date on the employee (the code is on Fora's Mina sidor, FOK plus six digits). Owners and board members never get one.
  • A draft or a salary run in review is not in the month: approve it first (warning FORA_RUN_NOT_APPROVED).
  • A worker with a code and no payout in the month is reported with pay_amount 0, as Fora asks for every marked-up worker every month.
  • Bonus earned in earlier months is reported in the payment month; attributing it to the months it was earned is not supported yet.
  • 400 FORA_REPORT_INCOMPLETE lists in details.issues what blocks the file: FORA_ORG_NUMBER_MISSING, FORA_ADDRESS_REQUIRED (a samordningsnummer needs street, postal code and city), FORA_NO_CODED_EMPLOYEES or FORA_NOTHING_IN_MONTH.

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

Query parameters

NameTypeRequiredDescription
yearnumberyesPayment year.
monthnumberyesPayment month, 1-12.

Response fields

NameTypeDescription
yearnumber
monthnumber
filenamestringThe file name the salary run page downloads.
payrollsobject[]
employee_countnumber
total_pay_amountnumber
salary_run_idsstring[]The salary runs whose pay is in the month.
warningsobject[]

Example request

{
  "year": 2026,
  "month": 10
}

Example response

{
  "data": {
    "year": 2026,
    "month": 10,
    "filename": "Fora_5565601712_202610.json",
    "payrolls": [
      {
        "employee_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
        "employee_name": "Kalle Hall",
        "personnummer_masked": "19540801-XXXX",
        "fok_id": "FOK306834",
        "pay_amount": 31250,
        "employment_end": null
      }
    ],
    "employee_count": 1,
    "total_pay_amount": 31250,
    "salary_run_ids": [
      "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
    ],
    "warnings": []
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/salary/premium-rules

salary.premium-rules.list · scope payroll:read

List OB and overtime premium rules.

Returns the shift premium rules the salary engine applies to worked days (OB-tillägg for evenings, nights, weekends and public holidays; tiered overtime), each with its amount form and validity. Active rules only unless ?include_inactive=true. No pagination: a company has a handful of rules.

Use when: You want to verify how OB or overtime will be derived before calculating a run, or to mirror a kollektivavtal into the company configuration.

Don't use for: The derived premium amounts on a payslip (GET /salary-runs/{id}/employees/{employeeId} after :calculate; each derived line names its rule). Worked hours themselves (the worked-days register).

Pitfalls

  • Rules only fire for worked days that carry start_time and end_time; hours-only rows are treated as 08:00-17:00 and never match night or weekend windows.
  • Overlapping rules never double-pay: each minute goes to the highest priority, then to the rule paying the most per hour for that employee.
  • ob_holiday rules fire only on actual Swedish public holidays, not on ordinary Sundays.
  • A rule pays only on dates between valid_from and valid_to; a rate step is two rules, the old one ending the day before the new one starts.

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

Query parameters

NameTypeRequiredDescription
include_inactive"true" | "false"notrue also returns switched-off rules. Default: active only.

Response fields

NameType
[].premium_rule_idstring
[].namestring
[].applies_to_all_employeesboolean
[].applies_to_employee_idsstring[]
[].day_of_weeknumber[]
[].start_timestring
[].end_timestring
[].amount_form"percent_of_hourly" | "monthly_divisor" | "sek_per_hour"
[].premium_percentnumber | null
[].monthly_divisornumber | null
[].sek_per_hournumber | null
[].hourly_divisornumber | null
[].valid_fromstring | null
[].valid_tostring | null
[].item_type"overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday"
[].prioritynumber
[].is_activeboolean
[].created_atstring
[].updated_atstring

Example response

{
  "data": [
    {
      "premium_rule_id": "c3f2…",
      "name": "OB kväll",
      "applies_to_all_employees": true,
      "applies_to_employee_ids": [],
      "day_of_week": [
        1,
        2,
        3,
        4,
        5
      ],
      "start_time": "18:00",
      "end_time": "06:00",
      "amount_form": "monthly_divisor",
      "premium_percent": null,
      "monthly_divisor": 480,
      "sek_per_hour": null,
      "hourly_divisor": null,
      "valid_from": "2025-04-01",
      "valid_to": null,
      "item_type": "ob_weekday_evening",
      "priority": 0,
      "is_active": true,
      "created_at": "2026-10-27T08:00:00Z",
      "updated_at": "2026-10-27T08:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

GET /api/v1/companies/:companyId/salary/settings

salary.settings.get · scope payroll:read

Get the company payroll settings.

Returns the payroll settings that drive new salary runs: pay day (salary_pay_day), avvikelseperiod (salary_deviation_period: which month a run reads absence and worked days from), salary payment file format (preferred_payment_format), the fallback bank for the upload instructions (salary_default_bank: the dashboard opens the instructions of the bank the payment file pays from first), öresavrundning of net pay (salary_net_rounding), whether the employee's payslip copy prints Arbetsgivarkostnad (salary_payslip_show_employer_cost) and Beräkningsunderlag (salary_payslip_show_breakdown), the calculation conventions (salary_calculation_policy: partial_month, sick_rate, long_leave, leave_context, net_rounding, one_off_tax_rounding, every key always present) and the voucher series salary runs book into (salary_voucher_series). A company that has no settings row yet answers with the defaults the engine would apply (pay day 25, same_month, pain001, no bank, no rounding, both payslip sections shown, every convention at its default, series A).

Use when: You are provisioning or auditing a customer for payroll and need to know how new salary runs will be dated, which month their deviations are read from, which calculation conventions the engine applies, which payment file the bank expects, or which voucher series the salary vouchers land in.

Don't use for: Invoice payment and contact details (PATCH /api/v1/companies/{companyId}/settings). Per-run values such as payment_date or deviation window (GET /salary-runs/{id}: they are snapshotted on the run). The conventions a calculated run actually used (GET /salary-runs/{id}: calculation_params.salary_calculation_policy). Employee-level pay settings (GET /employees/{id}).

Pitfalls

  • salary_payslip_show_employer_cost and salary_payslip_show_breakdown only change the payslip copy the employee receives (the emailed payslip link, and GET /salary-runs/{id}/payslips/{employeeId}/pdf?audience=employee). The employer view (the same PDF endpoint without audience) always prints both sections. The breakdown steps carry the employer cost figures, so salary_payslip_show_employer_cost=false also hides Beräkningsunderlag on the employee copy, whatever salary_payslip_show_breakdown says (its stored value is kept and applies again once the employer cost is shown). Both default to true. A change applies to runs whose payslips have not yet gone to employees: the first send or employee-copy download of a run fixes its sections on the run, and payslips already handed out keep the content they were issued with.
  • salary_deviation_period is snapshotted onto each salary run at creation: changing it never moves a run that already exists. Set it before the first run of a new month. Switching later makes the next run's deviation window overlap the previous run's window, and that run is refused with 409 SALARY_RUN_DEVIATION_PERIOD_OVERLAP (pass explicit deviation_period_start/end on that one run to bridge the switch).
  • salary_pay_day only drives the default payment_date of NEW runs (the day of the pay month, 1-28 so it exists in every month). Existing runs keep their payment_date; override per run on POST /salary-runs.
  • salary_voucher_series is an alias for company_settings.default_voucher_series_per_source_type.salary_payment. Writes MERGE that one key into the per-source-type map; the other source types keep their letters. The default company layout books salaries on K.
  • preferred_payment_format: pain001 (ISO 20022) is the default; bg_lb (Bankgirot Leverantörsbetalningar / Lön) is being retired by the banks during 2026, so only pick it for a customer whose bank still accepts LB files.
  • salary_calculation_policy holds the company's calculation conventions (beräkningsprinciper). Every key defaults to the historical Accounted behaviour; a customer migrated from Fortnox usually wants partial_month=annual_calendar_days (månadslön × 12 / 365 per calendar day employed), sick_rate=annual_hourly (timlön = månadslön × 12 / (52 × veckoarbetstid) for sjuklön), long_leave=calendar_after_five_workdays (leave longer than five working days deducted per calendar day at månadslön × 12 / 365, a whole month = the monthly salary) and, with salary_net_rounding, net_rounding=nearest. Compare one historical payslip before switching.
  • A PATCH of salary_calculation_policy is merged key by key into the stored policy (omitted keys keep their value); the response and the stored value always carry all seven keys. It is not snapshotted onto existing runs at creation: the conventions are read at :calculate and frozen into the run's calculation_params, so a draft recalculated after a change follows the new conventions and a calculated run does not.
  • long_leave=calendar_after_five_workdays is a five-day-week rule: :calculate refuses (400 VALIDATION_ERROR) a monthly employee whose workdays_per_week is not 5 while it is on. leave_context only matters under that convention.
  • one_off_tax_rounding governs engångsskatt on payslip lines that carry one_off_tax_percent (POST /salary-runs/{id}/employees/{employeeId}/lines); truncate (öretal bortfaller) is the statutory rule, nearest exists to reproduce another system's history.
  • vacation_day_value is how one paid semesterdag is valued under sammalöneregeln when the semesterlöneskuld is computed (the vacation-liability report, the vacation-year close, the vacation-balance estimate and the remeasurement): daily_divisor = månadslön / 21 at a five-day week (the historical value), percent_4_6 = 4,6 % of the månadslön, as Fortnox and Spiris value it. It never changes what a payslip pays. Valuations read the company's current value, not a run snapshot.
  • A company without a settings row reports series A (the engine fallback). The first PATCH creates the row with the standard series set, where salary_payment is K, unless salary_voucher_series is supplied in that same call: send it explicitly when provisioning so the letter never changes under you.

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

Response fields

NameType
company_idstring
salary_pay_daynumber
salary_deviation_period"same_month" | "previous_month"
preferred_payment_format"pain001" | "bg_lb"
salary_default_bank"swedbank" | "seb" | "handelsbanken" | "nordea" | "other" | null
salary_net_roundingboolean
salary_payslip_show_employer_costboolean
salary_payslip_show_breakdownboolean
salary_calculation_policyobject
salary_voucher_seriesstring

Example response

{
  "data": {
    "company_id": "aaaa1111-2222-4333-8444-555566667777",
    "salary_pay_day": 25,
    "salary_deviation_period": "previous_month",
    "preferred_payment_format": "pain001",
    "salary_default_bank": "swedbank",
    "salary_net_rounding": true,
    "salary_payslip_show_employer_cost": true,
    "salary_payslip_show_breakdown": false,
    "salary_calculation_policy": {
      "partial_month": "annual_calendar_days",
      "sick_rate": "annual_hourly",
      "long_leave": "calendar_after_five_workdays",
      "leave_context": "all_registered",
      "net_rounding": "nearest",
      "one_off_tax_rounding": "truncate",
      "vacation_day_value": "percent_4_6"
    },
    "salary_voucher_series": "K"
  },
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.create · scope payroll:write

Create a salary run.

Creates a draft salary run for the given period (period_year, period_month). The run starts empty: add employees with POST /salary-runs/{id}/employees, then POST /salary-runs/{id}/calculate. Requires Idempotency-Key. Dry-runnable.

Use when: You are starting a new month's payroll. Use dry-run first to validate the period + voucher_series choice without committing.

Don't use for: Adding employees to an existing run (POST /salary-runs/{id}/employees).

Pitfalls

  • Idempotency-Key is mandatory.
  • Duplicate (period_year, period_month) for the same company returns 409 SALARY_RUN_DUPLICATE_PERIOD.
  • Avvikelseperiod: absence and worked days are read from deviation_period_start..deviation_period_end, NOT necessarily from the pay month. Omit both to use the company setting (salary_deviation_period: same_month by default, previous_month for "innevarande månads lön, föregående månads avvikelser"), or pass both explicitly. A window that overlaps another live run returns 409 SALARY_RUN_DEVIATION_PERIOD_OVERLAP (the same day would be deducted twice); one date without the other, or a span over 62 days, returns 400 SALARY_RUN_DEVIATION_PERIOD_INVALID.
  • period_month is 1-12. The DB CHECK enforces this: a 0 or 13 returns 400 VALIDATION_ERROR before reaching the DB.
  • voucher_series omitted: the company's salary series (its voucher series setting for salary_payment, K on the standard set, A when the company has none), the series the dashboard and MCP use. A dry run previews it. Send a letter only to override it for this run.
  • A newly-created run has no employees: :calculate without employees returns 400 SALARY_RUN_NO_EMPLOYEES.

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
period_yearnumberyes
period_monthnumberyes
payment_datestringyes
voucher_seriesstringno
notesstringno
deviation_period_startstringno
deviation_period_endstringno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
period_yearnumber
period_monthnumber
payment_datestring
deviation_period_startstring | null
deviation_period_endstring | null
status"draft" | "review" | "approved" | "paid" | "booked" | "corrected"
voucher_seriesstring
total_grossnumber
total_taxnumber
total_netnumber
total_avgifternumber
total_employer_costnumber
agi_generated_atstring | null
agi_submitted_atstring | null
approved_atstring | null
paid_atstring | null
booked_atstring | null
created_atstring
notesstring | null
calculation_paramsunknown (optional)
updated_atstring

Example request

{
  "period_year": 2026,
  "period_month": 5,
  "payment_date": "2026-05-25",
  "voucher_series": "L",
  "deviation_period_start": "2026-04-01",
  "deviation_period_end": "2026-04-30"
}

Example response

{
  "data": {
    "id": "run_a8f1…",
    "period_year": 2026,
    "period_month": 5,
    "payment_date": "2026-05-25",
    "deviation_period_start": "2026-04-01",
    "deviation_period_end": "2026-04-30",
    "status": "draft",
    "voucher_series": "L"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.approve · scope payroll:write

Approve a reviewed salary run.

Advances a salary run from review to approved after validating every employee has the data required for the payment step (bank account + clearing number for an employee with a payout) and the booking step (calculation_breakdown proves :calculate ran). Records the approving user + timestamp. Strict-mode: validation errors return a complete list rather than failing on the first one.

Use when: You have a salary run in review status and want to authorize it for payment. This is the human (or agent) signoff step before money moves; the verifikation is still pending and won't exist until :book runs.

Don't use for: Posting journal entries (use :book after :mark-paid). Reverting an approval (POST /salary-runs/{id}/unapprove while the run is unpaid and its AGI unfiled; call :correct once the run is booked).

Pitfalls

  • Run must be in review: non-review runs return 400 SALARY_RUN_APPROVE_NOT_REVIEW.
  • Every employee with a payout (net after any tax override > 0) needs a clearing_number + bank_account_number that name a payable account (clearing 4 digits, or 5 starting with 8; account 5-10 digits without the clearing number). Missing or invalid bank details return 400 SALARY_RUN_APPROVE_VALIDATION_FAILED with the per-employee list; the list names employees, never account numbers. An employee with nothing to pay out (nollkörning, or a net fully used by a nettolöneavdrag) needs none: the payment file has no line for them.
  • Every employee on the run needs calculation_breakdown populated. If you skipped :calculate somehow, approve fails.
  • Employees without email get a non-blocking warning (lönebesked can't be sent automatically), and so does an employee whose F-skatt is not verified (30% skatteavdrag and full avgifter apply).
  • No period-lock check here: that lives on :book where the verifikation is posted. An agent can approve a run whose payment date falls in a now-locked period; :book will later refuse.

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

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
status"approved"
approved_atstring
approved_bystring | null
warningsstring[]

Example response

{
  "data": {
    "id": "run_a8f1…",
    "status": "approved",
    "approved_at": "2026-05-14T12:00:00Z",
    "approved_by": "user_b73c…",
    "warnings": [
      "Anna Andersson: E-post saknas, lönebesked kan inte skickas"
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.book · scope payroll:write

Post the verifikationer for a paid salary run.

Creates 1-4 journal entries (1 if the run pays, withholds or expenses anything: salary brutto/tax/net, so a run whose only amount is a förmånsvärde has none and keeps salary_entry_id null; 2 if the run has any: arbetsgivaravgifter; 3 if applicable: semesterlöneskuld accrual; 4 if applicable: pension + SLP from löneväxling), then advances status paid → booked with all the entry IDs recorded on the salary_runs row. Strict-mode: any engine failure aborts BEFORE the status flip, and all entries are validated before the first is posted, so a refusal (locked period, missing BAS account, required or archived dimension value, etc.) posts nothing: the run stays in paid so the caller can fix the cause and retry. A nollkörning (a run without amounts, or without employees) posts no entries: it is booked with salary_entry_id null and no audit block, and the AGI nolldeklaration is the period's only artefact.

Use when: You've marked a salary run as paid and want to post the BFL-required verifikationer. This is the final lifecycle verb before AGI generation; after :book, the run can no longer be edited and corrections go through POST /salary-runs/{id}/correct (storno, then a correction run).

Don't use for: Posting salary entries outside the salary-run lifecycle (use POST /journal-entries directly). Re-booking an already-booked run (returns 400 SALARY_RUN_BOOK_NOT_PAID).

Pitfalls

  • Run must be in paid: non-paid runs return 400 SALARY_RUN_BOOK_NOT_PAID.
  • payment_date must fall in an open fiscal period: locked period returns 400 PERIOD_LOCKED with fiscal_period_id and a hint of what unlock action is needed.
  • A run that pays out with a payment_date after today (Swedish calendar day) returns 422 SALARY_RUN_PAYMENT_DATE_AHEAD_UNCONFIRMED (details.payment_date) unless the body has confirm_payment_date_ahead: true: the salary verifikation credits the net pay to the bank account on payment_date. Confirm only when the salaries have gone out or the payment is scheduled in the bank; otherwise book on or after payment_date.
  • BFL 5 kap immutability: once :book succeeds the verifikationer cannot be edited or deleted. Corrections require :correct (Phase 5 PR-3) which does a storno-then-rebook.
  • The salary verifikation is the primary one; its voucher_number appears in the response audit block. The avgifter, vacation, and pension entries get separate voucher numbers (returned as entry_ids).
  • A run without arbetsgivaravgifter (only utlägg repaid, or only payees without avgifter such as F-skatt holders) posts no avgifter entry: avgifter_entry_id is null.
  • A nollkörning (every total 0, or no employees) is booked without entries: entry_ids is [], salary_entry_id is null and meta.audit is absent. No period lock applies to it, since nothing is posted.
  • Strict-mode: every entry is validated before the first is posted, so a refusal posts nothing and the run stays in paid. If posting stops partway on a transient failure, calling :book again adopts the entries already posted (when they match the run exactly) and posts only the missing ones, never twice. A posted entry of the run that does not match returns 409 SALARY_RUN_PARTIALLY_BOOKED with details.voucher_numbers: reverse those, then retry.
  • One booking per run at a time: while another :book call (or a dashboard or MCP booking) for the same run is in flight, this call returns 409 SALARY_RUN_BOOKING_IN_PROGRESS and posts nothing. Do not retry at once after a client timeout: wait, GET the run, and call :book again only if it is still paid.

Risk: high · 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
confirm_payment_date_aheadbooleanno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
status"booked"
booked_atstring
booked_bystring | null
salary_entry_idstring | null
avgifter_entry_idstring | null
vacation_entry_idstring | null
pension_entry_idstring | null
entry_idsstring[]

Example request

{
  "confirm_payment_date_ahead": true
}

Example response

{
  "data": {
    "id": "run_a8f1…",
    "status": "booked",
    "booked_at": "2026-05-26T09:15:00Z",
    "booked_by": "user_b73c…",
    "salary_entry_id": "je_salary…",
    "avgifter_entry_id": "je_avg…",
    "vacation_entry_id": "je_vac…",
    "pension_entry_id": null,
    "entry_ids": [
      "je_salary…",
      "je_avg…",
      "je_vac…"
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "audit": {
      "voucher_number": "L2026-0023",
      "voucher_url": "/api/v1/companies/.../journal-entries/je_salary…",
      "immutable_at": "2026-05-26T09:15:00Z"
    }
  }
}

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

salary-runs.calculate · scope payroll:write

Calculate a draft salary run and advance it to review.

Runs the per-employee payroll calculation (tax withholding, employer contributions, vacation accrual) for every employee on a draft run, persists the line items + run totals + calculation_params snapshot, then promotes status from draft to review in a single atomic verb. Returns the updated run plus a warnings array surfacing non-blocking issues (Skatteverket tax-table fallback, läkarintyg day-8 transition, Försäkringskassan day-15 transition, F-skatt not-verified employees). Strict-mode: any failure (validation, tax-table unavailable, DB error) aborts before the status flip: the run stays in draft.

Use when: You have a draft salary run with employees added and want to compute the numbers + freeze them for approval. This is the first lifecycle verb after creating a run.

Don't use for: re-running a salary run already in review or later (only draft is accepted: send a review run back with POST /salary-runs/{id}/revert, recall an approval with POST /salary-runs/{id}/unapprove first, and revise a paid or booked run with POST /salary-runs/{id}/correct). Adding employees to the run (POST /salary-runs/{id}/employees).

Pitfalls

  • Run must be in draft status: calculate on a non-draft run returns 400 SALARY_RUN_CALCULATE_NOT_DRAFT.
  • Salary run must have at least one employee: empty runs return 400 SALARY_RUN_NO_EMPLOYEES.
  • If Skatteverket's tax-table API is down and local fallback is missing the required table, calculate returns 503 SALARY_RUN_TAX_TABLE_MISSING. Retry is safe; the operation is idempotent at the helper level.
  • Vacation lines without an amount are priced here (semestertillägg, semesterlöneavdrag and semesterlön, or the deduction for unpaid days). When the days cannot be priced from the law and the data (procentregeln without the previous year in Accounted, hourly pay on sammalöneregeln, hourly förskott, vacation pay already paid as semesterersättning) calculate returns 400 SALARY_RUN_VACATION_PAY_UNDETERMINED with details.issues naming each employee and why; put the amount on the vacation line or change its category, then calculate again. Never estimate the base.
  • A run whose payment date falls in a year Accounted has no payroll rates for yet returns 409 SALARY_PAYROLL_CONFIG_MISSING (details.paymentYear). The year's rates ship once they are officially set; do not move the payment date to get around it.
  • F-skatt "not_verified" employees produce a non-blocking warning; an integrator should treat the warning as a hard signal that withholding will be wrong until F-skatt is verified.
  • Warnings about tax-table fallback or läkarintyg / FK day-15 transitions are non-blocking; the run still advances to review. Surface them to a human reviewer before calling :approve.

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

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
status"review"
period_yearnumber
period_monthnumber
total_grossnumber
total_taxnumber
total_netnumber
total_avgifternumber
total_employer_costnumber
warningsstring[]

Example response

{
  "data": {
    "id": "run_a8f1…",
    "status": "review",
    "period_year": 2026,
    "period_month": 5,
    "total_gross": 105000,
    "total_tax": 28500,
    "total_net": 76500,
    "total_avgifter": 32991,
    "total_employer_cost": 137991,
    "warnings": [
      "Läkarintyg krävs från och med dag 8: Anna Andersson. Kontrollera att läkarintyg finns innan lönekörningen godkänns."
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.correct · scope payroll:write

Correct a booked salary run (rättelsekörning): storno its verifikat and open a new draft for the same period.

Per Bokföringslagen 5 kap 5 § a booked salary run is never edited: this verb reverses every verifikation the run posted (salary, arbetsgivaravgifter, semesterlöneskuld, pension) with storno entries, marks the original corrected, revokes the payslip links that were emailed for it, and inserts a fresh draft run for the same period with is_correction = true and corrects_run_id pointing back. The roster and line items are copied onto the correction run so the operator edits a populated draft. Idempotent. Dry-runnable.

Use when: A booked (and usually paid) month turns out wrong: a missing line, a wrong salary, a benefit that was not on the payslip. Call this first, then edit the correction run's lines and walk it through calculate, approve, mark-paid, book and generate-agi.

Don't use for: Runs that are not booked yet (draft, review, approved, paid): delete or edit them instead, nothing is posted. Fixing a single verifikation outside the salary lifecycle (POST /journal-entries/{id}/correct). Re-issuing payslips without changing amounts.

Pitfalls

  • Only booked runs can be corrected: any other status returns 409 SALARY_RUN_CORRECT_NOT_BOOKED with details.current_status.
  • The original's verifikat are reversed with storno (new reversing entries in the same series); nothing is edited or deleted. All reversed entry IDs are returned in reversed_entry_ids.
  • The correction run is a fresh draft for the same period: it must be attached (roster is copied for you), calculated, approved, paid, booked and its AGI regenerated. Nothing is posted by this verb.
  • A second call on the same run returns 409 SALARY_RUN_ALREADY_CORRECTED with details.correction_run_id: continue in that run instead.
  • Payslip links of the original are revoked immediately (employees see "ersatt"); fresh links are issued when the correction run's payslips are sent.
  • The arbetsgivardeklaration (AGI) for the period must be re-filed after the correction run books; Skatteverket receives the corrected figures, not a delta.
  • The storno entries land in the original payment_date's period: a locked period returns PERIOD_LOCKED and nothing is written. If the failure happens after the first storno, valid_alternatives.reversed_entry_ids names the entries already reversed and valid_alternatives.remaining_entry_ids the ones still posted; the run stays booked; call this verb again once the cause is fixed: the retry skips the entries already reversed and continues with the remaining ones.
  • Idempotency-Key is mandatory.

Risk: high · 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
original_run_idstring
original_status"corrected"
correction_runobject
reversed_entry_idsstring[]

Example response

{
  "data": {
    "original_run_id": "run_a8f1…",
    "original_status": "corrected",
    "correction_run": {
      "id": "run_c0rr…",
      "period_year": 2026,
      "period_month": 5,
      "payment_date": "2026-05-25",
      "status": "draft",
      "is_correction": true,
      "corrects_run_id": "run_a8f1…",
      "deviation_period_start": "2026-04-01",
      "deviation_period_end": "2026-04-30"
    },
    "reversed_entry_ids": [
      "je_salary…",
      "je_avg…",
      "je_vac…"
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/generate-agi

salary-runs.generate-agi · scope payroll:write

Generate the Skatteverket AGI XML for a salary run.

Generates the arbetsgivardeklaration-på-individnivå XML for the run (HU section + per-employee IU + Frånvarouppgift for VAB/parental), upserts the agi_declarations row (correction-aware), stamps salary_runs.agi_generated_at, emits agi.generated, and auto-completes the arbetsgivardeklaration deadline. Returns the XML as a string field in the v1 envelope: agents extract data.xml and forward to Skatteverket directly (Mina Sidor upload or via a connected extension).

Use when: You've reviewed (or approved / paid / booked) a salary run and need to file AGI with Skatteverket. The Skatteverket filing deadline is the 12th of the following month (17th in Jan / Aug for companies ≤40 MSEK turnover).

Don't use for: Submitting the AGI to Skatteverket: this endpoint only generates and persists the XML. Submission is a separate flow via the (optional) skatteverket extension.

Pitfalls

  • Run status must be one of review, approved, paid, booked, corrected: draft returns 400 AGI_GENERATE_NOT_BOOKABLE.
  • Generating AGI from a review-status run risks submitting figures that will change at :approve. The dashboard allows this for flexibility; agents should prefer approved+ unless an early-warning workflow specifically wants the preview.
  • Subsequent calls for the same period UPDATE the agi_declarations row (is_correction=true) and overwrite the XML, until it is filed: a run whose declaration carries its kvittens gets the stored, filed XML back and nothing is rewritten. The FK570 specifikationsnummer stays consistent per employee: different number = new record per Skatteverket spec.
  • AGI_PERIOD_CONFLICT (409): another live run is paid out in the same month, whether or not it already holds the declaration of the period. Runs are not combined into one declaration; details.other_salary_run_id names the other run. AGI_GENERATION_CONFLICT (409): the declaration changed while it was generated (another generation or a submission); retry.
  • AGI_INCOMPLETE_DATA returns 400 when company contact info is missing (org_number, contact name, phone, email). Fix via /settings/company before retrying.
  • The XML content is räkenskapsinformation: BFL 7 kap retention applies. The agi_declarations row is never auto-deleted.

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

Response fields

NameType
agi_declaration_idstring
period_yearnumber
period_monthnumber
employee_countnumber
is_correctionboolean
totalsobject
xmlstring
xml_filenamestring

Example response

{
  "data": {
    "agi_declaration_id": "agi_a8f1…",
    "period_year": 2026,
    "period_month": 5,
    "employee_count": 3,
    "is_correction": false,
    "totals": {
      "totalTax": 28500,
      "totalAvgifterBasis": 105000,
      "totalAvgifterAmount": 32991,
      "avgifterByCategory": {
        "standard": {
          "basis": 105000,
          "amount": 32991
        }
      }
    },
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Skatteverket omrade=\"Arbetsgivardeklaration\">…</Skatteverket>",
    "xml_filename": "AGI_5566778899_202605.xml"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/mark-paid

salary-runs.mark-paid · scope payroll:write

Mark an approved salary run as paid.

Advances a salary run from approved to paid and stamps paid_at. This is the state-change verb after the bank transfer (or autogiro file) has been processed; it does NOT initiate payment, and does NOT post journal entries (use :book after this for that).

Use when: You've confirmed the salary payment hit employee bank accounts and want to advance the run's lifecycle so :book can post the verifikation.

Don't use for: Initiating the actual bank transfer (generate the bank file with POST /salary-runs/{id}/payment-file and upload it through the bank channel; this verb only records that it happened). Posting journal entries (use :book). Reverting a paid run (no :unpaid exists: call :correct once booked if you need to undo).

Pitfalls

  • Run must be in approved: non-approved runs return 400 SALARY_RUN_MARK_PAID_NOT_APPROVED.
  • paid_at is set server-side to the current UTC timestamp; the API does not accept a body-supplied date to keep BFL audit clean.
  • A run that pays out with a payment_date after today (Swedish calendar day) returns 422 SALARY_RUN_PAYMENT_DATE_AHEAD_UNCONFIRMED (details.payment_date) unless the body has confirm_payment_date_ahead: true. Confirm only when the salaries have already gone out or the payment is scheduled in the bank: :book then posts the net pay as paid out of the bank account on payment_date.

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
confirm_payment_date_aheadbooleanno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
status"paid"
paid_atstring

Example request

{
  "confirm_payment_date_ahead": true
}

Example response

{
  "data": {
    "id": "run_a8f1…",
    "status": "paid",
    "paid_at": "2026-05-25T08:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/payment-file

salary-runs.payment-file · scope payroll:write

Generate the bank payment file (pain.001 or Bankgirot LB) for a salary run.

Builds the salary batch payment file for an approved (or paid / booked) run and returns it inline as a string: ISO 20022 pain.001.001.03 XML (pain001, default) or the legacy Bankgirot LB text file (bg_lb). One credit transfer per employee with a positive net payout, dated on the run's payment_date, category purpose SALA. Every generated file is archived as an immutable salary_payment_files row (BFL 7 kap. 1 §, seven-year retention) before it is returned; payment_file_id and sha256 identify that copy and GET /salary-runs/{id}/payment-files lists them. Stamps salary_runs.payment_file_format and payment_file_generated_at. Same preconditions and output as the dashboard's payment-file download.

Use when: The salary run is approved and you (or an external payroll operator) need the file to upload in the bank's corporate file channel to pay the salaries.

Don't use for: Marking the run paid (use :mark-paid after the bank has executed the batch), posting the verifikationer (use :book), paying supplier invoices (use the supplier-invoice payment batch), or sending anything to the bank: this call only produces the file.

Pitfalls

  • Run status must be one of approved, paid, booked: a draft or review run returns 409 SALARY_RUN_PAYMENT_FILE_NOT_READY. Approve the run first (:approve).
  • pain001 pays from the bank account the salary is booked on: for a booked run the account its salary verifikat credits, for any other run the company's primary bank account (the one :book will credit). paying_account names it. The file uses that account's IBAN (the bank-reported one for a connected account, the entered one for a manual account) and its BIC (saved on the account, named by the bank connection, or derived from the IBAN, clearing number or bank name); a company with a single SEK bank account and no IBAN on it, or with no cash accounts, falls back to the IBAN and BIC in company settings. Every employee with a net payout needs clearing number and account number. bg_lb needs a valid company bankgiro number. Missing company details return 422 SALARY_RUN_PAYMENT_FILE_MISSING_BANK_DETAILS (details.problem names the field, details.account the paying account for iban_missing and bic_missing); missing employee accounts return 422 SALARY_RUN_PAYMENT_FILE_EMPLOYEE_BANK_MISSING with details.employees.
  • An employee account that names no payable account returns 422 SALARY_RUN_PAYMENT_FILE_EMPLOYEE_BANK_INVALID with details.employees (employee_id, name, problem) for every affected employee at once; the response never echoes an account number. problem is clearing_format or account_format (correct the employee's bank details: clearing 4 digits or 5 starting with 8, account 5-10 digits without the clearing number). Both formats carry every account that passes entry, including a 5-digit Swedbank clearing with a 10-digit account. A dry run reports the same error, so preview before payday.
  • The file comes back inline as content (a string). Write it to disk under filename (pain001 as UTF-8, bg_lb as ISO 8859-1 with CRLF line endings, exactly as returned) and upload it in the bank's file channel. Nothing is transmitted to the bank by this call.
  • Generating the file does NOT mark the run paid and moves no money. Call :mark-paid once the bank has executed the batch, then :book to post the verifikationer.
  • Bankgirot LB is being retired by the banks during 2026: prefer pain001. format defaults to company_settings.preferred_payment_format, which is pain001 unless the company changed it.
  • Employees with a zero net payout (nollkörning, or net consumed by a nettolöneavdrag) are left out of the file and need no bank account; employee_count and total_amount cover only the paid lines. Regenerating is harmless: each call rebuilds the file, archives it as a new salary_payment_files row and re-stamps payment_file_generated_at.
  • A correction run (is_correction, from :correct) pays only the difference: each employee's corrected net payout minus what the run it corrects already paid them (a new employee gets the full net). An employee with no difference is left out; one the correction paid too much (a lower corrected net, or removed from the run) is never paid or deducted and is named in warnings, so the person handles it. A correction with no positive difference returns 422 SALARY_RUN_PAYMENT_FILE_NOTHING_TO_PAY with details.correction.overpaid.
  • Every generated file is archived and listable: the response carries payment_file_id (the archived row) and sha256 (over the bytes as encoded for the bank: UTF-8 for pain001, ISO 8859-1 for bg_lb). Compare it with the checksum of what you uploaded, and use GET /salary-runs/{id}/payment-files to retrieve exactly what was generated earlier instead of regenerating: a regeneration after a bank-detail change (new employee account, changed company IBAN) is a different file, and the archive is the record of what the bank actually received. An archive failure returns an error and no file.
  • The file always uses the run's payment_date as the requested execution date; the body accepts no execution date (unknown fields return 400). Change the run's payment_date (PATCH while draft) if the transfer day must move.
  • Dry run (?dry_run=true) validates every precondition and returns format, filename, payment_date, employee_count, total_amount, paying_account and warnings without the content, without archiving and without stamping the run.
  • Every call returns the run's current file version with the same MsgId and EndToEndIds, so the bank refuses a second upload of the month as a duplicate. If the bank refused or never approved the earlier pain001 file (for example a corrected bank account), send new_version: true with confirm_previous_not_approved: true: the file gets new ids and becomes the run's version from then on. Only confirm when the earlier file was NOT approved at the bank; two approved files pay the salaries twice. Without the confirmation the call returns 422 SALARY_RUN_PAYMENT_FILE_NEW_VERSION_UNCONFIRMED; bg_lb returns 422 SALARY_RUN_PAYMENT_FILE_NEW_VERSION_UNSUPPORTED.

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
format"pain001" | "bg_lb"no
new_versionbooleanno
confirm_previous_not_approvedbooleanno

Response fields

NameType
salary_run_idstring
payment_file_idstring
format"pain001" | "bg_lb"
versionnumber
filenamestring
content_type"application/xml" | "text/plain"
contentstring
sha256string
payment_datestring
employee_countnumber
total_amountnumber
currency"SEK"
paying_accountobject | null
warningsstring[]
generated_atstring

Example request

{
  "format": "pain001"
}

Example response

{
  "data": {
    "salary_run_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
    "payment_file_id": "f0f0f0f0-f0f0-4f0f-8f0f-f0f0f0f0f0f0",
    "format": "pain001",
    "version": 1,
    "filename": "pain001_lon_2026-05.xml",
    "content_type": "application/xml",
    "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.03\"><CstmrCdtTrfInitn>…</CstmrCdtTrfInitn></Document>",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "payment_date": "2026-05-25",
    "employee_count": 3,
    "total_amount": 76500,
    "currency": "SEK",
    "paying_account": {
      "cash_account_id": "abababab-abab-4bab-8bab-abababababab",
      "name": "Företagskonto",
      "ledger_account": "1930",
      "iban_last4": "0123"
    },
    "warnings": [],
    "generated_at": "2026-05-20T08:00:00.000Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.revert · scope payroll:write

Send a salary run in review back to draft so it can be edited.

Moves the run from review to draft. Nothing is deleted or booked: the calculated figures stay on the run until it is recalculated, and payslip lines, employees and salaries become editable again. Run POST /salary-runs/{id}/calculate afterwards to get back to review. Idempotent. Dry-runnable.

Use when: A calculated run needs a change before approval: a missing line, an employee added or removed, a corrected salary or absence in the deviation period.

Don't use for: An approved run (POST /salary-runs/{id}/unapprove first) or a paid or booked run (POST /salary-runs/{id}/correct).

Pitfalls

  • Only a run in review can be reverted: anything else returns 400 SALARY_RUN_REVERT_NOT_REVIEW with details.current_status.
  • A run that moves on between the check and the write returns 409 SALARY_RUN_STATUS_CHANGED: read it again.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Response fields

NameType
salary_run_idstring
status"draft"

Example response

{
  "data": {
    "salary_run_id": "run_a8f1…",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary-runs/:id/send-payslips

salary-runs.send-payslips · scope payroll:write

Email the employees on an approved salary run a secure link to their payslip.

Sends each employee on the run (or only those in employee_ids) an email with a secure link to their lönebesked (never a PDF attachment: salary data and personnummer must not sit in inboxes). Each send rotates the employee's link, so a link emailed earlier for the run stops working. Every attempt, sent, failed or skipped for a missing email address, is written to the delivery log (salary_payslip_deliveries, BFL 7 kap.). One employee failing does not stop the others. Requires the run to be approved, paid or booked. Dry-runnable: the dry run lists the recipients and who lacks an email address, and sends nothing.

Use when: The run is approved (or paid/booked) and the employees should get their payslips, a group paid on its own day should get theirs (employee_ids), or a payslip should be re-sent after an employee's email address was corrected.

Don't use for: Fetching the payslip document yourself (GET /salary-runs/{id}/payslips/{employeeId}/pdf) or reading payslip amounts (GET /salary-runs/{id}/employees/{employeeId}).

Pitfalls

  • A draft or review run returns 400 SALARY_PAYSLIPS_SEND_INVALID_STATUS: approve it first.
  • Re-sending emails everyone on the run (or in employee_ids) again and invalidates their links sent before.
  • An employee_ids entry not on the run refuses the whole send with 400 SALARY_PAYSLIPS_EMPLOYEE_NOT_ON_RUN (details.employee_ids); nothing is sent.
  • Employees without an email address are skipped and counted in skipped, not an error: fix the address with PATCH /employees/{id} and send again.
  • Refused with 403 from the sandbox company (SALARY_PAYSLIPS_SEND_SANDBOX) and without the email capability (SALARY_PAYSLIPS_SEND_CAPABILITY_BLOCKED).
  • Not idempotent towards the recipients: a replay with a new Idempotency-Key emails everyone again.
  • The first send (or the first employee-copy PDF, whichever comes first) fixes which payslip sections the employee copy of this run prints, from salary_payslip_show_employer_cost / salary_payslip_show_breakdown at that moment. Changing those settings afterwards never changes a payslip of this run that employees already have; re-sending keeps the fixed sections.

Risk: medium · Idempotent: yes · Reversible: no · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Request body

NameTypeRequired
employee_idsstring[]no

Response fields

NameTypeDescription
salary_run_idstring
sentnumber
skippednumberEmployees without an email address (logged as skipped).
failednumber
totalnumber
deliveriesobject[]

Example request

{
  "employee_ids": [
    "emp_1…"
  ]
}

Example response

{
  "data": {
    "salary_run_id": "run_a8f1…",
    "sent": 2,
    "skipped": 1,
    "failed": 0,
    "total": 3,
    "deliveries": [
      {
        "employee_id": "emp_1…",
        "employee_name": "Anna Andersson",
        "status": "sent",
        "error": null
      },
      {
        "employee_id": "emp_2…",
        "employee_name": "Björn Berg",
        "status": "skipped",
        "error": "Anställd saknar e-postadress"
      }
    ]
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.unapprove · scope payroll:write

Recall the approval of a salary run (approved back to review).

Moves an approved run back to review and clears the approver, the AGI generation stamp and the payment-file tracking. A generated or exported AGI declaration that never reached Skatteverket is deleted, because its amounts may change. Refused once the AGI is being signed or has been filed: the period is then changed with a corrected AGI. A paid or booked run is never unapproved; it is corrected. Payslips already emailed are not recalled. Idempotent. Dry-runnable: the dry run names the AGI declaration it would delete, whether a payment file was generated and how many payslips were sent.

Use when: An approved run turns out wrong before it was paid and before the AGI was filed, and must be recalculated.

Don't use for: A paid or booked run (POST /salary-runs/{id}/correct) or a period whose AGI was filed (file a corrected AGI).

Pitfalls

  • Only an approved run: anything else returns 400 SALARY_RUN_UNAPPROVE_NOT_APPROVED.
  • An AGI in pending_signature, submitted or accepted (or agi_submitted_at set) returns 409 SALARY_RUN_UNAPPROVE_AGI_FILED.
  • A payment file generated for the run may already be with the bank: the API cannot know. Check before recalling, or salaries may be paid on the old amounts.
  • To edit the run afterwards, also revert it to draft (POST /salary-runs/{id}/revert).

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Response fields

NameTypeDescription
salary_run_idstring
status"review"
deleted_agi_declaration_idstring | nullThe generated but unfiled AGI declaration removed as stale, or null.

Example response

{
  "data": {
    "salary_run_id": "run_a8f1…",
    "status": "review",
    "deleted_agi_declaration_id": null
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary/premium-rules

salary.premium-rules.create · scope payroll:write

Create an OB or overtime premium rule.

Adds a rule: weekdays (ISO 1-7), a wall-clock window (end <= start wraps midnight), an amount form with exactly its own field (percent_of_hourly: premium_percent of the hourly wage, optionally with the agreement hourly_divisor for monthly-paid staff, e.g. Handels 166; monthly_divisor: månadslön / monthly_divisor per hour, e.g. Almega 480/300/150 or övertid 94/72; sek_per_hour: fixed kronor per hour, e.g. Gröna riksavtalet 27.59), a validity (valid_from required, valid_to optional), one of six item types, a priority for overlaps, and a scope (all employees or a named list). Supports ?dry_run=true.

Use when: Configuring OB and overtime from a kollektivavtal, or entering a new rate from a date (create the new rule with valid_from and set valid_to on the old one).

Don't use for: One-off manual premium lines on a single payslip (put the amount on item_type overtime or other on the run instead). Mertid or kompensationsledighet (not modelled).

Pitfalls

  • Send only the field of the chosen form: a percent on a monthly_divisor rule returns 400 VALIDATION_ERROR naming premium_percent.
  • monthly_divisor prices from the månadslön: OB types use the actual (degree-adjusted) salary, övertid types the full-time salary. It does not apply to hourly-paid employees, and naming one returns 400 SHIFT_PREMIUM_RULE_HOURLY_EMPLOYEE.
  • applies_to_all_employees=true requires an empty applies_to_employee_ids; false requires at least one id.
  • An employee id from another company returns 404 SHIFT_PREMIUM_RULE_EMPLOYEE_NOT_FOUND with the offending ids in details.
  • For "no OB on overtime hours" give the övertid rules a higher priority than the OB rules on the same window; at equal priority the rule paying the most per hour wins.
  • New rules apply to the next calculation of any open run; booked runs are never recomputed.

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
namestringyes
day_of_weeknumber[]yes
start_timestringyes
end_timestringyes
amount_form"percent_of_hourly" | "monthly_divisor" | "sek_per_hour"no
premium_percentnumber | nullno
monthly_divisornumber | nullno
sek_per_hournumber | nullno
hourly_divisornumber | nullno
valid_fromstringyes
valid_tostring | nullno
item_type"overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday"yes
prioritynumberno
applies_to_all_employeesbooleanno
applies_to_employee_idsstring[]no
is_activebooleanno

Response fields

NameType
premium_rule_idstring
namestring
applies_to_all_employeesboolean
applies_to_employee_idsstring[]
day_of_weeknumber[]
start_timestring
end_timestring
amount_form"percent_of_hourly" | "monthly_divisor" | "sek_per_hour"
premium_percentnumber | null
monthly_divisornumber | null
sek_per_hournumber | null
hourly_divisornumber | null
valid_fromstring | null
valid_tostring | null
item_type"overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday"
prioritynumber
is_activeboolean
created_atstring
updated_atstring

Example request

{
  "name": "OB kväll",
  "day_of_week": [
    1,
    2,
    3,
    4,
    5
  ],
  "start_time": "18:00",
  "end_time": "06:00",
  "amount_form": "monthly_divisor",
  "monthly_divisor": 480,
  "valid_from": "2025-04-01",
  "item_type": "ob_weekday_evening"
}

Example response

{
  "data": {
    "premium_rule_id": "c3f2…",
    "name": "OB kväll",
    "applies_to_all_employees": true,
    "applies_to_employee_ids": [],
    "day_of_week": [
      1,
      2,
      3,
      4,
      5
    ],
    "start_time": "18:00",
    "end_time": "06:00",
    "amount_form": "monthly_divisor",
    "premium_percent": null,
    "monthly_divisor": 480,
    "sek_per_hour": null,
    "hourly_divisor": null,
    "valid_from": "2025-04-01",
    "valid_to": null,
    "item_type": "ob_weekday_evening",
    "priority": 0,
    "is_active": true,
    "created_at": "2026-10-27T08:00:00Z",
    "updated_at": "2026-10-27T08:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary/vacation-liability/reconcile

salary.vacation-liability.reconcile · scope payroll:write

Book the semesterlöneskuld at its computed value on a date: the difference to 2920/2940 as one verifikat.

Computes the vacation liability as of as_of per employee (unpaid vacation pay for days earned and not taken: the remaining paid days of the vacation year, sparade dagar, on the statutory April to March basis the days earned so far toward the next semesterår, and under sammalöneregeln the unpaid semesterlön of rörliga lönedelar; each day valued at the company's vacation_day_value convention, avgifter at each employee's age-tier rate) and books the difference to what 2920 and 2940 hold: 7090 (arbetare) or 7290 per employee against 2920, and 7519 against 2940, debit when the liability grows and credit when it shrinks, dated as_of (source_type salary_payment). The calculation behind it is stored as the verifikat's underlag and is what the Semesterskuld report starts from afterwards. A side whose every amount stays within 1 krona is not booked; when nothing moves, adjusted is false and no verifikat is created, so a repeat is harmless. Dry-runnable: the dry run answers the lines and the per-employee figures and writes nothing.

Use when: A month or quarter end without a salary run, when the balance sheet should carry the vacation liability as it stands (for example before a bokslut or a report to the bank).

Don't use for: The yearly semesterårsavslut that rolls days into the next vacation year (POST /salary/vacation-year-close), or reading the liability without booking (GET /reports/vacation-liability).

Pitfalls

  • as_of must not be in the future: 400 VACATION_LIABILITY_DATE_AHEAD.
  • A closed or locked period, or a date on or before the company lock date, answers 400 PERIOD_LOCKED; no voucher number is spent.
  • Salary runs count when they are booked and were paid on or before as_of, or deduct leave that ended by then. Book the month's run first, or reconcile as of a date before it.
  • A posted verifikat is permanent: undo it with storno (POST /journal-entries/{id}/reverse), never by editing. After a storno the report starts from the previous remeasurement or close again.

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.

Request body

NameTypeRequiredDescription
as_ofstringyesThe date the liability is valued and booked at (YYYY-MM-DD), today or earlier.

Response fields

NameTypeDescription
as_ofstring
adjustedbooleanFalse when every difference stayed within 1 krona: nothing was booked.
journal_entry_idstring | null
voucher_seriesstring | null
voucher_numbernumber | null
booked_2920number
booked_2940number
computed_liabilitynumber
computed_avgifternumber
difference_2920numberComputed minus booked on 2920 (positive: the books held too little).
difference_2940number

Example request

{
  "as_of": "2026-10-31"
}

Example response

{
  "data": {
    "as_of": "2026-10-31",
    "adjusted": true,
    "journal_entry_id": "9a0b…",
    "voucher_series": "K",
    "voucher_number": 41,
    "booked_2920": 48210,
    "booked_2940": 15147.58,
    "computed_liability": 60550,
    "computed_avgifter": 19024.81,
    "difference_2920": 12340,
    "difference_2940": 3877.23
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/salary/vacation-year-close

salary.vacation-year-close · scope payroll:write

Close a vacation year (semesterberedning + arsavslut).

Rolls every active employee's vacation balances into the next year (only days above the 20-day must-take floor are saved; saved days older than 5 years become forced payouts) and reconciles the day-valued semesterlöneskuld against the booked 2920/2940, posting one adjustment verifikation when drift exceeds 1 kr. The frozen report is stored with the closure (BFL 7 kap).

Use when: Once per year after the vacation year ends (Jan for calendar basis, Apr for statutory). ALWAYS dry-run first and review the report: the close is not reversible via API.

Don't use for: Mid-year balance corrections (fix the source: absence days, opening balances, or run corrections). Paying out expired days (create a semesterersattning line in the next salary run: the close only flags them).

Pitfalls

  • dry_run=true returns the full review report with zero writes: treat it as mandatory before the live call.
  • 409 VACATION_YEAR_ALREADY_CLOSED on replay: the closure row is the idempotency anchor.
  • 423-style PERIOD_LOCKED when the adjustment date falls in a locked period: unlock or close without adjustment (book_adjustment=false) and post manually.
  • Untaken days at or below the 20-day floor are flagged in the report, NOT auto-saved (Semesterlagen 18 §).

Risk: high · 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
vacation_year_startstringno
book_adjustmentbooleanno

Response fields

NameType
vacation_year_closure_idstring
adjustment_entry_idstring | null
reportunknown (optional)

Example request

{
  "book_adjustment": true
}

Example response

{
  "data": {
    "vacation_year_closure_id": "vyc_a1b2…",
    "adjustment_entry_id": "je_c3d4…",
    "report": {
      "vacation_year_start": "2025-01-01",
      "rows": [],
      "sek": {
        "drift_2920": 8690.84
      }
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.update · scope payroll:write

Update a draft salary run.

Updates payment_date, voucher_series, or notes on a draft salary run. ONLY allowed when status === "draft": once :calculate has advanced the run to review, these fields are frozen because they feed into the verifikation that :book will eventually post.

Use when: You created a draft, then noticed payment_date should be different (e.g. moved from the 25th to the 23rd) before running :calculate.

Don't use for: Changing period_year / period_month (immutable: DELETE the draft and create a new one). Modifying employees in the run (not in v1 PR-1 scope).

Pitfalls

  • Returns 400 SALARY_RUN_PATCH_NOT_DRAFT if status !== "draft".
  • period_year + period_month are immutable post-create.
  • payment_date may fall outside the run's period month (lön i efterskott): the AGI redovisningsperiod follows the payment month (kontantprincipen), so a run for August paid on 25 September is declared for September.
  • Supplying payment_date clears every roster row's calculation_breakdown, so an already-calculated run must be recalculated before :approve/:book.

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
payment_datestringno
voucher_seriesstringno
notesstring | nullno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this salary run: srun_ plus its id as 32 lowercase hex. Accepted wherever the id is.
period_yearnumber
period_monthnumber
payment_datestring
deviation_period_startstring | null
deviation_period_endstring | null
status"draft" | "review" | "approved" | "paid" | "booked" | "corrected"
voucher_seriesstring
total_grossnumber
total_taxnumber
total_netnumber
total_avgifternumber
total_vacation_accrualnumber
total_employer_costnumber
salary_entry_idstring | null
avgifter_entry_idstring | null
vacation_entry_idstring | null
agi_generated_atstring | null
agi_submitted_atstring | null
calculation_paramsunknown (optional)
approved_bystring | null
approved_atstring | null
paid_atstring | null
booked_atstring | null
booked_bystring | null
notesstring | null
created_atstring
updated_atstring

Example request

{
  "payment_date": "2026-05-23"
}

Example response

{
  "data": {
    "id": "run_…",
    "payment_date": "2026-05-23",
    "status": "draft"
  }
}

PATCH /api/v1/companies/:companyId/salary-runs/:id/lines/:lineId

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

Update a payslip line in a draft salary run.

Updates fields on a salary_line_items row (amount, description, quantity, unit_price, item_type, account_number, one_off_tax_percent, vacation_category, vacation_saved_year) while the run is a draft. The flags follow from item_type: flags in the patch are ignored, and a changed item_type brings its own. Amounts are rounded to whole öre. one_off_tax_percent: null removes the engångsskatt and returns the line to table taxation. vacation_category: null returns a vacation line to this year's paid days. A text row (item_type text) stays words only: its amount stays 0 and it has no account. account_number is an override only: null drops it so the line books on the default resolved at booking (item_type, employment_type, personnel_category), and changing item_type drops a stored override unless the same PATCH sets account_number.

Use when: You spotted a wrong amount or description on a manual line before calculating: fix it in place instead of delete + recreate.

Don't use for: Post-calculation tax/avgifter adjustments (review-stage overrides are not on v1). Engine-derived lines (absence/benefits): they are regenerated by :calculate, so edits are overwritten.

Pitfalls

  • Draft-only: 400 SALARY_RUN_LINE_NOT_DRAFT once the run has advanced.
  • A lineId that belongs to a different run returns 404 SALARY_LINE_NOT_FOUND.
  • 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 line the calculation owns (absence, Övertid 50/100 % and OB rows, förmån and recurring-line rows, the engine's semesterersättning and öresavrundning rows), or a patch changing item_type to such a type, returns 400 SALARY_LINE_CALCULATED: the next :calculate would overwrite the edit. Change the source (absence, worked hours, the förmån, the recurring line) instead.
  • The row is validated as it reads after the patch: changing item_type to one that cannot carry engångsskatt, or making the amount non-positive, on a line that carries one_off_tax_percent is refused with 400 VALIDATION_ERROR; clear the percentage (null) in the same call.
  • vacation_category (paid, extra_paid, saved, unpaid, advance) is only valid while item_type is vacation, and vacation_saved_year only with category saved; a patch that breaks either is refused with 400 VALIDATION_ERROR.
  • A patch that sets amount, quantity or item_type is checked as the line will read: a 0 kr amount is refused with 400 VALIDATION_ERROR (details.field amount) on every line but a text row, except a vacation line carrying its days in quantity, and so is a sign the type cannot mean (a positive bruttolöneavdrag, a negative skattefri ersättning or förmån). For words without money use a text row.
  • A text row (item_type text) takes description and sort_order: a non-zero amount, a quantity or a unit_price is refused with 400 VALIDATION_ERROR, and account_number in the patch is ignored (stored null). A line never changes into or out of a text row (400 VALIDATION_ERROR, details.field item_type): DELETE it and POST a new one.

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"no
descriptionstringno
quantitynumberno
unit_pricenumberno
amountnumberno
account_numberstring | nullno
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
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

{
  "amount": 5500
}

Example response

{
  "data": {
    "salary_line_item_id": "sli_31c9…",
    "amount": 5500
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/salary/premium-rules/:id

salary.premium-rules.update · scope payroll:write

Update an OB or overtime premium rule.

Patches any subset of the rule fields. The scope pair, the amount field of the form and the validity order are validated on the merged state. Sending amount_form switches the form and clears the fields of the other forms, so send the new form's field with it. Set valid_to to end a rule on a date, or is_active=false to switch it off.

Use when: A kollektivavtal changed a window, or a rule should end on a date (valid_to). For a new rate from a date, end this rule and create a new one, so runs before the date keep the old rate.

Don't use for: Retroactive corrections of booked runs (use the salary run correction flow, which recomputes from the dated rules).

Pitfalls

  • Changing the rate in place changes it for every date the rule covers, including open runs of earlier periods; a dated step is a new rule.
  • A field of another form without amount_form returns 400 SHIFT_PREMIUM_RULE_FORM_INVALID.
  • Flipping applies_to_all_employees to false without applies_to_employee_ids returns 400 SHIFT_PREMIUM_RULE_SCOPE_INVALID.
  • Named employee ids are re-verified whenever the list or the form changes.

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
namestringno
day_of_weeknumber[]no
start_timestringno
end_timestringno
amount_form"percent_of_hourly" | "monthly_divisor" | "sek_per_hour"no
premium_percentnumberno
monthly_divisornumberno
sek_per_hournumberno
hourly_divisornumber | nullno
valid_fromstringno
valid_tostring | nullno
item_type"overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday"no
prioritynumberno
applies_to_all_employeesbooleanno
applies_to_employee_idsstring[]no
is_activebooleanno

Response fields

NameType
premium_rule_idstring
namestring
applies_to_all_employeesboolean
applies_to_employee_idsstring[]
day_of_weeknumber[]
start_timestring
end_timestring
amount_form"percent_of_hourly" | "monthly_divisor" | "sek_per_hour"
premium_percentnumber | null
monthly_divisornumber | null
sek_per_hournumber | null
hourly_divisornumber | null
valid_fromstring | null
valid_tostring | null
item_type"overtime_50" | "overtime_100" | "ob_weekday_evening" | "ob_weekend" | "ob_night" | "ob_holiday"
prioritynumber
is_activeboolean
created_atstring
updated_atstring

Example request

{
  "valid_to": "2026-03-31"
}

Example response

{
  "data": {
    "premium_rule_id": "c3f2…",
    "name": "OB kväll",
    "applies_to_all_employees": true,
    "applies_to_employee_ids": [],
    "day_of_week": [
      1,
      2,
      3,
      4,
      5
    ],
    "start_time": "18:00",
    "end_time": "06:00",
    "amount_form": "monthly_divisor",
    "premium_percent": null,
    "monthly_divisor": 480,
    "sek_per_hour": null,
    "hourly_divisor": null,
    "valid_from": "2025-04-01",
    "valid_to": "2026-03-31",
    "item_type": "ob_weekday_evening",
    "priority": 0,
    "is_active": true,
    "created_at": "2026-10-27T08:00:00Z",
    "updated_at": "2026-10-27T09:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/salary/settings

salary.settings.update · scope payroll:write

Partially update the company payroll settings.

Patches the payroll settings: salary_pay_day (1-28), salary_deviation_period (same_month | previous_month), preferred_payment_format (pain001 | bg_lb), salary_default_bank (swedbank | seb | handelsbanken | nordea | other | null), salary_net_rounding (boolean), salary_payslip_show_employer_cost (boolean), salary_payslip_show_breakdown (boolean), salary_calculation_policy (an object with any of partial_month: workdays | annual_calendar_days, sick_rate: daily_divisor | annual_hourly, long_leave: workdays | calendar_after_five_workdays, leave_context: all_registered | through_deviation_end, net_rounding: up | nearest, one_off_tax_rounding: truncate | nearest; merged key by key into the stored policy) and salary_voucher_series (one letter A-Z). All fields optional; at least one must be supplied; unknown fields are rejected. Upserts: a company without a settings row gets one created with the supplied values and DB defaults for the rest. Returns the full resource after the write. Idempotent (mandatory Idempotency-Key). Dry-runnable: ?dry_run=true returns the merged resource without writing.

Use when: You are onboarding a customer for payroll over the API (set the pay day, avvikelseperiod, calculation conventions, payment file format and voucher series before the first run), a customer changes pay day, or a customer migrated from Fortnox needs the same partial-month, sick-pay and long-leave conventions as their old payslips.

Don't use for: Invoice payment and contact details (PATCH /api/v1/companies/{companyId}/settings). Changing the payment date or deviation window of an existing run (PATCH /salary-runs/{id}, or explicit deviation_period_start/end on POST). Changing the conventions of a run that is already calculated (recalculate the draft, or :correct a booked run). Tax and legal profile changes (not on the public API).

Pitfalls

  • Only an owner or admin of the company may change settings: other members get 403 FORBIDDEN, on a dry run too.
  • Idempotency-Key is mandatory; calls without it return 400.
  • At least one field must be supplied; an empty body returns 400. Unknown fields return 400 (strict body), also inside salary_calculation_policy.
  • salary_payslip_show_employer_cost and salary_payslip_show_breakdown only change the payslip copy the employee receives (the emailed payslip link, and GET /salary-runs/{id}/payslips/{employeeId}/pdf?audience=employee). The employer view (the same PDF endpoint without audience) always prints both sections. The breakdown steps carry the employer cost figures, so salary_payslip_show_employer_cost=false also hides Beräkningsunderlag on the employee copy, whatever salary_payslip_show_breakdown says (its stored value is kept and applies again once the employer cost is shown). Both default to true. A change applies to runs whose payslips have not yet gone to employees: the first send or employee-copy download of a run fixes its sections on the run, and payslips already handed out keep the content they were issued with.
  • salary_deviation_period is snapshotted onto each salary run at creation: changing it never moves a run that already exists. Set it before the first run of a new month. Switching later makes the next run's deviation window overlap the previous run's window, and that run is refused with 409 SALARY_RUN_DEVIATION_PERIOD_OVERLAP (pass explicit deviation_period_start/end on that one run to bridge the switch).
  • salary_pay_day only drives the default payment_date of NEW runs (the day of the pay month, 1-28 so it exists in every month). Existing runs keep their payment_date; override per run on POST /salary-runs.
  • salary_voucher_series is an alias for company_settings.default_voucher_series_per_source_type.salary_payment. Writes MERGE that one key into the per-source-type map; the other source types keep their letters. The default company layout books salaries on K.
  • preferred_payment_format: pain001 (ISO 20022) is the default; bg_lb (Bankgirot Leverantörsbetalningar / Lön) is being retired by the banks during 2026, so only pick it for a customer whose bank still accepts LB files.
  • salary_calculation_policy holds the company's calculation conventions (beräkningsprinciper). Every key defaults to the historical Accounted behaviour; a customer migrated from Fortnox usually wants partial_month=annual_calendar_days (månadslön × 12 / 365 per calendar day employed), sick_rate=annual_hourly (timlön = månadslön × 12 / (52 × veckoarbetstid) for sjuklön), long_leave=calendar_after_five_workdays (leave longer than five working days deducted per calendar day at månadslön × 12 / 365, a whole month = the monthly salary) and, with salary_net_rounding, net_rounding=nearest. Compare one historical payslip before switching.
  • A PATCH of salary_calculation_policy is merged key by key into the stored policy (omitted keys keep their value); the response and the stored value always carry all seven keys. It is not snapshotted onto existing runs at creation: the conventions are read at :calculate and frozen into the run's calculation_params, so a draft recalculated after a change follows the new conventions and a calculated run does not.
  • long_leave=calendar_after_five_workdays is a five-day-week rule: :calculate refuses (400 VALIDATION_ERROR) a monthly employee whose workdays_per_week is not 5 while it is on. leave_context only matters under that convention.
  • one_off_tax_rounding governs engångsskatt on payslip lines that carry one_off_tax_percent (POST /salary-runs/{id}/employees/{employeeId}/lines); truncate (öretal bortfaller) is the statutory rule, nearest exists to reproduce another system's history.
  • vacation_day_value is how one paid semesterdag is valued under sammalöneregeln when the semesterlöneskuld is computed (the vacation-liability report, the vacation-year close, the vacation-balance estimate and the remeasurement): daily_divisor = månadslön / 21 at a five-day week (the historical value), percent_4_6 = 4,6 % of the månadslön, as Fortnox and Spiris value it. It never changes what a payslip pays. Valuations read the company's current value, not a run snapshot.
  • salary_default_bank: null clears the bank; omitting the field leaves it unchanged. It only pre-selects upload instructions in the dashboard, and only when the account the payment file pays from is at a bank without instructions there. It changes neither the payment file format nor the account the file pays from: that is the bank account the salary is booked on, the company's primary bank account.

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
salary_pay_daynumberno
salary_deviation_period"same_month" | "previous_month"no
preferred_payment_format"bg_lb" | "pain001"no
salary_default_bank"swedbank" | "seb" | "handelsbanken" | "nordea" | "other" | nullno
salary_net_roundingbooleanno
salary_payslip_show_employer_costbooleanno
salary_payslip_show_breakdownbooleanno
salary_calculation_policyobjectno
salary_voucher_seriesstringno

Response fields

NameType
company_idstring
salary_pay_daynumber
salary_deviation_period"same_month" | "previous_month"
preferred_payment_format"pain001" | "bg_lb"
salary_default_bank"swedbank" | "seb" | "handelsbanken" | "nordea" | "other" | null
salary_net_roundingboolean
salary_payslip_show_employer_costboolean
salary_payslip_show_breakdownboolean
salary_calculation_policyobject
salary_voucher_seriesstring

Example request

{
  "salary_pay_day": 25,
  "salary_deviation_period": "previous_month",
  "salary_default_bank": "swedbank",
  "salary_net_rounding": true,
  "salary_calculation_policy": {
    "partial_month": "annual_calendar_days",
    "sick_rate": "annual_hourly",
    "long_leave": "calendar_after_five_workdays",
    "net_rounding": "nearest"
  },
  "salary_voucher_series": "K"
}

Example response

{
  "data": {
    "company_id": "aaaa1111-2222-4333-8444-555566667777",
    "salary_pay_day": 25,
    "salary_deviation_period": "previous_month",
    "preferred_payment_format": "pain001",
    "salary_default_bank": "swedbank",
    "salary_net_rounding": true,
    "salary_payslip_show_employer_cost": true,
    "salary_payslip_show_breakdown": false,
    "salary_calculation_policy": {
      "partial_month": "annual_calendar_days",
      "sick_rate": "annual_hourly",
      "long_leave": "calendar_after_five_workdays",
      "leave_context": "all_registered",
      "net_rounding": "nearest",
      "one_off_tax_rounding": "truncate",
      "vacation_day_value": "percent_4_6"
    },
    "salary_voucher_series": "K"
  },
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-05-12"
  }
}

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

salary-runs.delete · scope payroll:write

Delete a draft salary run.

Hard-deletes a salary run. ONLY allowed when status === "draft": once the run has calculated numbers or posted a verifikation, BFL 5 kap immutability applies and storno is the only correction path. CASCADE deletes salary_run_employees and salary_line_items.

Use when: You created a run by mistake or want to recreate it with different period_month. Only draft runs can be deleted.

Don't use for: Reverting a booked run (POST /salary-runs/{id}/correct). Hiding a run from listings (no soft-delete on this table: drafts are truly removed).

Pitfalls

  • Returns 400 SALARY_RUN_DELETE_NOT_DRAFT for any status other than draft.
  • Hard delete: the salary_run_employees + salary_line_items rows cascade away.
  • Idempotent in the absent-row sense: DELETE on a non-existent id returns 404 SALARY_RUN_NOT_FOUND rather than re-emitting a deletion event.

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.

Example response

{
  "data": null
}

DELETE /api/v1/companies/:companyId/salary-runs/:id/lines/:lineId

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

Delete a payslip line from a draft salary run.

Removes a salary_line_items row while the run is a draft. Engine-derived lines (absence, benefits) reappear on the next :calculate; delete the underlying absence/benefit record instead.

Use when: A manual line (bonus, deduction) was added by mistake and the run has not been calculated/advanced yet.

Don't use for: Removing an employee from the run entirely: DELETE /salary-runs/{id}/employees/{employeeId}. Suppressing engine-derived lines: fix the source data (absence days, benefits).

Pitfalls

  • Draft-only: 400 SALARY_RUN_LINE_NOT_DRAFT once the run has advanced.
  • A line the calculation owns (absence, Övertid 50/100 % and OB rows, förmån and recurring-line rows, the engine's semesterersättning and öresavrundning rows) returns 400 SALARY_LINE_CALCULATED: :calculate would bring it back. Change the source (absence, worked hours, the förmån, the recurring line) instead.

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.

Example response

{
  "data": null
}

DELETE /api/v1/companies/:companyId/salary/premium-rules/:id

salary.premium-rules.delete · scope payroll:write

Delete an OB or overtime premium rule.

Deletes a rule no payslip line derives from. A rule a calculated run already derived a line from is kept and switched off (is_active=false) instead, so the line keeps the rule it was paid under; it derives nothing on the next calculation. Answers deleted and deactivated.

Use when: A rule was created by mistake, or it should no longer apply at all.

Don't use for: Ending a rule on a date while it still pays before it (PATCH valid_to).

Pitfalls

  • deleted=false with deactivated=true is a success: a payslip line already derives from the rule.
  • Returns 404 SHIFT_PREMIUM_RULE_NOT_FOUND when the id is unknown to this company.

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

NameTypeDescription
premium_rule_idstring
deletedboolean
deactivatedbooleanTrue when a payslip line derives from the rule: kept and switched off instead of deleted.

Example response

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