User management and user invitation use cases

User management and user invitation – use case guide

This guide explains how to invite users to a Netvisor company (käyttäjän kutsuminen) and how to manage existing users' access rights (käyttäjänhallinta) through the API. For element-level details, see the API reference.

The Finnish UI term is shown in italics after the English description, for example accountant (Kirjanpitäjä).

Before you start

Required rights: the API user must have access to the company and, in addition, the User administrator role (käyttäjähallitsija, KH) or Accounting office administrator role (tilitoimiston pääkäyttäjä, TPK) rights.
Production only: the user invitation and user management resources only work in the production environment.
Identifiers: users and companies are identified by their Netvisor keys. The company's key is given in company, and a user's key in user with the attribute type="netvisorkey". Users' keys are returned by getuseraccessrightssummary.nv.

Resources

Area	Resource	Method	Purpose
User invitation	senduserinvitation.nv	POST	Send a user invitation (käyttäjäkutsu)
	getuserinvitations.nv	GET	List invitations and their statuses
	verifyuserinvitation.nv	POST	Verify an invitation and open the user's access
	canceluserinvitation.nv	POST	Cancel an invitation
User management	getuseraccessrightssummary.nv	GET	List users and their roles, profiles and validity
	edituseraccessrights.nv	POST	Change a user's roles and access profiles
	changeuseraccessrightsvalidity.nv	POST	Set the validity period of a user's access
	deleteuseraccessright.nv	POST	Remove a user's access to a company

Use case: invite a user

The invitation lifecycle

Step	What happens	Invitation status
1. Send	Your integration sends the invitation with `senduserinvitation.nv`. Netvisor creates a one-time link and sends it to the invitee.	`WaitingForAuth`
2. Authenticate	The invitee opens the link and authenticates.	`Authenticated`
3. Verify	Your integration verifies the invitation with `verifyuserinvitation.nv`. The user's access to the company opens.	`Verified`

An invitation can also end in Cancelled (cancelled with canceluserinvitation.nv), or in one of the error statuses EmailSendingFailed, SmsSendingFailed or TwoFaFailed. The invitation is valid for a limited time; its expiry time is returned by getuserinvitations.nv.

Step 1 – Send the invitation

senduserinvitation.nv sends an invitation to a new or existing user. The invitee's email address becomes their username.

Element	Notes
`type`	Invitation type: `NewUser` (new user, Uusi käyttäjä) or `Employee` (employee, Työntekijä). See below. Required.
`firstname`	Invitee's first names, max 50 characters. Required.
`lastname`	Invitee's last name, max 50 characters. Required.
`email`	Recipient's email address, max 100 characters. Becomes the username. Required.
`phone`	Recipient's phone number, max 20 characters. Required.
`company`	Netvisor key of the company the user is invited to. Required.
`user`	Netvisor key of an existing user, `type="netvisorkey"`. Required for `Employee`, optional for `NewUser`.
`verifiernotification`	Email address that receives a notification when the invitation has been verified. Optional.

The two invitation types work differently:

	`NewUser` (Uusi käyttäjä)	`Employee` (Työntekijä)
Payroll requirement	None.	Payroll (palkanlaskenta) must be in use in the company; otherwise the invitation fails with an error.
`user` element	Optional.	Required: the user must already exist in Netvisor and already be an employee in payroll.
Creates a new user	Can create a completely new user.	Never creates a new user.
If the user already has access to the company	The invitation is rejected with an error.	Access rights are not added again.
Role the user gets	Company user (Yrityskäyttäjä)	Company user (Yrityskäyttäjä)

Example:

<root>

<type>NewUser</type>

<lastname>Person One</lastname>

<email>demo.person.one@example.com</email>

</senduserinvitation>

</root>

Step 2 – Follow the invitation

getuserinvitations.nv lists invitations issued by your integration, in pages (page, itemsonpage).

Parameter	Use
`company`	Company's Netvisor key. Defaults to the API user's current company.
`netvisorkeys`	Comma-separated invitation IDs.
`invitationtypes`	`Employee`, `NewUser`.
`invitationstatuses`	`WaitingForAuth`, `Authenticated`, `Verified`, `EmailSendingFailed`, `SmsSendingFailed`, `TwoFaFailed`. Defaults to `WaitingForAuth` and `Authenticated`. `Cancelled` cannot be queried and is rejected.
`invitationemail`, `invitationphone`, `invitationfirstnames`, `invitationlastname`	Exact-match filters on the invitee's details.

Each invitation contains the company, the invitee's name, whether the invitee is an existing Netvisor user (ExistingNetvisorUser), the email address and phone number given in the invitation, the invitation type and status, and timestamps for creation, expiry, authentication and verification, together with who created and verified the invitation.

Step 3 – Verify the invitation

When the invitee has authenticated, call verifyuserinvitation.nv with the invitation's Netvisor key in netvisorkey. The invitation moves from Authenticated to Verified, and the user's access to the company opens. The call returns FAILED if the invitation is not in the Authenticated status.

