Companies and Settings

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

How to open and activate company accounts

1. Create company account
2. Configure settings for the account
3. Authorize the account (Customer authentication process) either with
   1. Visma Sign authentication process
   2. Partner’s own customer authentication process

1. Create company account

When registering a new company through the API, different countries have varying levels of support:

FI, SE, NO, DK, NL companies can be registered without any special arrangements. Because our customer authentication process supports these countries.

SOAP

Creating a company requires a vendor key.

• register_with_password The method registers a new company account with basic settings and adds/creates a user based on the email in the user_email parameter

Note how the user creation works!

• If user given in the user_email parameter doesn’t exist, a new user is created based on email and added to the company
• If user given in the user_email parameter exists, this existing user is added to company

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, for security reasons only company_uuid is returned.

REST

Creating a company requires a vendor key and a user API key.

You may use an existing user or create a new one with:

• POST /v1/users

To register a new company with basic settings:

• POST /v1/companies

Existing company

There can be only one company per business id. If the business id already exists in Maventa you will get an error message when trying to register it again (BID ALREADY TAKEN). Please contact Maventa support (support@maventa.com) regarding the management changes of the already existing account.

In REST API you can check beforehand company’s availability with

• POST /v1/partner/lookups/companies

When registering a new company account, it gets automatically linked to your vendor. If you take an already existing company account into use, remember to link the company account to your vendor. This is necessary for correct reporting and support handling and also mandatory if you wish to use webhooks. Similarly if a company stops using your vendor, it should be unlinked.

SOAP

• link_vendor_api_key Link vendor API key
• unlink_vendor_api_key Unlink vendor API key

REST

• POST/v1/company/vendors Link vendor API key
• DELETE/v1/company/vendors Unlink vendor API key

2. Configure account settings

When company account has been created, it can be configured by updating company settings and adding new users.

Keep Active

Keep Active is a feature for companies that rarely generate transactions. To maintain your company account as active even without generating transactions within a year, use the “Keep Active” feature.

As part of our data maintenance efforts, we will disable inactive company accounts, which means accounts with no transactions in the past 13 months. An email alert will be sent to the account after 12 months of inactivity, notifying that the account will be automatically disabled in one month. This provides time for companies to take appropriate action. If there is no activity after 13 months, the account will be disabled.

In REST API you can trigger Keep Active function with

• POST/v1/company/keep_active

SOAP

API methods:

• configure_company - Method to change company’s settings.
• show_company_configuration - Method to view current settings of a company.
• user_create_e - Method to create new users or adding existing one to a company account.
• scan_account_order - Method to activate Scan account for the company.

You can update the receiving 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.

REST

API methods:

• PATCH /v1/company/settings change company’s settings.
• GET /v1/company/settings view current settings of a company.
• POST /v1/users add new or existing user to a company.
• POST /v1/company/notifications - register webhooks

3. Customer authentication process

Customer authentication process is a necessary step to get the company’s account authorized. In other words to verify the company_state. The process ensures that a person with right to represent the company has confirmed and approved the registration for the Maventa service and has accepted the Terms of Service. The process is crucial for preventing potential misuse of the service.

The company’s account cannot be fully used until authentication is completed.

Please note that for Finnish companies, the process also automatically creates a bank network opening request.

Customer authentication options

The customer authentication process can happen with Visma Sign electronic signature service after opening the company’s account or it can happen already on the partner’s side.

If partner wants to use own authentication process, Maventa needs to approve the partner’s customer authentication process.

Visma Sign service is always used if company’s account is registered via Maventa UI.

Visma Sign authentication process

The authentication takes place within Visma Sign service. A person who has rights to represent company (signing rights or power of attorney) authenticates strongly with bank credentials, BankID or mobileID and signs a document where they confirm that company’s account can be authorized and taken into use.

Strong authentication via Visma Sign is currently available for the following countries: Finland, Sweden, Norway, Denmark and Netherlands.

Partners own customer authentication process

When company’s representative has been already strongly authenticated on the partner’s side the account can be taken in use without any additional signing.

