# Pro API (accounting firm tier)

The Pro API (`/v01/api/pro/...`) is the endpoint family for accounting firms: one cross-tenant view over every customer account an accounting firm — or a partner acting as one — is authorised to run payroll for.

Examples use `test-*` URLs. See [Environments](https://code.salaxy.com/get-started/environments.md) for `demo-*` and production hosts.

## Who uses it, and when

- **One audience** — a user signed in as an **accounting firm account**, or a partner acting on behalf of one, on the Salaxy Pro site.
- **One scope** — a cross-tenant view of every customer company the accounting firm is authorised for. Multi-tenant filtering is baked into the server-side search; you never pass an account filter yourself.
- **Three-tier integrations only.** The Pro API is used when there is an accounting firm tier between the partner and the customer company (partner → accounting firm → customer company). Two-tier integrations — a partner that operates customer accounts directly, with no accounting-firm layer — do not call the Pro API; they use the per-company `/v0X/api/...` endpoints instead.

For the account roles and the Pro-vs-Company-site split, see [Account structure](https://code.salaxy.com/integration/account-structure.md). To browse the endpoints, see the [Pro API reference](https://code.salaxy.com/reference/rest/v04/pro.md).

## Session and credentials

| Endpoint | Method | Purpose |
|---|---|---|
| `/v01/api/pro/session` | GET | Returns the Pro session, including the active service model. |
| `/v01/api/pro/credentials` | GET | Lists the credentials available to the Pro session. |
| `/v01/api/pro/accounts/{accountId}/token` | GET | Mints a token scoped to one customer company the accounting firm is authorised for. |

Get the Pro session:

```http
GET https://test-secure.salaxy.com/v01/api/pro/session
Authorization: Bearer {your-pro-token}
```

## Account discovery and token minting

| Endpoint | Method | Purpose |
|---|---|---|
| `/v01/api/pro/accounts` | GET | Lists the customer companies the Pro session is authorised for. |
| `/v01/api/pro/authorizingAccounts` | GET | Lists the accounts that have authorised this accounting firm. |

Two constraints shape multi-tier walks:

- **`/accounts` prepends the current account itself** — skip the first entry when recursing; the rest are the accounts that have authorised this session.
- **`/accounts/{id}/token` mints only for an account that *directly* authorised the current session.** A technical account → accounting firm → customer company walk must therefore impersonate **level by level**: mint the accounting firm token from the technical account session, then mint the customer company token *from the accounting firm token*. You cannot mint a grandchild's token straight from the technical account session.

*Diagram: From the technical account session you mint the accounting firm token. From the accounting firm token you mint the customer token. A dashed arc from the technical account straight to the customer token is marked as not allowed: you cannot mint the customer token directly. (Level-by-level token minting: each token is minted from the level directly above it.)*

## Partner-relationship management

These endpoints set or remove the **primary-partner** link on a customer company — which accounting firm account owns the relationship. Setting the primary partner is what gates the `waitingPartnerApproval → paymentAllowed` flow downstream.

| Endpoint | Method | Purpose |
|---|---|---|
| `/v01/api/pro/accounts/{accountId}/partner?serviceModelId={id}` | POST | Sets the accounting firm as primary partner for the customer company, using the named service model. |
| `/v01/api/pro/accounts/{accountId}/partner` | DELETE | Removes the primary-partner relationship. |

Set the primary partner:

```http
POST https://test-secure.salaxy.com/v01/api/pro/accounts/{accountId}/partner?serviceModelId={serviceModelId}
Authorization: Bearer {your-pro-token}
```

The `proxyPartner` field used at account creation is the other side of the same relationship: `proxyPartner` threads a *new* customer company under an accounting firm account at creation time, while `POST .../partner` re-points an *existing* customer company.

## Cross-account search (OData)

The search endpoints query the indexes owned by the Pro session's authorised accounts. They accept standard OData `$filter`, `$top`, `$skip`, `$orderby`, and `$select`, plus a free-text `$search` parameter; the server enforces a maximum page size. See [Queries and paging](https://code.salaxy.com/reference/queries.md) for the query syntax.

Multi-tenant scoping is automatic: you do not pass an account filter, and a forged `accountId` in `$filter` can only *narrow* within the authorised set — it never widens it. An accounting firm account cannot read customer companies that belong to a different accounting firm.

| Endpoint | Returns |
|---|---|
| `/v01/api/pro/payrolls` | Payrolls across the accounting firm's book (e.g. those in `waitingPartnerApproval`). |
| `/v01/api/pro/calculations/editable` | Editable salary calculations (filter shape baked in — see below). |
| `/v01/api/pro/calculations/readonly` | Paid and in-flight calculations (filter shape baked in — see below). |
| `/v01/api/pro/invoices` | Invoices. |
| `/v01/api/pro/workers` | Workers. |
| `/v01/api/pro/messages` | Messages. |
| `/v01/api/pro/files` | Files. |
| `/v01/api/pro/taxcards` | Tax cards. |
| `/v01/api/pro/records` | Records. |
| `/v01/api/pro/ir-epr` | Incomes Register earnings-payment reports. |
| `/v01/api/pro/ir-psr` | Incomes Register payer-summary reports. |
| `/v01/api/pro/household-years` | Household yearly summaries. |
| `/v01/api/pro/settings` | Account settings. |
| `/v01/api/pro/customers` | Customers (free-text + OData). |
| `/v01/api/pro/customers/{refDate}` | Customers for the period that contains a reference date. Not OData: the query takes `periodType` (month by default) and, for a custom period, `endDate`. |

The two `/calculations/...` filter shapes are baked into the server — they are not OData arguments you can override:

- **`editable`** — calculations in `draft`, `proDraft`, `waitingApproval`, `template`, `sharedWaiting`, `sharedApproved`, or `sharedRejected`.
- **`readonly`** — calculations whose payment has started: `paymentStarted`, `paymentSucceeded`, `paymentCanceled`, `paymentRefunded`, `paymentError`, plus internal copies and `feePending`.

Find payrolls waiting for partner approval:

```http
GET https://test-secure.salaxy.com/v01/api/pro/payrolls?$filter=status eq 'waitingPartnerApproval'
Authorization: Bearer {your-pro-token}
```

## Approvals are save-driven

The Pro API exposes **no** `/approve` or `/decline` endpoint. Two gated transitions on the accounting firm's side are instead driven by saving the entity with a target status through the standard endpoints:

| Transition | How to drive it |
|---|---|
| `waitingPartnerApproval → paymentAllowed` (the accounting firm approves a payroll waiting for it) | Fetch the payroll, set `info.status = "paymentAllowed"`, and save it via the standard payrolls endpoint. |
| `proDraft → draft` (the accounting firm releases a calculation so the company can see it) | Fetch the calculation, set `workflow.status = "draft"`, and save it via the standard calculations endpoint. |

Because there is no dedicated approve/decline response, confirm the transition by re-reading the saved entity's status field rather than by checking a response code. The save runs the same validation and snapshotting pipeline as an ordinary edit. For the statuses themselves, see [the payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md).

## Boundary with the Company API

The Pro endpoints answer *"across my whole book"*. Their non-Pro counterparts — the standard `/v0X/api/...` endpoints **without** the `pro/` prefix — answer *"for this one company"* and back the Salaxy Company site. A partner that provisions both a Pro UI and a Company UI from the same integration chooses which family to call by the account type the user signed in as.

## Reference

Browse the full endpoint list:

- [Pro API in the v04 reference (beta)](https://code.salaxy.com/reference/rest/v04/pro.md) — static page for the Pro endpoints.
- [Interactive v04 reference](https://code.salaxy.com/reference/rest-api-v04.md) — run requests against this site's API environment.

The same endpoints are in the v04 reference under `/v04/api/pro/`; this guide uses the `/v01/api/pro/` addresses, which serve them too.

**Next:** [Employees and employments](https://code.salaxy.com/integration/employments.md)
