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), using one of:
   1. Finnish signatory check (Finnish companies registered through the Maventa UI)
   2. Visma Sign authentication process (UI registrations in Sweden, Norway, Denmark, the Netherlands, and API-driven authorisation in any country)
   3. 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

Customer authentication happens in one of three ways, depending on the company’s country and how the account is opened:

1. Finnish signatory check — used for Finnish companies registered through the Maventa UI. The signatory’s signing authority is verified against the Finnish business register, and the signatory signs the Maventa Terms of Service via Visma Sign. The flow is split into two phases: the admin invites the signatory by email, and the signatory completes the signing on their own device.
2. Visma Sign authentication process — used for UI registrations in Sweden, Norway, Denmark, and the Netherlands, and for API-driven authorisation in any country (including Finland). A signee with the right to represent the company (signing rights or power of attorney) receives an emailed invitation, authenticates strongly via Visma Sign, and signs a document confirming that the company’s account can be authorised.
3. Partner’s own customer authentication process — used by partners who have an approved authentication process of their own. The account is authorised via the API with an identifier in authorization_method.

If a partner wants to use their own authentication process, Maventa needs to approve it first.

Finnish signatory check

Finnish companies need a signatory with legal signing authority (nimenkirjoitusoikeus) to authorise the company’s account for sending and receiving electronic documents. In practice, the person registering the company in the Maventa UI — usually an accountant, finance-ops contact, or admin — is rarely that authorised signatory. The Finnish signatory check splits registration and signing into two phases so the right person can sign without needing a Maventa account or inheriting the registrant’s session.

How the flow works in the Maventa UI:

1. The admin opens the registration wizard for a Finnish company and enters the signatory’s email address. The wizard sends the signatory a personal invitation link, and the admin is free to close the tab.
2. The signatory opens the link on their own device, agrees to the privacy statement, enters their Finnish personal identity code (henkilötunnus), and picks their bank.
3. Maventa checks the signatory’s signing authority against the Finnish business register before any signature is collected.
4. If authority is confirmed, the signatory is redirected to Visma Sign for bank authentication and signs the Maventa Terms of Service.
5. After signing, the company’s company_state moves to verified (1) automatically. No API status-poll is needed for this flow.

The authority check returns one of three outcomes:

The invitation link is valid for 7 days. Once the signatory opens the link and starts signing, the window narrows to 15 minutes so they complete the signing in one sitting; if the window expires, the admin can resend the invitation.

Visma Sign authentication process (other countries and API-driven)

The authentication takes place within Visma Sign. The signer must be a person who has the right to represent the company (signing rights or power of attorney) — this is a requirement of the authorisation, not just an organisational convention. The signer authenticates strongly with bank credentials, BankID, or mobileID and signs a document where they confirm that the company’s account can be authorised and taken into use.

In UI registrations, the Maventa wizard collects the signer’s email address and Visma Sign emails them the invitation; the signing happens in Visma Sign, not in the Maventa UI. The person registering the company in the Maventa UI does not need to be the same person as the signer — if they are not, they enter the email address of someone who is. The same applies to API-driven authorisation: the API caller supplies the signer’s email and Visma Sign handles the rest.

This path applies to UI registrations in Sweden, Norway, Denmark, and the Netherlands, and to API-driven authorisation in any country (including Finland). For Finnish companies registered through the Maventa UI, the Finnish signatory check is used instead.

Partner’s 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 the 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 a partner is using their own customer authentication process, there is still a need to call the authorization endpoint — see Partner’s own customer authentication process.

For Finnish companies registered through the Maventa UI, the registration wizard handles the Finnish signatory check end to end and the API call is not made by the partner.

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 following applies to the Visma Sign authentication path (non-FI UI registrations and API-driven authorisation). For the Finnish signatory check, see the step-by-step flow above.

• The signee needs to be a person who has the right to represent the company (signing rights or power of attorney).
• You can use the locale parameter 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

The credentials below are for the Visma Sign authentication path on testing (non-FI UI registrations and API-driven authorisation). For testing the Finnish signatory check on stage, see the stage environment notes below.

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

• GET /v1/companies/{id}/status

You can complete a Visma Sign authorisation 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.

Stage environment for the Finnish signatory check

On production, the Finnish signatory check runs against the real Finnish business register and the real Visma Sign service. On the Maventa stage environment (testing.maventa.com), both are mocked by default so partners and integrators can exercise the entire flow end-to-end without real personal identity codes, real bank authentication, or real signatures. Production never runs in mock mode regardless of any setting — the test identity codes here cannot be used against secure.maventa.com.

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

Every signatory-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 signatory’s email address and sends the invitation.
• Waits for the signatory to complete the signing; the company’s company_state moves to verified (1) automatically once the signing finishes.
• If the signatory 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 signatory 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 stage.
• 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 a single signee has the right to represent multiple companies, one signing can be used to authenticate all of the company accounts at the same time — for example 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, the companies must be from the same country.

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

This option uses the Visma Sign authentication path and applies to API-driven authorisation. The Finnish signatory check (UI) authorises one Finnish company per session.

Example - Finnish signatory check (UI)

You have started registering a Finnish company in the Maventa UI; at this point the authorisation status is (-1) = unverified. The registration wizard runs the Finnish signatory check — the admin invites the signatory by email, and the signatory completes the signing on their own device.

After the signatory completes the signing, the company’s company_state updates to verified (1) automatically.

Example - Visma Sign authentication process (other countries and API-driven)

You have created the company account; at this point the authorisation status is (-1) = unverified. This example covers the Visma Sign authentication path — used for UI registrations in Sweden, Norway, Denmark, and the Netherlands, and for API-driven authorisation in any country. For Finnish companies registered through the Maventa UI, see the Finnish signatory check example above.

To initiate the Visma Sign process, call POST /v1/companies/authorizations.

After the Visma Sign process has been completed, the 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 the account can be used it needs to be authorised. When the user logs into the account for the first time, they go through a first-time wizard where they add information about the company and configure basic settings. The last step of the wizard is the company’s customer authentication — the signing must be done by a person who has the right to represent the company (signing rights or power of attorney), regardless of country. The person opening the wizard is not always that same person, and the flow accommodates both cases:

• Finnish companies use the Finnish signatory check: the person in the wizard enters the signatory’s email, and the signatory — who is the person with signing rights — completes the signing on their own device.
• Companies in Sweden, Norway, Denmark, and the Netherlands use the Visma Sign authentication process: the person in the wizard provides the signer’s email address, and Visma Sign emails the invitation to the signer who then authenticates and signs. The signer can be the same person who is using the wizard if they have signing rights, or a different person if they do not.

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