The partner must provide an tracable information in authorization_method per each company to link the authentication process event on their side (e.g. contract number, signing eventID). If needed partner has to be able to show that the authentication has happened.

Please contact Maventa support to get your own authentication process approved.

APIs to use

After company’s account has been created an API call is used to trigger the authentication process, in other words, a Visma Sign document is sent for signing, see Visma sign authentication process

If partner is using own customer authentication process there is still a need to call the authorization method/endpoint, see Own customer authentication process example.

When the customer authentication is completed the company’s account gets authorized and company_state changes from unverified (-1) to verified (1) after this the account is ready to be used fully.

REST

• Authorize a single company POST /v1/company/authorization
• View company’s authorization status GET /v1/company/authorization
• Authorize multiple companies POST /v1/companies/authorizations
• View company’s authorization status GET /v1/companies/{id}/status

SOAP

• Authorize a company/companies authorize_companies
• View company authorization status company_auth_status

Authorization states

NOTE! Sending or receiving of invoices is not allowed if company_state is unverified (-1) and API will return error message “Unauthorized”.

Authorization webhooks

You can use webhooks to get notifications when company’s state changes. See the example “Example for companies authorization”.

You can also register webhook to monitor bank network opening for Finnish companies. The request to open bank network is sent after the authentication is completed. The opening is approved by third party (bank) and it usually takes couple of days.

Visma Sign authentication process in production

• The signee needs to be a person who has rights to represent company (signing rights or power of attorney).
• You can use parameter locale to select the language of the PDF document.
• The invitation to sign is valid for 7 days. If the signature is not made within this time, a new request must be sent.
• Company’s authorisation status is automatically updated from Visma Sign every 15 minutes.

Visma Sign authentication process in testing and Visma Sign service test credentials

In testing, the flow is similar as above but there are no automatic status updates. You need to call API to get the company’s state updated.

• SOAP company_auth_status
• REST GET /v1/companies/{id}/status

You can complete Visma Sign authorization request with these test credentials:

• user ID: testtest@test.test
• password: xO70MVYD0CXaKcQ2

For bankID you can use Nets test users from https://www.nets.eu/developer/e-ident/eids/Pages/testusers.aspx

Authenticate multiple company accounts with one go

In cases where single signee has rights to represent multiple companies it is possible to use one signing to authenticate all of the company accounts at the same time. For example in case of a housing company or accounting office that has power of attorney for multiple customers. One API call can be used to authorize up to 50 companies. For authentication to work, companies must be from the same country.

When this option is used the signing invitation contains a list of companies to be authenticated.

Example - Visma Sign authentication process

You have created company account, at this point authorisation status is (-1) = unverified. To initiate Visma Sign process to call authorize_companies / POST /v1/companies/authorizations API method.

After Visma Sign process has been completed, company account is set to verified state (1) and is ready to be used.

Example - Partner’s own customer authentication process

After company account creation account’s authorization status is -1 = unverified.
To authorize the account call one of these:

• authorize_companies method
• POST /v1/company/authorization endpoint
• POST /v1/companies/authorizations endpoint

In the API call you must provide an identifier in authorization_method per each company to link to authorisation event (e.g. contract number, signing eventID). After the API call, account is set automatically to verified state 1 and is ready to be used. No need to sign any documents in Visma Sign service.

Company account creation over UI

New companies with a new user can be created for:

• Testing at https://testing.maventa.com/registrations/
• Production at https://secure.maventa.com/registrations/

If you need to create a new company for an existing user, login to Maventa UI first.

Before account can be used it needs to be authorized using Visma Sign service. When the user logins to the account for the first time, user needs to go through a first time wizard where they add information of the company and configure basic settings. The last step of the wizard is the company authorization process with Visma Sign service. This process is the same as described within the Visma Sign authentication process above, but in this case the signing is initiated from the UI.

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 integration partners.

The key difference between a Partner and a Company account is that Partner accounts have extra identifier, vendor_api_key, which is used to link API calls to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can have multiple vendor API keys, for example one for each country they have customers in.

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

FAQ