Acting on behalf of other organizations with Vero API interfaces

Vero API interfaces allows the user to submit or retrieve data on behalf of their own organization or on behalf of another organization as an authorized representative. If the interface user is acting on behalf of their own organization, a separate Suomi.fi authorization is not required to use the interfaces. However, if the interface user is acting on behalf of another organization, the user may need a Suomi.fi authorization. If a Suomi.fi authorization is required, it is always explained separately in the documentation of the interface in the API portal.

Vero API interfaces use Suomi.fi authorization service provided by the Digital and population data services agency (DVV). Using the authorization service individuals and companies can authorize other individuals or companies to act on their behalf in various administrative matters, such as managing tax affairs. Suomi.fi authorizations can be granted or requested through the Suomi.fi service. For more information about authorizations and how to grant them can be found in here: How to grant a Suomi.fi authorisation for tax matters.

Below are use case examples of how an user can act either on behalf of their own organization or as an authorized representative on behalf of another organization.

Example 1: An accounting office is using an accounting and payroll software, which has an integration built for the List letters request API interface. The accounting office is using the interface to manage their own tax affairs and it uses the interface to request only letters which have been sent for the accounting office itself by the Tax administration. In this case the accounting office is acting on behalf of its’ own organization and it does not manage other organizations tax affairs with this interface. This means that no letters are being request on behalf of other organizations and the accounting office does not need a Suomi.fi authorization to use the interface.

Example 2: An accounting office is using an accounting and payroll software, which has an integration built for the List letters request API interface. The accounting office is managing other companies’ tax and accounting affairs and it is using the interface as a part of this business activity. The accounting office is using the interface to request their business clients’ letters which have been sent by the Tax administration. After retrieving the letters, the accounting office can react to them appropriately. In this case the accounting office is acting on behalf of other organizations and a valid Suomi.fi authorization is required to use the interface.

Suomi.fi authorization tokens

The interfaces have verified the Suomi.fi authorization during each interface call. Each verification has taken 300 - 500 ms and as the number of interface calls increases, this solution is not sustainable. The large number of authorization checks causes slowness in the use of the interfaces. In the future, Suomi.fi authorization will be ensured by a Suomi.fi authorization token, which will be retrieved in advance by the system using Vero API interfaces, for all clients required in the interface transactions.

The interface user must request the Suomi.fi authorization with the GetToken interface before making calls to other Vero API interfaces that require a Suomi.fi authorization. The GetToken interface returns the authorization token for the user.

• The authorization token is a technical signed data structure that contains the Suomi.fi authorizations which have been granted for the interface user. The technical data structure is implemented according to the JSON Web Token model. An authorization token gives the access to act on behalf of another organization for 60 minutes from the moment the token is created.

Authorization token

Suomi.fi authorization tokens are retrieved for each customer for whom the user is acting on behalf within the next hour. The tokens are created with a single Vero API GetToken interface call. The authorization tokens are returned in the response message for each customer who have granted the user Suomi.fi authorizations. The customer-specific authorization token is placed into Vero API call’s header called Vero-authorizationtoken. The use of authorization token speeds up the response times in Vero APIs by 300 – 500 ms per call and reduces the network load to DVV. Using the Vero API GetToken interface the user’s software can verify the authorizations validity before calling other interfaces.

The use of the authorization token will provide the following benefits to the user:

• Makes the use of the interfaces more efficient, as there is no need to perform a separate authorization check from the DVV for each call.
• Increases the reliability of the Vero API interfaces as well as the quality of service by reducing the amount of network traffic to the DVV, resulting in faster operation of all interfaces.
• Using a token also reduces processing and response times for calls in other interfaces.
• The authorization token can also be used to check the current active Suomi.fi authorizations for each customer. Information about the authorizations is retrieved from the DVV authorization service. All valid authorizations are returned for the user when a new token is created.

Suomi.fi authorization token will be mandatory to use starting from 1.5.2024 in all Vero API interfaces which require authorizations when acting on behalf of another organizations. The authorization token will replace the current procedure where authorizations are verified directly from the Digital and population data services agency (DVV) during each API call.

Authorization token is not mandatory to use in interfaces which do not require Suomi.fi authorizations. This change also doesn’t affect situations where users are managing their own data in interface calls. If an interface requires a Suomi.fi authorization, it is informed in the interface’s documentation. The documentation can be found in Vero API portal. The authorization token has been released to production in 31.8.2023 and it has not yet been mandatory to use.

Suomi.fi authorizations are required in the following Vero API interfaces currently:

• Decision and letters interfaces
• Role registration update
• Line of Business and Accounting Period Query
• Tax period inquiry
• Balance specification
• Transaction search
• Car tax decision interfaces and return status inquiry
• EMCS interfaces
• Household expenses reporting interfaces
• Pensions and benefits reporting and Pensions and benefits changed withholding data inquiry
• Value added tax and VAT EC sales interfaces
• Corporate income tax interfaces (prepayment interfaces, send profit distribution, share values inquiry)

Steps in Authorization API usage:

1. Determine and gather a list of customers which are going to be processed in your application.
2. Request authorization tokens for all customers by sending their IDs to GetToken API once or in batches of 3000 customers to gain speed benefits from the GetToken API.
3. GetToken response contains tokens only for those customers the caller has access at the time of the call.
4. Manage customer specific tokens and customer IDs and set the token to Vero-Authorizationtoken header for each Vero API call that requires Suomi.fi authorization.
5. Do all Vero API calls within 60 minutes while the tokens are active. When tokens expire, call the GetToken again.