Notification Service

Purpose of the service

The Notification Service is an additional service designed to enhance the use of other Vero API interfaces. The service allows user to subscribe and receive different notification types from the Tax Administration. Notification is a simple message that tells you that something taxation-related has happened for a customer. For example, a tax event has occurred for the customer selected in the subscription and a notification is generated based on it. The notification is an indicator that the user of the Vero API interfaces must respond to it.

The notification contains the notification type and the key information to retrieve the actual data content associated with the notification. The user must then select the appropriate interface to retrieve the data. Notifications are stateless and it is the responsibility of the software using the Notification Service to keep track of which notifications have already been processed and how to respond to the received notifications.

Available notification types as of 17 September 2024:

  • EMCS and related activities

Upcoming notification types:

  • Tax cards
  • Letters and decisions
  • Changes to tax period length

Push notification service

The push notification service is an alternative way of receiving notifications directly from the Tax Administration system by receiving JSON calls in the form of push-type notifications. The user does not need to retrieve the newest notifications by periodically accessing the ListNotifications interface.

In the push notification service, the user submits a request for receiving notification types and then registers their own software in the push notification service.

The Benefits of the service for the user

  • The notification service can be used to speed up the data retrieval processes, because there is no need to make Vero API interface calls for each customer continuously, but only for those customers whose data has changed.
  • Usage of resources are diminished in both customer’s and in Tax administration’s systems, because the number of calls is lower. Information is submitted or requested only when it’s necessary.
  • Network traffic is diminished which results saving of costs for the software using the service. The software requires less server capacity and resources. In addition: the costs of cloud-based software might diminish, because the usage of the interfaces is managed better and number of unnecessary calls are lower. Use of cloud service is enhanced when the need for resource usage in interface calls is lesser.
  • The speed up in process times. The user’s software no longer requires large batch jobs -process to send large mass of calls, as they might have done earlier. This will speed up the usage of the software and the data retrieval processes of the correct information. Enhancing process times is also dependable of the user’s software development solutions.
  • The network load for the Vero API services is diminished. The use of the Notification Service will also improve the overall load on the Vero API services, which makes submitting and retrieving of data via the interfaces more efficient. Reducing the network load will also reduce delays in calls response times, and calls will reach the Tax Administration's system and the user's own software more quickly.
  • Push notifications are well suited for real-time use cases where an immediate indication is needed for a change in information, e.g. EMCS export approval.
    • Customer system data can be maintained in real-time with Tax Administration data without lengthy batch processes outside of office hours.

Examples of future use cases:

Tax card inquiry: a user has made a subscription to receive notifications about new tax cards. The user is a payroll office or an accounting office that is using the withholding percentage inquiry API interface. A new tax card is created in the Tax Administration’s system or in MyTax for the customer associated with the subscription (employee). The selected notification type is salary and based on that notification type and the new tax card, a notification is created in the Tax system. The notification is retrieved with the ListNotifications interface or sent to the user via the Push Notification service. Based on the notification, the user can react and retrieve the new tax card information for the payroll using the withholding percentage inquiry API. The user does not need to request the changed tax card information continuously, for example daily for all their employees, but only when the tax card information has changed for certain customers. The customer (employee) does not need to send the tax card to payroll.

Letter inquiries: a user has subscribed to receive new letter notifications. The user is an accounting office which uses the Letter inquiry API interfaces to manage their clients in their tax affairs. A new letter is sent to the client associated with the subscription (the client of the accounting firm) from the Tax Administration, which generates a notification in the Tax system. The notification is retrieved with the ListNotifications interface or sent to the user via the Push Notification service. Based on the notification, the user can react and retrieve the new letter information with the letter inquiry API interfaces. The user does not need to poll for new letters continuously, for example daily for all customers, but only when new letters have arrived.

Steps to use the service

  • Subscribe (API endpoint: Subscribe) Customer system first creates a subscription of notification types for customers they are interested in by calling the Subscribe endpoint. A unique subscription id is provided in the response message.
    • With the Push Notification Service, the user registers their own software’s hosting interface to the service to receive the latest notifications in near real-time to their system.
    • When registering, the user must provide the following: their request’s identifier (SubscriptionID), the URL of the system where they wish to receive push notifications (CallBackURL), and a “secret”, which is a key piece of information that will function as an authentication method when push notifications are sent to the client (CallBackSecret). The secret is determined by the client’s system. This way, the user can be sure that any incoming push notifications were sent by the Tax Administration.
  • Poll for notifications (API endpoint: ListNotifications) When subscription is successfully configured, the customer system polls the ListNotifications endpoint with the subscription id and the appropriate date range to receive available notifications.
    • If you have enabled Push Notifications, you will automatically receive the latest notifications based on your subscription and registration as Push Notifications JSON calls directly to your software. Only the notification key (NotificationKey) is sent in the push notification call. No sensitive, personal- or business information is sent in the Push Notification calls.
    • Retrieve the actual data content of the Push Notification call, using the GetNotification interface.
  • React to notifications (Customer system) When notification have been retrieved by the customer system, decide what to do with it, call other Vero API endpoints to get or send data based on the notification message content. Orchestration of activities is done by the customer system. Keeping track of read notifications is responsibility of the customer system.

Notification Service — other pages

Page last updated 12/18/2023