# 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/company
```

It 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](https://www.ytj.fi)). 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](https://code.salaxy.com/get-started/environments.md) 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.
