Skip to content

Company settings ​

Each customer company has settings that payroll needs: contact details, the employer's bank account, and pension and insurance contracts. You can leave them to the embedded white label settings screens, or read and write them over the REST API from your own UI. Examples use the test environment; see Environments for demo and production.

The settings round tripThree steps. One: read the whole settings object from Salaxy. Two: change only the part your own screen owns, such as the employer's bank account. Three: post the whole object back. Salaxy replaces the stored settings with what you post, so anything you leave out is lost.123Read allGET the whole objectChange your partleave the rest as it isPost all backPOST the whole objectA partial POST erases dataSalaxy replaces the settings with the body you send
Always read, change, and post the whole settings object. Never build the body by hand.

Which fits you? ​

Settings in the embedded white label ​

Use this when your customers use the embedded Salaxy UI, Salaxy Business or Salaxy Pro (build path 1). The customer fills in company information, bank account and contracts in the settings screens, in your design. You build nothing, and this page is not needed. See Embedded white label.

Settings through the REST API ​

Use this when you build your own UI (build path 2) and need to own the settings screens. Everything below is for you.

Settings through the REST API: how it works

You write each area through the endpoints below. Salaxy provisions some parts of the settings itself (accounting, Incomes Register, payment channels and others). You never edit those, but you must post them back unchanged. See the round trip.

How it works ​

Settings are written through two objects.

MethodPathHolds
GET, POST/v03/api/accounts/companyCompany information: contact, language, company type
GET, POST/v03/api/settings/companyEverything else: payment account, pension and insurance contracts, and the parts Salaxy provisions
GET, POST, DELETE/v03/api/settings/pensionContracts and /{contractNumber}Pension contracts, one at a time
POST/v03/api/settings/pensionContracts/allReplace the whole list of pension contracts

All of them also exist as /v04/api/.... You call them as the customer company: see Impersonation. The account must exist first: Customer account creation.

The GET, change, POST round trip ​

POST /v03/api/settings/company replaces the stored settings with the body of your request. It does not merge. A sub-object missing from the body is overwritten with empty defaults. That wipes configuration that Salaxy provisioned: accounting, Incomes Register, payment channels, customer funds and more.

  1. Read the whole object: GET /v03/api/settings/company.
  2. Change only the sub-object your UI owns.
  3. Post the whole object back, with every other sub-object exactly as you received it.
Sub-objectContentsWho writes it
payments.invoiceEmployer payment accountYou
calc.pensionContractsPension contractsYou
calc.insuranceContractsInsurance contractsYou
accounting, costAccountingAccounting targets, export and cost-accounting dimensionsSalaxy: post back as it is
calc.incomesRegisterIncomes Register deliverySalaxy: post back as it is
payments.channels, payments.defaultChannel, payments.customerFundsPayment channels and customer fundsSalaxy: post back as it is
payments.channelConfigsPayment channel configs, read-onlyIgnored on save; see Payment channel config
partnerPartner and service modelSalaxy: post back as it is
holiday, reporting, usecase, messaging, forms, payStats, configs, preferencesOther service configurationSalaxy: post back as it is

The server enforces a few fields, so a faithful round trip always succeeds. The partner link cannot be changed: a different partner.accountId is rejected. Service-model pricing is always taken from Salaxy's records. When a contract's company is none, its contractNumber is cleared.

Two parts have an easier route. Pension contracts and cost-accounting dimensions have their own endpoints that keep the other settings intact. The employer's bank account and insurance contracts have none: write them only through the round trip.

Company information ​

Contact details, UI language and company type are on the company account object. Read it, change the fields you manage, post it back.

http
GET https://test-secure.salaxy.com/v03/api/accounts/company
Authorization: Bearer {customer-company-token}
json
{
  "id": "example-company",
  "companyType": "fiOy",
  "language": "fi",
  "contact": {
    "email": "payroll@example.com",
    "telephone": "+358 3 123 4567",
    "street": "Takomokatu 8",
    "postalCode": "33100",
    "city": "Tampere",
    "countryCode": "fi"
  }
}