Cancel an invitation

canceluserinvitation.nv cancels an invitation that has not been completed (netvisorkey). The invitation is marked Cancelled and the invitation link stops working immediately. The call returns FAILED if the invitation does not exist or has already reached Authenticated, Verified or Cancelled.

Use case: manage users' access rights

List users and their rights

getuseraccessrightssummary.nv returns the users of one company with their roles, access profiles and validity.

Parameter	Use
`company`	Company's Netvisor key. Defaults to the API user's current company.
`users`	Comma-separated user Netvisor keys. Without it, all users the API user can see are returned.
`listallusercompanies`	`true` = return every company each listed user can access, instead of one company. Requires `users`, and only companies the API user has access to are listed.

For each user, the response contains the Netvisor key, first name, last name, roles, access profiles and, when both are set, the validity period (ValidFrom, ValidTo).

Role in the response	Netvisor UI name
`IsCompanyAdmin`	Company administrator (Yrityksen pääkäyttäjä)
`IsAccountOfficeSuperUser`	Accounting office super user (Tilitoimiston pääkäyttäjä)
`IsUserAdmin`	User administrator (Käyttäjähallitsija)
`IsAuditor`	Auditor (Tilintarkastaja)
`IsAccountant`	Accountant (Kirjanpitäjä)
`IsPayrollAccountant`	Payroll accountant (Palkanlaskija)
`IsPayrollPersonnelManager`	Supervisor (Esihenkilö, E)
`IsPayrollEmployeeController`	Personal data administrator (Henkilötietojen hallinnoija, HH)

Change roles and access profiles

edituseraccessrights.nv changes an existing user's roles and access profiles in one company. user and company are required. The update is partial: elements you leave out are not changed.

Element	Netvisor UI name	Values
`isuseradmin`	User administrator (Käyttäjähallitsija)	0 = off, 1 = on
`isaccountant`	Accountant (Kirjanpitäjä)	0 = off, 1 = on
`isauditor`	Auditor (Tilintarkastaja)	0 = off, 1 = on
`ispayrollaccountant`	Payroll accountant (Palkanlaskija)	0 = off, 1 = on
`ispayrollpersonnelmanager`	Supervisor (Esihenkilö, E)	0 = off, 1 = on
`ispayrollemployeecontroller`	Personal data administrator (Henkilötietojen hallinnoija, HH)	0 = off, 1 = on
`accountingprofile`	Accounting access profile (Kirjanpidon käyttöoikeusprofiili)	`AllRights`, `BrowsingRights`, `PurchaseledgerUser`, `SalesledgerUser`, `PurchaseAndSalesLedgerUser`, `CompanyUser`, `NoRights`
`payrollprofile`	Payroll access profile (Palkkahallinnon käyttöoikeusprofiili)	`EmployeeRights`, `AllRights`, `AcceptorRights`, `CompanyManagementRights`, `NoRights`, `BrowsingRights`

To turn a role off, send it explicitly with the value 0. Profile values are not case-sensitive.

Example: give a user the accountant role and full accounting rights, without changing anything else:

<root>

<accountingprofile>AllRights</accountingprofile>

</edituseraccessrights>

</root>

Set the validity period of access

changeuseraccessrightsvalidity.nv sets from when and until when a user's access is valid, without changing their roles or profiles. Use it, for example, for time-limited audits or temporary access.

Element	Notes
`user`	User's Netvisor key, `type="netvisorkey"`. Required.
`company`	Company's Netvisor key, `type="netvisorkey"`.
`useforallcompanies`	0 = apply only to the given company. 1 = apply to every company the API user has access to; `company` is then ignored.
`validfrom` / `validto`	Start and end date, `format="ansi"` (YYYY-MM-DD). Required.

<root>

</changeuseraccessrightsvalidity>

</root>

The call returns FAILED if the user has no access to the company or the date range is invalid.

Remove access

deleteuseraccessright.nv removes a user's access to a company (user and company). A user cannot remove their own access with this resource. The call returns FAILED if the user and company combination does not exist or the API user lacks user administrator rights.

Glossary: English – Finnish

English	Finnish (Netvisor UI)
User management	Käyttäjänhallinta
User invitation	Käyttäjän kutsuminen / käyttäjäkutsu
New user	Uusi käyttäjä
Employee	Työntekijä
Company user	Yrityskäyttäjä
Company administrator	Yrityksen pääkäyttäjä
Accounting office administrator role	Tilitoimiston pääkäyttäjä (TPK)
User administrator role	Käyttäjähallitsija (KH)
Auditor	Tilintarkastaja
Accountant	Kirjanpitäjä
Payroll accountant	Palkanlaskija
Supervisor	Esihenkilö (E)
Personal data administrator	Henkilötietojen hallinnoija (HH)
Accounting access profile	Kirjanpidon käyttöoikeusprofiili
Payroll access profile	Palkkahallinnon käyttöoikeusprofiili
Payroll	Palkanlaskenta

Last updated on

Was this page helpful?