Appearance
Partner-initiated account creation
For a smooth single sign-on or federation experience, your system usually needs to be sure the company's Salaxy account exists before onboarding starts. Trusted partners can call:
http
POST /v03/api/partner/companyIt returns the public account information if the company, identified by its business ID (Y-tunnus), already has an account. If it does not, it creates an account stub from the Finnish trade register (YTJ). By default, your account gets full access to an account it creates.
Trusted partner role
Required in production; not required in test.
Examples use test-* hosts — see Environments for demo and production.
Request
| Field | Description |
|---|---|
officialId | Required. The business ID (Y-tunnus), used to fetch the company from the trade register |
partnerAccountId | Optional. The company's id in your system. If set, it is stored with the authorisation and every later call must include it |
proxyPartner | Optional. A child partner, in parent–child set-ups: e.g. accounting software (parent) whose accounting firms (children) own the companies. The parent needs access to the child, not to the companies |
language | Optional. The company's UI language: fi, sv or en |
contactFirstName, contactLastName | Optional. Contact person |
telephone, email | Optional. Contact details |
Add ?checkAuthorizationOnly=true to check authorisation without creating anything.
Response
| Field | Description |
|---|---|
accountId | The company's id in Salaxy |
avatar | For display: displayName, url, initials, color … |
isVerified | The company has accepted Salaxy's terms and conditions |
isAuthorized | The company has authorised your account — with the right partnerAccountId, if one was given |
partnerAccountId | The partner account id access is currently restricted to |
Every successful outcome returns HTTP 200 with these fields — including a company that has not yet authorised you (isAuthorized: false). It never returns 404 for an unknown company: an account stub is created instead, and with checkAuthorizationOnly=true the answer is 200 with isAuthorized: false.
Errors
Errors return HTTP 400 with error (a short title) and messageHtml (a message you can show — currently in Finnish); validation failures also include a validation object.
json
{ "error": "Y-tunnus on virheellinen", "messageHtml": "Y-tunnus 1234567-9 on virheellinen." }| HTTP | Cause |
|---|---|
| 400 | officialId is missing (Y-tunnus puuttuu) |
| 400 | officialId is not a valid business ID or VAT id (Y-tunnus on virheellinen) |
| 400 | The proxyPartner account does not exist |
| 400 | You are not authorised to the proxyPartner account |
| 400 | officialId is your own company id (Kumppanin oma Y-tunnus) — blocked by design; use your partner account directly |
| 400 | The trade register data failed validation (error starts with VALIDATION) |
| 400 | The trade register returned no company name (Yrityksen nimi puuttuu) |
| 401 | Missing or invalid access token |
In production, a call without the trusted partner role fails before the checks above, so you do not get the structured 400 body — expect a server error.

