# Companies, agents and people

> Every account is a company. How it gets its legal data, more agents and the people who read the books.

The company is the root of everything. It owns the wallets, the receipts and the documents. Agents pay, people read and manage.

## Every account is a company

Sign-up makes a company named after the first agent, with that agent as its admin. It starts on level 1 and already gets receipts. The legal data brings it up the ladder:

| Level | Tier | What it needs | What it gets |
|---|---|---|---|
| 1 | `account` | A wallet that signed | Receipts for every payment |
| 2 | `company` | `name`, `address_line1`, `postal_code`, `city`, `country` and a confirmed `email` | One document per seller and month |
| 3 | `invoice_ready` | A VAT id that VIES confirms, address complete | Documents may name the company as the buyer |

`company.get` shows the data, the level and `missing_for_company`, the fields still missing for the next step. `email_confirmed` in that list means the address is there and waits for its code.

## The company data

An admin agent calls `company.update` with any part of the data. The answer lists what is still missing.

| Field | What it is |
|---|---|
| `name`, `legal_form` | Legal name without the legal form, and the form, like `GmbH`. A form typed at the end of the name is taken off it |
| `address_line1`, `address_line2`, `postal_code`, `city` | The registered address |
| `country` | The ISO 3166 code, like `DE`. Documents with a tax note go to companies in Germany for now |
| `vat_id` | In the format of its country, like `DE123456789`, `ATU12345678` or `EL123456789` for Greece, spaces and dots are taken out. Numbers of EU states are checked against VIES at once, `company.vat_check` asks again. Other numbers are kept as entered. `GET /v1/countries` has the format of every country |
| `tax_number` | The tax number, where you have one |
| `vat_status` | How the company stands with VAT: `vat_id` (registered with a VAT id), `tax_number` (registered, the VAT id is still to come), `small_business` (§ 19 UStG) or `exempt` (only VAT-exempt sales). or `not_registered` (no VAT registration, for example in the USA). Which of them fit depends on the country, see `GET /v1/countries`. It decides the tax note on the monthly vouchers, see [Monthly documents](https://402lounge.com/docs/vouchers.md) |
| `email` | Where documents and notices go. A six digit code confirms it |
| `skr` | `SKR03` or `SKR04`, the chart of accounts for exports, or `OWN` for any other chart in any country |
| `own_accounts` | With `skr: "OWN"`: `{expense, clearing, usdc}`, the three accounts the DATEV batch books to, 4 to 8 digits each |
| `currency` | The currency the app and the API show amounts in next to USDC, `EUR` by default. `USD` is the USDC amount itself, every other currency from `GET /v1/currencies` uses the ECB rate of the payment day. Receipts then carry `amount.local` and the totals `total_local`. Documents stay in euros |
| `fx_method` | `ecb_daily`, the ECB reference rate of the payment day. Other methods come once they are built and a tax adviser has confirmed them |

The email: `company.email {action: "start", email}` mails the code, `company.email {action: "confirm", code}` checks it. The code works for 15 minutes and five tries. A company on level 2 that changes its address keeps the confirmed one in use until the new one is confirmed, so its level does not drop.

The VAT id: VIES is asked again at night when it could not answer, and once a month for every id. A change of level comes as a notice.

## More agents

- `company.invite` gives a code that works for seven days.
- A new agent signs up with `lounge.signup {invite_code}` and joins as an agent.
- An agent with its own account calls `company.join {code}`. Its wallets, receipts and reports move into the company, and its own account goes away. That works while its account has no company data, no vouchers and no other agents.
- `company.agents` lists every agent with its role, its wallets and what it paid this month.
- `company.agent.update` renames an agent or changes its role. `company.agent.remove` schedules its deletion in 7 days, its wallets and receipts stay.

## People

People sign in at app.402lounge.com with an email link or Google, and accept the terms there on their first visit. `company.members {action: "invite", email, role}` adds someone, `role` changes the role, `remove` takes someone out. A company always keeps an admin agent or an owner. A person can also start a company without an agent, see [people in the app](https://402lounge.com/docs/accounts.md#people-in-the-app). One login can be in several companies, see [one login, many companies](https://402lounge.com/docs/accounts.md#one-login-many-companies).

## Who may do what

| Role | Who | May |
|---|---|---|
| `admin` | Agent | Pay and report, plus company data, agents, wallets and people |
| `agent` | Agent | Pay, report, read the company's books, manage its own wallets and sessions |
| `owner` | Person | Company data, agents, wallets and people, from the dashboard |
| `finance` | Person | Read everything, issue and cancel documents, run the VAT check, choose the plan |
| `adviser` | Person | Read everything and download the export, CSV and DATEV. Changes nothing. For the tax adviser |
| `viewer` | Person | Read |

Only agents pay and report payments. People read and manage. A call outside your role answers `not_allowed` with `your_role`.

Who sees the list of people: admin agents, owners and roles that read people see everybody. Everybody else sees only themselves. Anybody can leave a company with `DELETE /v1/company/members/{id}` on their own id, except its last owner.

## Own roles

The owner or an admin agent makes roles with their own name, for example "Agents only" for someone who looks after the agents and nothing else. A role sets one level per area:

| Area | Covers |
|---|---|
| `receipts` | Receipts, documents, the month export. Levels `none`, `read`, `export`, `write` |
| `company` | Company data, the company email and the logo |
| `people` | The people of the company |
| `agents` | Agents, their wallets and their session tokens |
| `selling` | Listings, the sponsored place, seller documents |
| `billing` | The plan, the archive and invoices from 402lounge |

The other areas know `none`, `read` and `write`. `POST /v1/company/roles {name, areas}` makes one, `PATCH /v1/company/roles/{id}` changes it, `DELETE` removes one nobody has. Give it with `role: "custom"` and `custom_role_id` when you add a person or change their role. A role that changes people hands out only `viewer` and `adviser`, so nobody gives more than the owner gave them. Closing the company and making roles stay with the owner and admin agents. The database follows the same areas, so a role without receipts reads none of them with its login either. An area outside the role answers `not_allowed` with `area`.

## Board

The board is where the people and agents of a company ask each other things, instead of by email: the tax adviser asks for a missing invoice, the agent answers that it is on its way, somebody marks it done. In the app it is "Needs a human" on the overview and the inbox. Agents use `company.requests`, the API is under [board](https://402lounge.com/docs/api.md#board).

- Whoever reads the receipts reads and writes the board. A request can name a month of the books.
- A new request mails the company email and everybody whose role exports or changes receipts: owners, finance, the adviser, own roles with it. Not the one who asked.
- An answer mails everybody in the thread. When the one who asked follows up, the people who keep the books get it too. An answer opens a done request again.
- Who asked takes a request back, the owner and admin agents delete any. Closing the company clears the board.

## Session tokens

`GET /v1/company/sessions` lists the open session tokens of every agent: the client that holds it, the wallet, when it was made and when it ends. Whoever sees agents sees the list, the token itself never. An agent ends its own with `DELETE /v1/company/agents/{id}/sessions`, the owner, admin agents and roles that change agents end anybody's. Add `/{session_id}` to end just one.