Technical guidance

This section describes the general technical guidelines for the Vero API interfaces. This section is especially useful for a software developer who is starting to develop and use Vero API interface integration for the first time. For more detailed technical descriptions of the interfaces, as well as guidelines can be found in the API Portal documentation for each interface.

Endpoint versioning

Versioning is done for endpoints or for API products when necessary. Versioning is based on sequential number at the end of endpoint address with letter "v", for example https://api.vero.fi/Customer/IDs/ValidateTaxNumber/v3 

Version numbering begins at 1 and whenever a new breaking change is introduced, the version number is increased. A breaking change is for example such where fields have been removed or data types have been changed in a message. Breaking change usually means that users of the service must change their integrations with the service. Please note that adding new optional fields to a message is not considered to be a breaking change. 

The Tax Administration usually supports no more than 2 different versions of one interface: the current version and the version. We expect all users of the previous version to begin using the latest version within the transition period specified for each version change. The documentation appearing in the API portal contains information about new versions. 

The structure of endpoint addresses

The general structure of the Tax Administration’s functional systems is reflected in the structure of endpoint addresses. Addresses are in English, and they consist of the following parts in the production environment: 

Vero API domain: api.vero.fi/ 
Category: Customer/ 
API product name or sub-category: IDs/ 
Name of the service: ValidateTaxNumber/ 
Version: v1

Addresses of test environment endpoints may have additional identifiers to indicate both the environment and that it is a test endpoint, for example: 

Vero API test domain: pintatesti.vero.fi/ 
Test environment ID: FIS/ 
Category: Customer/ 
API product name or sub-category: IDs/ 
Identifier of the test endpoint: Test/ 
Name of the service: ValidateTaxNumber/ 
Version: v1

For a list of current addresses, see the API portal. 

Information in the Header 

Vero-softwarekey

All interfaces require a "vero-softwarekey" header with a software-specific API key. The header is documented in the Vero API portal in the description of each interface. The API key is received from the API portal after the software has been registered.
The Tax Administration uses the information to identify and contact the software developer, if necessary.

Vero-authorizationtoken

The header is used if the interface requires Suomi.fi authorization when acting on behalf of another party. Suomi.fi authorization tokens must be retrieved for the selected customers with the GetToken interface. A customer-specific token is set in the header, which matches with the individual customer being processed in the call.

Service parameters 

There are many data items that relate to individuals’ personal data in the service calls and data-entry inputs that the interfaces work with. Typically, the significant parameter is the personal identity code. No interface parameters are included in the addresses of the calls (as URL parameters) because as such, they could stay stored for a long time in the log data of various servers, and they could expose personal data. Services that use this type of data will use a POST method and include the personally identifiable information in the request body only.

Information about data types 

In general, message structures are based on JSON format where the usual JSON data types are in use: 

string 
number 
Boolean 
null/empty 
object 
array

Files are transferred in JSON message as base64 encoded or separately as type application/binary. JSON messages has to be UTF-8 encoded. 

Dates and timestamps 

The date format is in accordance with the ISO 8601 standard, yyyy-MM-dd. Timestamps must indicate milliseconds and the relevant time zone. Example: 2022-02-25 is the date, and the timestamp is 2022-02-25T14:59:43.397+02:00. When a timestamp is generated in another time zone, the Tax Administration’s system converts the time into local Finnish time. 

Http status codes 

Users receive standard http status codes. Only the “200 OK” message code from the service will indicate that the service call was successful. Typical response values from services are a unique identifier and timestamp, which together serve as an acknowledge-of-receipt message from the Tax Administration. If http status code is something else than 200 then response usually contains detailed error message as JSON structure. 
Other http response codes such as 400 and 500 mean that the inbound call was not accepted, or cannot be answered, for example: “bad request” plus a JSON message containing an error code and the error code’s description or label. Typical errors include structural validation errors, input validation errors, insufficient authorisation, overload, or a downtime situation.  
If the user’s “production” certificate had been obtained the same day when an attempted service call is made, it may be that the interface only returns the “http 500” error until the certificate is properly uploaded in the production environment of Vero API. Vero API services respond to calls made with production certificates only after the certificate has been fully installed in our environment. Certificates for Vero API are retrieved from the Incomes Register's certificate service. In general, production certificates generated in the certificate service during office hours (8.00 am to 4.15 pm) will work in Vero API calls at the latest on the following day.