apidays Helsinki & North 2025 - Vero APIs - Experiences of API development in Finnish Tax Administration, Tuomo Hyttinen (Tax Administration of Finland)

Vero APIs - Experiences of API development in Finnish Tax Administration
Tuomo Hyttinen, ICT specialist at Tax Administration of Finland

apidays Helsinki & North 2025 - APIs for Innovation, Intelligence, and Impact
June 3 & 4, 2025

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Vero APIs - Experiences of API development in Finnish Tax Administration
2. Agenda Overview of Vero APIs Internal development process in FTA Best practices in API development
3. Tuomo Hyttinen ICT-specialist in API team • Almost 7 years in Finnish Tax Administration (Vero) • Experience in different roles in multiple IT- projects at Vero  Testing  Requirement definition  Coordination & management  Service design  Training & demos  Documentation • LinkedIn: Tuomo Hyttinen
4. What are the Vero API interfaces? • Vero API is an interface service provided by the Finnish Tax administration (Vero). • Vero APIs are meant for reporting or retrieving taxation-related information in real-time. • Vero APIs have variety of use cases in taxation. • The tax administration designs, develops and releases new Vero APIs according to new identified needs of taxation and customers.
5. How do they work? APIs allow data to be reported directly to the tax administration through the taxpayer's own system. E.G. an accounting software is used for handling accounting and tax affairs with APIs. Real time services, typically single return filings and queries. REST API/JSON payload HTTPS/TLS 1.2+ Client certificate authentication (mTLS) API keys Suomi.fi authorization (certain APIs only)
6. Examples of API use cases Submit tax returns All the companies' tax returns (e.g. VAT, income tax, annual information returns, car tax) EMCS (Excise Movement and Control System) returns Inquiry tax related data Employer can check an employee's current tax rate (tax cards) Correspondence (letters) Register status Payment transactions Submit other taxation related information Household expenses data on behalf of an individual customer Data about rental targets for income taxation
7. Why are the APIs useful in taxation? Better utilization of resources & Reducing Manual Work Automated data exchange reduces need for manual work and processing of tax related data, saving thousands of hours in labor costs for tax administration and for tax liable companies and individuals. Reducing administrative workload—automatic and error-free data transfers processes for taxpayers, accounting offices, and tax authorities, minimizing delays, need of postage and paperwork. Tax collection Tax collection and reporting becomes more efficient when different systems can exchange data seamlessly. Benefits to society - tax revenue is allocated to correct public services more efficiently. Secure data transfers prevent unauthorized modifications, ensuring tax compliance and reducing fraud risks.
8. Timeline in Vero APIs - How it all started 2019 – APIs for automation of taxation. First two APIs, API portal & Sandbox. 2020 – Car tax APIs & Withholding data inquiry (most used API today). 2021 – Expansion with VAT, CIT, Letters, Pensions & Role inquiry APIs. 2022 – EMCS system, Notification service & first EMCS APIs launched. 2023 – API portal v2, API keys, verification testing & new APIs. 2024 – Authorization token, push notifications & new API infrastructure.
9. The present and future 2025: over 80 Vero APIs in production currently.  The APIs are a well-established and integral part of the whole taxation system in Finland  Over 6000 companies use the APIs.  E.g. so far in 2025, 2.6 million employees tax cards have been queried, using the tax card API.  150 000 companies, which pay salaries, use the API service via some software in their business.  APIs will become the most important channel to submit and query taxation data in future.
10. How to start using Vero APIs Self-service principle Developers/users can start using Vero API services by self-service - no contact to Vero is needed Users start the introduction and onboarding process in the Vero.fi: https://vero.fi/developer
11. API developer onboarding process Get to know Vero APIs Stage 1 Try APIs in Sandbox Stage 2 Register to API portal Stage 3 Develop and test Stage 4 Acceptance testing Stage 5 Move to production Stage 6
12. Internal development process In FTA New API needs are identified from customer feedback, customer research or internal business needs Taxation teams order new APIs from the API team Taxation team is responsible for requirements, rules, definitions and functional testing API team together with taxation team manages customer communications
13. API team manages the development Technical architecture of interfaces Technical functionality of the integration Technical testing of the integration Common API solutions General data security, access management solutions Developer documentation (API portal) & support Test environments
14. Best practices - organizational Dedicated API Management Team Ensure your team is well-versed in API lifecycle management, including design, development, testing, deployment, and maintenance. Foster a culture of collaboration and continuous learning to keep up with evolving API standards and technologies. Developer Support and Documentation Provide comprehensive and up-to-date documentation using tools like Swagger/OpenAPI 3. Include sample requests, response payloads, and error codes . Offer dedicated support channels for external developers, such as forums, chat support, and regular webinars.
15. Best practices - organizational API Governance Implement policies for API versioning, deprecation, and backward compatibility. Use semantic versioning (e.g., v1, v2) to manage changes. Establish security protocols, including authentication and authorization mechanisms. Performance Monitoring and Analytics Use monitoring tools to track API performance and usage metrics for optimization. Regularly analyze analytics data to make informed, data-driven improvements to API functionality.
16. Best practices - technical Consistent Naming Conventions Use clear, consistent, and intuitive naming conventions for endpoints and data. Avoid abbreviations HTTP Methods and Status Codes Use standard HTTP status codes to indicate the result of requests (e.g., 200 OK, 201 Created, 404 Not Found, 500 Internal Server Error). Security Measures Enforce HTTPS to encrypt API traffic. Implement input validation and sanitization to prevent security vulnerabilities. Use throttling and rate limiting to protect APIs from abuse and ensure fair usage.
17. Best practices - technical Error Handling Provide meaningful error messages and standard error codes. Ensure errors are handled gracefully to improve the developer experience. Documentation and Developer Experience Maintain detailed and user-friendly documentation Include examples and tutorials to help developers get started quickly
18. Collaboration with the software companies API team & developers Slack channel for developers - everyday help API sandbox - explore and test APIs - provide feedback Observation form to send feedback Monthly infos and newsletters Open discussions for new ideas and to understand customer needs Provide test APIs to support the API development
19. Thank you Any feedback or questions: • Ohjelmistotalot@vero.fi • Get started using APIs: Vero API - vero.fi