The object also carries fields that Salaxy manages or that are read-only, such as avatar, serviceModelId, partner and identity. Keep what you receive and post it back unchanged. POST /v03/api/accounts/company returns the saved object with 200.

FieldNotes
contact.emailThe company's salary-related e-mail. Stored lower case and trimmed
contact.telephone, contact.street, contact.postalCode, contact.citycity is the postal town (postitoimipaikka)
contact.countryCodeISO 3166-1 alpha-2; currently always fi
languagefi, sv or en; default follows the account default
companyTypefiOy limited company, fiTm sole proprietor, fiRy association, fiYy other Finnish company or association, unknown. The federation flow uses the same codes

Employer payment account ​

The employer's bank account, used when Salaxy creates payment material on the employer's behalf. It is the payments.invoice sub-object of /v03/api/settings/company, written only through the round trip. This is the part you change, inside the full object:

json
{
  "payments": {
    "invoice": {
      "sepaBankPartyId": "12345678",
      "ibanNumber": "FI22 6601 0001 0897 47",
      "bic": "AABAFI22"
    }
  }
}
FieldNotes
ibanNumberThe employer's Finnish IBAN
bicOptional for a Finnish IBAN: derived from the IBAN when you omit it. A bic in a response does not prove that anyone stored one
sepaBankPartyIdThe payer identifier (maksatustunnus) that the employer's bank issued, used in SEPA payment files

The same sub-object holds the e-invoicing fields eInvoiceReceiver and eInvoiceIntermediator. Round-trip them unchanged unless your UI manages e-invoicing.

Pension contracts ​

The employer's statutory earnings-related pension (TyEL) contracts are the calc.pensionContracts array. Most companies have one contract; several are allowed. Two ways to write them:

  • Granular endpoint. POST /v03/api/settings/pensionContracts with one contract adds it, or updates the one with the same contractNumber. GET lists the contracts, GET or DELETE /v03/api/settings/pensionContracts/{contractNumber} reads or removes one. Prefer this when pension is the only part you write.
  • Round trip. Change calc.pensionContracts in the full object. Use this when you write other areas in the same flow.

POST /v03/api/settings/pensionContracts/all replaces all contracts with the array you post.

json
{
  "company": "varma",
  "contractNumber": "55-1234567X",
  "id": null
}
FieldNotes
companyThe provider: ilmarinen, elo, varma, veritas, apteekkien, verso, pensionsAlandia, kevaMunicipal, kevaState, kevaChurch, kevaKela, kevaAland, valio, other, or none. none means no contract and clears contractNumber. etera appears only in old data
contractNumberThe provider's contract number, for example 55-1234567X. The key of the granular endpoint
pensionPercentCustom percent. Leave it unset to use the provider's default, returned read-only as pensionDefaultPercent
pensionDiscountPercentDiscount percent, when the provider has granted one
startDate, endDateOptional validity, as ISO 8601 dates; endDate is inclusive. null means valid without limit. A future startDate keeps the contract inactive until then
subOrgCodeSub-organisation code for the Incomes Register, when the provider requires one

Read-only: id (send null for a new contract), status (undefined, checked or pending) and pensionDefaultPercent.

Insurance contracts ​

The employer's statutory accident insurance and group life insurance are one contract object in the calc.insuranceContracts array. There is no granular endpoint: write them only through the round trip. This is the part you change:

