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

*Diagram: Your 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. (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](https://code.salaxy.com/security/account-creation.md); 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](https://code.salaxy.com/integration/accounting-firm-accounts.md).

**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](https://code.salaxy.com/integration/pro-api.md#partner-relationship-management).

Background on the tiers: [Account structure](https://code.salaxy.com/integration/account-structure.md).

## 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](https://code.salaxy.com/security/account-creation.md#request). 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](https://code.salaxy.com/security/account-creation.md#errors) and [Errors](https://code.salaxy.com/reference/errors.md).

## 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

1. **Store `accountId`.** It is the key for everything that follows, and the id you use when you act as this company: see [Impersonation](https://code.salaxy.com/security/impersonation.md).
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](https://code.salaxy.com/integration/service-models.md).
3. **Set up the company**: [Company settings](https://code.salaxy.com/integration/company-settings.md). In the embedded white label, the customer fills these in the settings screens.
4. **Add employees** and run payroll: [Create employees](https://code.salaxy.com/get-started/rest/create-employees.md).

## 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](https://code.salaxy.com/get-started/test-account.md).

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