Appearance
Customer account creation
Before you can run payroll for a customer company, the company needs a Salaxy account. A trusted partner creates it, or finds the existing one, with a single call that takes the company's Business ID (Y-tunnus). Do this before you start the customer's onboarding. Examples use the test environment; see Environments for demo and production.
Trusted partner role
Required in production, not in test. The authentication side (who may call, and how) is in Partner-initiated account creation; this page does not repeat it.
Which fits you?
Customer company directly under you
Use this when you serve the companies yourself, with no accounting firm in between. Leave proxyPartner out. Your technical account becomes the customer's parent.
Customer company under an accounting firm
Use this when the company belongs to an accounting firm that you have already created. Set proxyPartner to the accounting firm's account id, so the firm sees the company in its own book. Create the firm first: see Accounting firm account creation.
Both options: how it works
proxyPartner threads the new customer under an accounting firm account at creation time. The caller must be authorised to that accounting firm account. Salaxy sets the parent only if the company has none yet. A company that already sits under another provider keeps its parent. To move it, use the explicit re-point in the Pro API.
Background on the tiers: Account structure.
How it works
| Method | Path | Purpose |
|---|---|---|
| POST | /v03/api/partner/company | Assure the account: return the existing one, or create a stub from the trade register |
| POST | /v03/api/partner/company?checkAuthorizationOnly=true | Check access only; create nothing |
The same call exists as /v04/api/partner/company. The request and response fields are in Partner-initiated account creation. In short:
- Required:
officialId, the Business ID. A*in place of the check digit is accepted (1234567-*); the check digit is computed. - Useful:
partnerAccountId(the company's id in your system),proxyPartner,language(fi,sv,en) and contact details. - Returned:
accountId,avatar,isVerified,isAuthorized,partnerAccountId.
http
POST https://test-secure.salaxy.com/v03/api/partner/company
Authorization: Bearer {technical-account-token}
Content-Type: application/jsonjson
{
"officialId": "1234567-8",
"partnerAccountId": "customer-4711",
"language": "fi",
"email": "payroll@example.com"
}json
{
"accountId": "FI00POYT0001234567",
"avatar": { "displayName": "Example Oy", "initials": "EO" },
"isVerified": false,
"isAuthorized": true,
"partnerAccountId": "customer-4711"
}Rules
- Safe to repeat. A second call with the same
officialIdreturns the existing account, so you can retry after a network failure. partnerAccountIdsticks. Once set, every later call for that account must carry the same value.- Never a 404. An unknown company gets a stub. Access state is in
isAuthorized, not in the status code. - The company name comes from the trade register. The request has no name field. A company that the Finnish trade register does not know is refused with a
400whoseerrorstarts withVALIDATION. A register outage fails the same way, so retry later. There is no manual fallback on this endpoint. - Your own Business ID is refused. Use your partner account directly.
- Errors: every business failure is a
400witherrorandmessageHtml. See the table in Partner-initiated account creation and Errors.
Verification: what isVerified blocks
The response has two flags, and they answer different questions.
| Flag | Question | Effect when false |
|---|---|---|
isAuthorized | Can you access this account? | Every read and write on the account fails |
isVerified | Has the customer authorised Salaxy to act for it? | Creating invoices fails; nothing else |
A new stub starts with isAuthorized: true and isVerified: false. An unverified account is fully usable: you can set it up, add employees, and build salary calculations and payrolls. The refusal comes only when a payroll is committed for payment, as a 400 titled Asiakkaan valtakirjan allekirjoitus/palvelun ehtojen hyväksyntä puuttuu ("the power of attorney or acceptance of the terms is missing").
- Load data first. You can create customers and import employees before the customer finishes its own onboarding. Only the payment step waits.
- Who sees it. When payment is committed in the embedded white label, the customer sees the block, and can resolve it there. Expect a support question, not an API error that you handle.
- Two routes to verified. The company signs its own employer power of attorney (identified through a bank or Suomi.fi), or, where an accounting firm vouches for it, the company accepts the terms with a click.
- A second, different refusal. When the customer is under an accounting firm, that firm must hold a valid, unexpired Incomes Register certificate. Otherwise creating invoices fails with a different
400, and the message names the firm's certificate. It can start failing long after onboarding, when the certificate expires. The remedy is the firm's. - Moving a customer can un-verify it. If the company was verified through the accounting firm's vouching, it stays verified only while that firm remains its billing partner. Moving it to another firm or partner returns it to unverified, with no event and no error. The symptom is payment commits that start failing for one customer that worked yesterday.
What happens after
- Store
accountId. It is the key for everything that follows, and the id you use when you act as this company: see Impersonation. - Check the service model. The company reads its parent's service model from creation, and inherits the payment channel and the accounting model from it. Salaxy links any other model: Service models.
- Set up the company: Company settings. In the embedded white label, the customer fills these in the settings screens.
- Add employees and run payroll: Create employees.
Test it
- Call the endpoint on
test-secure.salaxy.comwith your technical account token. The trusted partner role is not needed in test. - Use a Business ID of a company that really exists. The trade register is the production one, in every environment, so a made-up ID is refused.
- Test-only exception: a checksum-valid Business ID that starts with
77and is unknown to the register is created with the nameTest company <Business ID>. - Call it twice with the same ID and check that you get the same
accountId. - Call with
?checkAuthorizationOnly=truefor an ID that has no account: expect200withisAuthorized: false. Nothing is created. - See also Get a test account.
Checklist
- You call the endpoint before onboarding starts, and store
accountIdand your ownpartnerAccountId. - You treat
isAuthorized: falseas an access problem, andisVerified: falseas a payment-commit problem. - You branch on the HTTP status and
validation, never on the Finnisherrortext. - You do not create invoices for a customer that is unverified, and you show a clear message when the commit is refused.
- In a three-tier set-up you create the accounting firm first and pass its id as
proxyPartner.
Next: Company settings

