Companies and Settings

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

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

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.

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.

• 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.

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

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

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.

• 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

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.

• 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

Mock mode for Finnish companies registered over the UI (stage)

When the new Finnish signatory check is in effect, registering a Finnish company through the Maventa UI on testing uses a stage-only mock of Visma Sign and the underlying authority check against the Finnish business register. You can click through the full signing flow with the test identity codes below — no real bank authentication runs, and no live calls are made to either service.

You can run through the entire flow on your own — enter your own email as the signee, open the link from your inbox, and walk through the signing yourself. Because everything is mocked, you can also try all three paths (approved, joint-authority, rejected) back to back without any real signer, real bank, or real Finnish company being involved.

The signing now happens in two phases. The admin enters only the signee’s email in the registration wizard; the signee receives an emailed link and completes the signing themselves (entering their identity code, choosing a Finnish bank, and confirming the signature). Every signee-flow page and the admin wizard’s signatory-check views on stage display a visible STAGE MOCK MODE banner so testers know they are not signing for real.

What the admin does

• Opens the registration wizard for a Finnish company.
• Enters the signee’s email address and sends the invitation.
• Waits for the signee to complete the signing; the company’s company_state moves to verified (1) automatically once the signing finishes.
• If the signee has only joint signing rights, the wizard reports a partial-authority result and prompts the admin to invite the next signatory before verification can complete. See the joint-authority note below.

What the signee does

• Opens the email link.
• Enters a test henkilötunnus (see the table below).
• Picks any Finnish bank from the list — the choice does not matter on testing.
• On the “Mock Visma Sign” page, clicks the button to complete signing. No real bank authentication runs, so the Nets test users referenced above are not used for this flow.

Test henkilötunnus values

Joint-authority path. Some Finnish companies are registered with nimenkirjoitusoikeus yhdessä (joint signing authority), meaning the company can be represented only when two named persons sign together. The mock joint-authority pair simulates this: signing once with 010191-0042 leaves the company in a partial-authority state, and the company is verified only after a second signing with 020292-0132. Use both identity codes, not just one.

Status updates flow through automatically in this UI flow, so the manual GET /v1/companies/{id}/status call described above is not needed. For API-driven Visma Sign testing and for non-Finnish companies, keep using the test credentials in the previous section.

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 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:

• 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.

The request body must follow this structure:

{
  "auth_email": "test.person@maventa.com",
  "company_ids": ["UUID"],
  "locale": "EN",
  "options": "{\"authorization_method\": \"how+identifier linking auth event\"}"
}

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