Scam messages have been sent out in the Tax Administration’s name. Read more about scams.

Use of Suomi.fi Authorization in Vero API Interfaces

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.

Attention begins.

Interface documentation

More information about the authorization interface, JSON schema and the detailed descriptions of the parameters can be found from the API portal.

Attention ends

Suomi.fi authorization token is mandatory 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. 

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
  • Excise duties
  • 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.
Page last updated 10/7/2025