json
{
  "calc": {
    "insuranceContracts": [
      {
        "isPartnerInsurance": false,
        "company": "fennia",
        "contractNumber": "41-1234567",
        "insurancePercent": 0.7,
        "groupLifeInsurancePercent": 0.06,
        "id": null,
        "startDate": null,
        "endDate": null
      }
    ]
  }
}
FieldNotes
companyThe insurer: lähiTapiola, pohjola, if, fennia, aVakuutus, aktia, pohjantähti, tryg, ålands, turva, redarnas, folksam, alandia, protector, other, pending (not chosen yet), or none (knowingly no insurance; clears contractNumber). Send the non-ASCII values in UTF-8 exactly as written
contractNumberThe accident-insurance contract number
insurancePercent, groupLifeInsurancePercentPercents used to estimate the insurance amounts
isPartnerInsurancetrue when the insurance is arranged through a partner insurance
startDate, endDateAs for pension contracts

Read-only: id (send null for a new contract) and status.

Payment channel config ​

Some payment channels need values of the company's own before they can pay for it, such as an agreement id from the payment provider and the bank account that the provider debits. That is the company's payment channel config, at most one per channel.

v04 beta

This endpoint is in v04 only and may change. There is no v03 equivalent. Which channels the company uses stays in payments.channels and is Salaxy's. Your provisioning notes say which channel needs a config, and its channel key. The OpenAPI reference lists the path once for each channel that takes a config, with that channel's key in place of {channel}; a channel without a config has no path.

MethodPathPurpose
GET/v04/api/settings/payment-channels/{channel}/configRead; the version is in the ETag header
PUT/v04/api/settings/payment-channels/{channel}/configCreate or replace: 201 the first time, then 200; safe to retry
PATCH/v04/api/settings/payment-channels/{channel}/configChange named fields, as a JSON Merge Patch (Content-Type: application/merge-patch+json)
DELETE/v04/api/settings/payment-channels/{channel}/configRemove; 204

The configs also show in the settings as payments.channelConfigs, read-only. POST /settings/company ignores that field, so the round trip can never change or erase a config. For a channel that needs a debit account and an agreement id:

json
{
  "debitAccount": { "iban": "FI21 1234 5600 0007 85" },
  "data": { "agreementId": "AG12345678" }
}

debitAccount.bic is filled in from a Finnish IBAN when omitted. data.agreementId is required, at most 35 characters. Salaxy stores the IBAN without spaces.

  • Concurrent writes. Send the ETag you read as If-Match on PUT, PATCH or DELETE. If the config changed in between, the write fails with 412. If-None-Match: * makes a PUT create-only.
  • Errors are problem details. Branch on type or the status. A 422 lists messages per field.

What payment needs ​

Do not over-build the settings screens. Of everything above, only a usable payment channel is a company setting that payment requires.

SettingRequired to pay?
Payment channel on the payroll (defaults from payments.defaultChannel)Yes
Employer IBAN and sepaBankPartyIdNo gate. They are read when a SEPA file is made. A missing value is a warning in the settings check
Pension contractNo gate. Without one the calculation runs as a temporary employer, and the employer's street, city and postal code become required
Business IDNot checked at payment

The other payment gates are on the account (isVerified: see Customer account creation) and on the calculation. A calculation that fails validation blocks payment.

Test it ​

  • Create a test company: Get a test account, or Customer account creation.
  • GET /v03/api/settings/company and keep a copy. Change payments.invoice.ibanNumber, post the whole object, and read it again. Every other sub-object must be identical to your copy.
  • To see why the rule exists, post the object without accounting on a throw-away test company, and read it again.
  • Add a pension contract through POST /v03/api/settings/pensionContracts, then through the round trip, and compare.
  • Test data and helpers: Test endpoints and test data.

Checklist ​

  • You never post a hand-built settings object: every write starts from a fresh GET.
  • You change only the sub-object your screen owns and post the rest unchanged.
  • Pension contracts use the granular endpoint when they are the only change; insurance contracts and the bank account go through the round trip.
  • You send null as id for a new contract and do not edit status or pensionDefaultPercent.
  • Your screens do not block payment on missing IBAN or pension; they warn instead.
  • With the embedded Salaxy UI (build path 1), its settings screens are used and this page is skipped.

Next: Accounting firm account creation

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.