# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Three 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. (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](https://code.salaxy.com/white-label/index.md).

### 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](#the-get-change-post-round-trip).

## How it works

Settings are written through two objects.

| Method | Path | Holds |
|---|---|---|
| GET, POST | `/v03/api/accounts/company` | Company information: contact, language, company type |
| GET, POST | `/v03/api/settings/company` | Everything 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/all` | Replace the whole list of pension contracts |

All of them also exist as `/v04/api/...`. You call them as the customer company: see [Impersonation](https://code.salaxy.com/security/impersonation.md). The account must exist first: [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md).

### 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-object | Contents | Who writes it |
|---|---|---|
| `payments.invoice` | Employer payment account | **You** |
| `calc.pensionContracts` | Pension contracts | **You** |
| `calc.insuranceContracts` | Insurance contracts | **You** |
| `accounting`, `costAccounting` | Accounting targets, export and cost-accounting dimensions | Salaxy: post back as it is |
| `calc.incomesRegister` | Incomes Register delivery | Salaxy: post back as it is |
| `payments.channels`, `payments.defaultChannel`, `payments.customerFunds` | Payment channels and customer funds | Salaxy: post back as it is |
| `payments.channelConfigs` | Payment channel configs, read-only | Ignored on save; see [Payment channel config](#payment-channel-config) |
| `partner` | Partner and service model | Salaxy: post back as it is |
| `holiday`, `reporting`, `usecase`, `messaging`, `forms`, `payStats`, `configs`, `preferences` | Other service configuration | Salaxy: 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`.

| Field | Notes |
|---|---|
| `contact.email` | The company's salary-related e-mail. Stored lower case and trimmed |
| `contact.telephone`, `contact.street`, `contact.postalCode`, `contact.city` | `city` is the postal town (*postitoimipaikka*) |
| `contact.countryCode` | ISO 3166-1 alpha-2; currently always `fi` |
| `language` | `fi`, `sv` or `en`; `default` follows the account default |
| `companyType` | `fiOy` limited company, `fiTm` sole proprietor, `fiRy` association, `fiYy` other Finnish company or association, `unknown`. The [federation](https://code.salaxy.com/security/federation.md) 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"
    }
  }
}
```

| Field | Notes |
|---|---|
| `ibanNumber` | The employer's Finnish IBAN |
| `bic` | Optional for a Finnish IBAN: derived from the IBAN when you omit it. A `bic` in a response does not prove that anyone stored one |
| `sepaBankPartyId` | The 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
}
```

| Field | Notes |
|---|---|
| `company` | The 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 |
| `contractNumber` | The provider's contract number, for example `55-1234567X`. The key of the granular endpoint |
| `pensionPercent` | Custom percent. Leave it unset to use the provider's default, returned read-only as `pensionDefaultPercent` |
| `pensionDiscountPercent` | Discount percent, when the provider has granted one |
| `startDate`, `endDate` | Optional validity, as ISO 8601 dates; `endDate` is inclusive. `null` means valid without limit. A future `startDate` keeps the contract inactive until then |
| `subOrgCode` | Sub-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
      }
    ]
  }
}
```

| Field | Notes |
|---|---|
| `company` | The 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 |
| `contractNumber` | The accident-insurance contract number |
| `insurancePercent`, `groupLifeInsurancePercent` | Percents used to estimate the insurance amounts |
| `isPartnerInsurance` | `true` when the insurance is arranged through a partner insurance |
| `startDate`, `endDate` | As 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.

| Method | Path | Purpose |
|---|---|---|
| GET | `/v04/api/settings/payment-channels/{channel}/config` | Read; the version is in the `ETag` header |
| PUT | `/v04/api/settings/payment-channels/{channel}/config` | Create or replace: `201` the first time, then `200`; safe to retry |
| PATCH | `/v04/api/settings/payment-channels/{channel}/config` | Change named fields, as a JSON Merge Patch (`Content-Type: application/merge-patch+json`) |
| DELETE | `/v04/api/settings/payment-channels/{channel}/config` | Remove; `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](https://code.salaxy.com/reference/errors.md#problem-details-on-new-v04-endpoints). 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.

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

The other payment gates are on the account (`isVerified`: see [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md#verification-what-isverified-blocks)) and on the calculation. A calculation that fails validation blocks payment.

## Test it

- Create a test company: [Get a test account](https://code.salaxy.com/get-started/test-account.md), or [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md).
- `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](https://code.salaxy.com/reference/test-endpoints.md).

## 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](https://code.salaxy.com/integration/accounting-firm-accounts.md)
