Integration guide

Welcome to Maventa integration guide!

This guide will tell you how to connect your financial system to Maventa e-invoicing and document exchange service. See how to move from testing to production, what API methods to use for different functionality, as well as get useful tips and routines for integrating.

Let’s go!

Get started

The integration process includes setting up the integration, testing it and finally moving to production.

To get the necessary API keys to testing and production follow the three steps under Integration setup.

Please note that before entering the production environment all integrators are required to fill in and sign Maventa Integration Agreement that outlines important arrangements such as billing and support.

If you haven’t quite yet decided what type of integration to make, see our Overview section. In there you can find guidance how to define the integration scope and level based on the needed functionality and automation.

Integration setup

Step 1 - Create Account to get access to API keys

To start using Maventa APIs, open a test account for your company from here.

When you have registered the company account in testing, contact Integration Care ( or your integration contact point to convert your account into a partner account. At the same time they will create a vendor_api_key for you. This key is linked to your partner account will be used to identify your software interaction with the API.

Step 2 - Start building

After having the necessary API keys you can start building the integration. Follow feature specific guides for detailed instructions on sending, receiving, account & settings configuration and service activation.

Step 3 - Move to production

When integration is created and tested in testing environment and the Integration Agreement has been signed you will receive the keys to move to production. Follow the same process as in testing.

First create a regular account for your company in production from [here. After that contact Integration Care ( or your integration contact point to change the account to partner and create the vendor_api_key.

API keys

To use the API you need three different API keys, which are used in almost every request towards Maventa API:

  • user_api_key (identifies a single user, required in all interaction with API)
  • company_uuid (identifies a single company, required in all interaction with API)
  • vendor_api_key (identifies a partner, required in all partner interaction with API)

User_api_key and the company_uuid are returned when you create new users and companies. The vendor_api_key is given to you by your integration contact point from Maventa.

When using the API keys, make sure they are written as is and ensure there are no extra blanks before or after the key to avoid errors.

In SOAP API, authentication is performed by providing all keys on each request.

In REST API, authentication is performed by using oauth2 standard tokens. See more at REST API Authentication.

Testing environment

In testing server, electronic and print sends outside Maventa are simulated, but internal and e-mail sends work as in production environment. Since emails are actually sent out, make sure to use e-mail addresses that you own when conducting testing to avoid any confusion (e.g. do not use something like since that domain really exists meaning that the e-mail address might also exist)

It is also good to note, that the testing environment is also used for internal testing, which means that it can differ from the production environment from time to time. The database of the testing server might be unavailable at times, and the server may be emptied without notice. Also for data privacy do not use real/production data in the testing environment.



Invoices are sent by providing an XML file and specifying other necessary data as parameters on the api call. After the send you will get an ID that can be used to monitor invoice delivery.

You can use the same functionality to send invoices based on your preference either using SOAP or REST API.

To send an invoice make sure you have:

  • Sender company account: company account in Maventa where to send the invoice from. Sending doesn’t require separate activation, but if you want to use the print service or other additional services for sending, these need to be activated beforehand
  • Invoice xml: invoice XML file from your system in one of the supported e-invoice formats. You can also add supported attachments types or own invoice image to be sent with the invoice.
  • Receiver information: electronic invoicing address, email or postal address that can be used to reach the invoice receiver

See more information by opening the guides for

Invoice routing

How invoice gets delivered, how to give the delivery address and look up invoice recipients.

Invoice XML & content

What are the supported XML formats and attachment types, how invoice images and validation are handled

Invoice sending, monitoring and error handling

How to send an invoice. What are the possible invoice statuses, how to use callback notifications, resend and handle errors.

Finvoice specific logic

Finvoice format specific handling.



Invoices are received by listing new incoming invoices in Maventa and then downloading the invoice and attachments into your financial system.

List new incoming invoices

Invoice listing gives information of the new incoming invoices in Maventa.
First step of invoice receiving is to list the incoming invoice id’s and save them locally.

API methods

  • invoice_list_ids To get a list of invoice id’s between selected timestamps. Method is called per company, so it is only possible to list invoices from one company at a time.
  • list_vendor_inbound_invoices To list all inbound invoices of companies. Method lists all inbound invoices of all the companies which are linked to certain vendor_api_key.
  • Use GET /v1/invoices with params direction=RECEIVED, received_at_start, and received_at_end to get list of invoices available for download. It is possible to use the param fields to limit the amount of data returned on the response.

Download incoming invoices

Incoming invoices are downloaded with

  • Incoming invoices should not be polled more often than once per hour, usually a couple of times per day is enough
    • Call methods starting with latest fetch timestamp and ending with current timestamp
    • If the API returns error or something unexpected, do not update timestamp but allow retry of listing at a later time
    • When the API returns a list of invoices, save invoice IDs locally with a status ‘pending download’ or such
    • Use the local ID list to download an invoice, marking it as successfully retrieved only after it has actually been retrieved (e.g. in case of errors, alert/retry download)
    • Timestamp on the server is GMT +2 and differences between client side and server side clocks might create intervals not covered when listing. Therefore, it is recommended that the timestamps have some buffer, for example 1 minute before and after to avoid any gaps in the time
    • Since the IDs of the invoices are listed locally, that list can be used to make sure the same invoice is not downloaded twice
  • After listing the invoices, have a separate process to download the actual invoice XML and attachments, and update the status with ‘download completed’ only after completed download. This will help to ensure intermittent errors will not cause any invoices to not be downloaded.

Invoice receiving

Fraud reporting

To work on preventing invoice fraud, Maventa supports functionality to report us receiving of suspected fraudulent invoices. Integrators can add the reporting functionality into their system to give the users an easy way to do reports in the context of the invoice handling.

The purpose of this user generated/crowd sourced fraud warning service is to gather early indications of possible fraudulent senders. If different receivers report the same company enough times, the company can be added to a warning list. When invoice is coming from a sender on the list, company can get notification of this for example through Detect service. It is important to note that this reporting functionality cannot be used to dispute the invoice or refuse payment of it. Report is not automatically forwarded to the invoice sender or the authorities.

By adding the “report fraud -button” as part of your integration you will give your users an opportunity to be part of collecting the data and helping in the efforts for fraud prevention. See here how to do it.

Reporting in short

  • Reporting is linked to a received invoice
  • When doing the report, user is asked to select a reason category and give a contact email
  • User can additionally give more description of the fraud case (optional)
  • Texts and translations to use are availabe over the API

Send a report - example flow

Start the flow

User starts the reporting by clicking “Report fraud” button


  • Add a button/other way to start the report for a received invoice in your system

Report button

Reporting step 1/3

User is shown a text that explains the feature and helps them to understand the purpose of it


Fraud report information text

Reporting step 2/3

User is asked to select a reason for their report from preset categories. They can select one or many. Minimum one reason is required


Fraud report categories

Reporting step 3/3

User sees the summary of report and is asked to leave a contact email and optionally give more information about the case they are reporting.


  • Use POST/v1​/invoices​/{id}​/reports to submit the report. Currently only one report per invoice is allowed
  • Parameters
    • Maventa invoice id
    • reason category for reporting (one or many)
    • contact email (not displayed but could be used for further contacting)
    • optional: description of the fraud

Fraud report summary


You can decide whether or not the reporting is done step by step or all at once, how it best fits your system. In all cases take into account these couple of requirements

  • user should see the information text to understand the feature
  • minimum one reason category for reporting is required; this is to get more information of the case but also to reduce the possibility of reporting based on invalid reason
  • a contact email is required; this is not displayed elsewhere but could be used for further contacting

Other actions - See status & delete report

See report status

See the reporting information and status of the invoice, for example to show user if invoice has already been reported or get user report id required to delete report.

Delete existing report

Allow user to delete report they have made, if they no longer suspect fraud or need to do changes to their report.

Companies and settings

API to use: SOAP API

All companies using Maventa have an own account that is registered with unique business ID and company details. After registration company settings can be configured, including activation of different services and networks. Before account is ready to be used fully, it needs to be verified by partner or the end user company.

Company accounts will always be linked to at least one user. Users are created based on an email address. The user can be a real “human” user or a technical/API user only. This gives possibility to create the user set up in a very flexible way, taking into account the integration needs.

In company and user management note that

  • each company in the system is unique by businessID
  • each user in the system is unique by email address
  • companies have their own unique identifier; company_uuid
  • users have their own API key; user_api_key
  • each company needs to have at least one user, this can be a “real human user” or system “api user”
  • accessing the Maventa web user interface requires for authentication access to the user email. If you need the company user to access the web UI, make sure that the user email exists and is accessable for the user.

How to open company accounts

You can use either API or user interface to open and manage a company account. However, the user interface requires manual work so if the integration will have multiple companies or a complex set-up, API is recommended.

1. Account creation

To create a new company, register a company account using API method

  • register_with_password
    The method registers a new company account with default settings and adds/creates a user based on the email in the user_email parameter
    • if user with email doesn’t exist, a new user is generated based on email and added to the company
    • if user with email exists, this existing user is added to company

Note! In situations where a new user is created, method returns unique company_uuid and user_api_key. If method is called with an existing user, only company_uuid is returned.

2. Account configuration

When company account has been created, it can be configured by updating company settings, adding new users and activating services. Some services for receiving can only be activated after the verification step.

API methods:

You can update the receivig setting (enable/disable) also using company_invoice_receiving. Note,that invoice receiving needs to be enabled in order to register company account to Peppol network or to use additional services such as Scanning.

3. Account verification

To prevent possible misuse of the service, company account needs to be verified before it can be used for sending and receiving. The requirements to use the account are that customer company has been strongly authenticated and has signed Terms of Service

The account verification takes place with Visma Sign electronic signature service. A person who has rights to represent company related to electronic invoicing authenticates strongly with bank credentials or mobileID and signs a document where they confirm that account can be taken into use for the company.

If the customer has already signed the Terms of Service and has been strongly authenticated on the integrator side, it is possible to agree with Maventa about verification without the Visma Sign step.

API methods

  • authorize_companies
    Method to verify company accounts
    • Call to initiate account verification process, Maventa sends a request to authenticate through Visma Sign to an email address is given as parameter in the api call.
    • Account is verified and can be taken into use after customer has completed signing.
  • company_auth_status
    Method to see the company authorisation status
    • In order to start sending and receiving invoices the company status needs to be verified (1).


  • The signee should be person who has rights to represent company in matters conserning electronic invoicing/ordering
  • Before account is verified it is possible to configure account settings, but company cannot send or download invoices or register to Peppol as invoice or other document receiver
  • In production, company authorisation status is updated from Visma Sign every 15 minutes. In testing, there are no automatic updates but you need to call company_auth_status to get the status updated.
  • For Finnish companies, completing the signing creates also automatically the request to open bank network.

Process for company account activation over API Company account activation

Company accounts over UI

New companies with a new user can be created for:

If you need ro create a new company for an existing user, log-in to Maventa UI first.

Before account can be used it needs to be verified using strong authentication and electronic signing. When the user logs in to the account for the first time, user needs to go through a set-up wizard where they add information of the company and configure some of the basic settings. The last step of the wizard is the company verification process with Visma Sign service.

Different settings can be configured further in the web UI after user has logged in. Dedicated sections help to find the wanted settings and tell more information what the settings are about.

Partner accounts

In Maventa there are two type of accounts; Company accounts and Partner accounts. Company account is the default account type. Partner accounts are used by the integrating partners (ERPs and such with multiple customers).

The key difference between a Partner and a regular Company account is that Partner accounts have an own identifier, vendor_api_key, that is used to link actions to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can own many vendor_api_keys, for example one for each country they have customers in.

Integrators don’t need to worry about controlling the account types, all accounts registered to Maventa are first created as Company account and changed to account type Partner if and when needed by Maventa.

User management

User creation

Users are created to Maventa based on an email address. Creation happens at the time of the company account opening, or separately over API or user interface. A user can be connected to many companies and a company can have many users.

Created company user can be real person or an api-user that is a technical user only. Same api-user can be added to multiple accounts, but usually for integrators with larger amount of customers it is for security reasons recommended to have own api-user per account. For example email could be formatted as

Access to Maventa web user interface requires access to user email for authentication. If the new users will log in to UI make sure they have access to their email address.

User roles and rights

You can control the user rights by changing the user role. There are two roles, user and admin user. Compared to admin, users have more limited rights to service, they cannot for example modify company details or settings or add new users to the company.

User settings

You can configure user specific setting in Maventa, e.g. notifications which user would like to get.

API methods for user management

  • user_create_e to create or add a new or existing user to a company
  • user_list to list company users
  • user_show to show information about a specific user
  • user_update_e to update users details. Note that user’s email address cannot be updated through the API
  • user_delete to delete a user from a company account. You cannot delete your own user account

Services and networks

Take into use different services and networks enabled by Maventa. Select the services that you want to include in your integration and check here the service specific guides for implementation instructions.

Consumer invoicing

Send invoices to consumers into their net bank or mobile application. Use email or printing service as a fallback options for sending.

Peppol network

Send and receive electronic invoices and other trading documents in an international Peppol network.


Use print service to print the invoice and deliver it by post to recipients who cannot receive electronic invoices. Define the settings based on your customer needs.

Mass printing service (Payslip)

Use Maventa Direct Print API to send EPL and PDF files as letters through print service. The service is currently available in Finland only.

Receivables Management Service for Finnish companies

Activate Maventa Receivables Management Service to accelerate cash flow and free resources from manual work. The service handles reminders, payment monitoring, payment allocation, and debt collection after the invoice has been sent. Note! Only available for Finnish companies.


Use scanning service to receive PDF and print invoices in electronic format. Open scan accounts where suppliers can send print and PDF invoices. The invoices are scanned and then delivered to the companies as electronic invoices.


Receive data from different checks performed on the incoming invoices and companies. Use the data to improve purchase invoice handling and boost data-driven decision-making. For example give useful notifications to the users to improve fraud detection, supplier management and quality of bookings and payments.

Maventa Connector

Maventa Connector is a simple Maventa client program for Windows. If your ERP does not have a direct Maventa integration but can create invoices as XML files, you can use Maventa Connector to send those invoices. More information available in Finnish at and our support portal.

Email invoicing

Invoices can also be sent as an email invoices to the recipients. Email route is used as a secondary delivery route if invoice could not be sent as an e-invoice and if recipient e-mail address is available. Email invoice sending can also be forced or then disabled completely.

Embeddable User Interface

The Embeddable User Interface (EUI) is Maventa user interface that can be embedded into the ERP. With EUI customers don’t need to visit any external webpage to access their Maventa account but instead they can access their Maventa related settings, activate additional services and view their invoice listings directly from inside the ERP system. EUI is highly customizable which means that every ERP using it can create their own look of it by hiding parts of it their customers don’t need.

Document exchange

API to use: REST API

Maventa enables sending and receiving electronic order documents through PEPPOL network. The document types supported include orders, order responses, catalogues, catalogue responses and dispatch notes.


Partner and Maventa agree about the way the end customers (users of partner’s software) are invoiced for their transactions and use of Maventa services.

Basis for billing

Billing is transaction based. All transactions are billed based on the partner vendor_api_key that is provided on the API calls or in some cases stored in the company details. Based on the vendor_api_key setting the transactions can be billed from the key owner (partner) or from the end customer directly.

Billing is partner specific meaning that same transaction is only billed once from a partner and you can refetch invoices to same partner’s other systems without additional cost. If a customer receives invoices into different partners’ products, i.e. uses multiple ERPs from different partners to receive invoices at the same time, each partner will be billed separately for the invoice they have received into their system.

Transaction report

All Maventa invoices are attached with a transaction report that contains all the transacations that are billed in the invoice.

The transaction report contains the following information of the transactions

Header Value
BillingCompanyID unique identifier of the invoiced company in Maventa billing system
BillingCompanyName name of the invoiced company in Maventa billing system
BillingCompanyOrganizationIdentifier business ID of the invoiced company in Maventa billing system
TargetCompanyID unique identifier of the company who has performed the transaction
TargetCompanyName name of the company who has performed the transaction
TargetCompanyOrganizationIdentifier business ID of the company who has performed the transaction
MaventaProduct name of the transaction
DimensionItemSoftware name of the software used to perform the transaction
PrintPageCount number of printed pages within the transaction (for print transactions only)
ScanPageCount number of scanned pages (for scanned transactions only)
BatchItemCount number of transactions (for all other transactions types than print and scan)
ActionOriginTime time when transaction was performed
InvoiceNumber description of transaction
ProductUnitNetFullPrice unit price of transaction
LineNetSum total line amount

See example transaction report:

Note that the structure of this report is based on a real life example, but the data in the report is made-up.