Skip to content

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.

Creating a customer accountYour system sends the customer's Business ID to Salaxy in one call. Salaxy looks for an existing account. If there is none, Salaxy fetches the company from the Finnish trade register (YTJ) and creates an account stub. Salaxy returns the account id, which your system stores. After that you can set up the company, and the customer completes its own onboarding at its own pace.Your systemsends the Business IDSalaxyfinds or creates the accountCustomer accountyou store its account idTrade registerYTJ, only for a new company
One call finds the account, or creates a stub from the trade register when there is none.

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 ​

MethodPathPurpose
POST/v03/api/partner/companyAssure the account: return the existing one, or create a stub from the trade register
POST/v03/api/partner/company?checkAuthorizationOnly=trueCheck 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/json
json
{
  "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 officialId returns the existing account, so you can retry after a network failure.
  • partnerAccountId sticks. 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 400 whose error starts with VALIDATION. 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 400 with error and messageHtml. See the table in Partner-initiated account creation and Errors.

Verification: what isVerified blocks ​

The response has two flags, and they answer different questions.

FlagQuestionEffect when false
isAuthorizedCan you access this account?Every read and write on the account fails
isVerifiedHas 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 ​

  1. Store accountId. It is the key for everything that follows, and the id you use when you act as this company: see Impersonation.
  2. 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.
  3. Set up the company: Company settings. In the embedded white label, the customer fills these in the settings screens.
  4. Add employees and run payroll: Create employees.

Test it ​

  • Call the endpoint on test-secure.salaxy.com with 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 77 and is unknown to the register is created with the name Test company <Business ID>.
  • Call it twice with the same ID and check that you get the same accountId.
  • Call with ?checkAuthorizationOnly=true for an ID that has no account: expect 200 with isAuthorized: false. Nothing is created.
  • See also Get a test account.

Checklist ​

  • You call the endpoint before onboarding starts, and store accountId and your own partnerAccountId.
  • You treat isAuthorized: false as an access problem, and isVerified: false as a payment-commit problem.
  • You branch on the HTTP status and validation, never on the Finnish error text.
  • 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

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.