We are upgrading the MyTax e-service. Due to the upgrade, the service is down from Friday 13 November 4.30 pm to Sunday 15 November 6 pm. Please take care of your tax matters before the service break. Read more about the service outage
Tax Return Status API
The Tax Return Status API is intended for retrieving status information on the following tax returns:
- Value Added Tax
- EU Sales List
- Business tax return for business operators and self-employed persons (5)
- Tax return for agricultural operations (2)
- Tax return for forestry (2C)
- Tax return of business activities – Corporation (6B)
- Annual information return on dividends
The interface returns data about the current processing stage of a specific return in the Tax Administration’s systems. The interface returns only the status of the tax return, not the actual content of the return.
Status Information
Not received
- Indicates that the requested return could not be found at all. Submission or receipt of the return has failed completely.
- The return must be resubmitted or the error in the calling software must be corrected.
Received
- The return has been successfully received, but no automatic decision has been generated for it and the Finnish Tax Administration has not yet started processing it.
- The customer must wait until the return has been processed.
Being Processed
- The return is being processed by the Finnish Tax Administration. The information in the return is under review.
- The return has progressed further in the process. The customer must wait until the return has been processed.
Processed
- The return has been processed (or a decision has been issued for it).
- Check the detailed information of the return in MyTax or through the appropriate API.
- If new actions are initiated by the Finnish Tax Administration regarding the same processed return, for example if a tax reassessment case is opened for a regular tax decision, the same return will be returned by the API with the status "Being Processed".
The interface is designed primarily for organisations acting on behalf of others, i.e. mainly for accounting firms that manage their clients’ taxes on clients’ behalf.
Example starts
Interface documentation:
More information about the interface, the message schema and more detailed descriptions of the parameters can be found in the Vero API portal.
Example ends
Benefits of the interface
- Tax Return Status API allows the user to see the processing status of tax returns in the financial management software so that there is less need to monitor the progress of tax returns separately in MyTax.
- Tax Return Status API reduces the need to switch between systems and introduces tax return status data into the accounting firm’s daily work processes.
- Real-time status data reduces the need for manual monitoring and client-specific checks.
- The interface can be integrated into existing financial management processes and automated workflows.
- Up-to-date information helps the user react more quickly to matters that are being processed by the Tax Administration.
- Time is saved and the amount of manual work decreases, which can improve the accounting firm’s efficiency and customer service.
Example starts
Use case
Tax Return Status API is used by an accounting firm that uses financial management and accounting software into which the Tax Administration's API services have been integrated. The accounting firm manages various corporate clients’ taxes on their behalf based on an authorisation.
The accounting firm files tax returns regarding various tax types on its clients’ behalf using electronic channels. Occasionally, the accounting firm submits or checks its clients’ information in MyTax based on an authorisation.
The accounting firm’s software sends an acknowledgement when a tax return has been submitted to the Tax Administration, but the accounting firm does not receive detailed information about the processing of the return through the software. Each client’s returns must be monitored separately in MyTax. The accounting firm wants to centrally keep track of the processing of its clients’ tax returns in real time without needing to check each client’s information separately in MyTax.
Tax Return Status API allows the accounting firm to see how the processing of its clients’ tax returns progresses. The interface supplements the other Tax Administration interfaces and enables more comprehensive management of tax matters in the financial management software.
The accounting firm can combine the use of the interface with other Vero API interfaces, such as the interfaces for retrieving tax returns (Get return) and for letters or balance information. The accounting firm will thus be able to build a comprehensive processing solution in its software, where first the tax returns’ status data is retrieved and then the more detailed content of decision letters, tax returns or payments. This allows the accounting firm to respond to the information retrieved as necessary, for example to reply to a letter sent by the Tax Administration or pay a client company’s taxes on time. The accounting firm can also build a solution for comprehensive monitoring of all tax returns in its software.
Example ends