REST API

Maventa REST API covers the following API’s

• AutoXChange API (sending and receiving invoices, sending and receiving other document types, webhooks, Detect Service)
• Validator API (validating invoices and other documents)
• Receivables API (Receivables Management Service)
• Payslip API (Mass Printing service)

You will find more information of the APIs below. Before you continue, make sure you have read our Integration guide and understand the Partner Agreement

How to start

Integration set up

How to get started and get the necessary keys to set up the integration is explained in our Integration guide

You will also also find there feature specific guides for sending, receiving, companies and settings, services and networks and billing that list what API method to use for different tasks.

Technical documentation in Swagger

Detailed technical documentation can be found at swagger.maventa.com. Select the environment and correct API in the top-right corner of the page and you will find a full list of methods with detailed descriptions of parameters and responses.

You can also try out the API directly in your browser with the Swagger user interface. Just click the “Authorize” button first and then “Try it out” button found under each method.

AutoXChange Postman example

Updated at 1.04.2025

This example has a collection with all the available endpoints and an example environment.

In order to use the collection successfully:

• View and fork the collection and example environment from button below
• Variables baseUrl and tokenUrl are given in collection’s (the parent) Variables tab.
• In the collection’s Authorization tab, the Type is set to BearerToken and as Token it uses the environment variable access_token which is created when you call the token endpoint.
• Before creating a token insert mandatory values to EXAMPLE_ENVIRONMENT’s variables (scope, client_id, client_secret, vendor_api_key).
• Call POST /oauth2/token endpoint to get access_token environment variable created to your environment variables. In Tests tab there is a step that sets the access_token from response to a environment variable.
  • For this endpoint remember set Type to No Auth in the Authorization tab
• With other endpoints, set Type to Inherits auth from the parent

Authentication

Authentication to REST API is based on the Oauth2 standard. Using of all API functions requires a valid Oauth2 bearer token, retrievable with the user_api_key and company_id . Expiry is set on server side and the mechanism to handle the expiry of the token is suggested to be handled gracefully on the client side.

The endpoint for aquiring the token is POST /oauth2/token. This endpoint provides authentication to all of the Maventa REST APIs.

• When starting a session, request for an authentication token via POST /oauth2/token
• Store the token locally, and set it to expire in given time before the server side value returned in response as seconds in expires_in field
  • Use the token until the stored validity time is reached, and then request a new token
  • When storing the token note that it is just a signed JSON so the length is not fixed. Be prepare that the number of characters in token may change
• Build in graceful authentication error handling
  • Prepare to handle possible token expiry errors even though using the client side expiry time, by requesting a new token
  • Handle token access and token unauthorized/expired scenarios differently (if token granted per client id&secret does not grant access to given resource, asking for a new token will not help)

Authenticate as a company

Authenticating requires a user_api_key and company_id. To create an account in testing, registrations can be done in Maventa Web UI, then logging in, and navigating to settings.

Also you need a vendor_api_key. When you have registered a company account in testing, contact your integration contact point or Maventa support to convert your account into a partner account and create a vendor_api_key for you.

Call the POST /oauth2/token method with company credentials:

• client_id = Company UUID (log in to your Maventa account to get it)
• client_secret = API key (log in to your Maventa account to get it)
• vendor_api_key

Notes:

• Currently only one level of user rights, admin, is supported. So all authenticated users will be granted with admin rights
• For Maventa company authentication, the scope does not need to be provided

Authenticate as an operator

Call the POST /oauth2/token method with operator credentials:

• client_id = operator_id
• client_secret = operator_secret

Error handling

The client should always handle any server/connection issues gracefully. Do not lock up or throw exceptions directly at your users. There can be both scheduled and unscheduled breaks in the service which should be handled on the client side, for example with messages like “Service unavailable, please try again later”.

AutoXChange API

AutoXChange API (also known as AX API) can be used to create companies, send and receive invoices, orders and other trading documents, register webhooks and activate different networks and services such as Peppol or Scan. It also includes Detect, a service that performs automatic checks and analysis on invoices.

Company creation and customer authentication

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 to ensure Know Your Customer process has been completed.

• Use POST /v1/companies to create a company
• Use POST /v1/companies/authorization to complete customer authentication process and to be able to start using the account
• Use GET /v1/companies/{id}/status to get company authorization status (customer authentication process completed or not)
• Use PATCH /v1/company/settings to modify company settings
• Use POST /v1/company/profiles to open services and networks, e.g Scanning service and Peppol network
• Use POST /v1/users to add new or existing user to a company

You can register webhooks to monitor when company authrization status changes, and when services and networks gets activated.

Service activation and profile registering

Register company as invoice or document receiver and activate services. The endpoint for profile registrations is POST /v1​/company​/profiles

• use POST /v1​/company​/profiles to register profile you want to have
• use GET /v1​/company​/profiles to fetch information of registrations
• use GET /v1/company/profiles/{id} to fetch more information of a specific registration
• use DELETE /v1​/company​/profiles to delete a registration

You can also use webhooks to get notifications when the registration status changes.

Networks to register

• VISMA - Internal invoice receiving. This network needs to be enabled to be able to receive invoices also via other networks like Peppol and scan.
• PEPPOL - Receiving in the Peppol network. Read more about Peppol registrations here.
• BANK - Sending and receiving in the Finnish bank network. Only for Finnish companies. Request to activate is sent automatically when company completes the customer authentication process. Activation takes typically from 1-3 days.
• SCAN - Receiving from scan service activated via AutoInvoice. Read more about scan service from here.
• SCAN_DOCUMENTS (or VISMASCANNER) - Receiving other documents than invoices via scan applications (Visma Scanner mobile application, DocScan web application)
  • VOUCHER
• RECEIVABLES - DEPRECATED - Use PUT /v1/services/receivables for receivables management service activation. Read more about the service from here.
• INEXCHANGE - Profile for operator InExchange - usage agreed separately.
• NEMHANDEL - Profile for Nemhandel registrations - usage agreed separately.
• AISPROOM - Profile for operator Sproom - internal use only.

Profiles not visible in this list are deprecated or in experimental stage. Please contact your integration contact point if you have further questions.

Examples

Below you can find examples of how to register networks and profiles

{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "VISMA"
}

{
  "id": "23c3226e-eaba-423e-8f4d-b1ce85429ab5",
  "status": "pending",
  "profile": "INVOICE_AND_CREDIT_NOTE",
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": null,
  "endpoint_id": "003712345678",
  "scheme": "V154",
  "network": "VISMA"
}

// Request 1
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "PEPPOL"
}

// Request 2
{
"profiles": [
  "ORDER"
],
"profile_version": "PEPPOLBIS30",
"network": "PEPPOL"
}

// #1
{
  "id": "ce2e8bda-355a-4e58-b2be-830c434b8ab9",
  "status": "pending",
  "profile": "INVOICE_AND_CREDIT_NOTE",
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003712345678",
  "scheme": "0216",
  "network": "PEPPOL"
}

// #2
{
  "id": "ce2e8bda-353a-4e58-b4be-832c434b8ab9",
  "status": "pending",
  "profile": "ORDER",
  "profiles": [
    "ORDER"
  ],
  "profile_version": "PEPPOLBIS30",
  "endpoint_id": "003712345678",
  "scheme": "0216",
  "network": "PEPPOL"
}

Invoice Exchange

Invoice sending

Invoices are sent by providing an XML file and specifying other necessary data for send as parameters on the api call.

• Use POST /v1/invoices to send an invoice, getting back a invoice ID in return
• The recommended way is to use webhooks to get notifications of invoices states. Fallback approach is to use REST API method GET /v1/invoices with param direction=SENT or GET /v1/invoices/{id}to poll status of sent documents to see those are either delivered successfully or failed in delivery.
• Use rerouting methods if you need to resend an invoice to another route or resend after route activation
  • PUT /v1​/invoices​/{id}​/reroute​/einvoice to send the invoice to an electronic address
  • PUT /v1​/invoices​/{id}​/reroute​/email to send the invoice to an email address
  • PUT /v1​/invoices​/{id}​/reroute​/print to send the invoice via print

NOTE! Sending or receiving of invoices is not allowed if company_state is unverified (-1) and API will return error message “Unauthorized”. Invoices can be sent after the authorization is done.

See more guidance and recommended routine for invoice sending in Integration guide

Check supported invoice formats from here and some example XML files from here.

Invoice receiving

To receive invoices, register the company first as invoice receiver, like this.

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

• The recommended way is to use webhooks to get notifications of received invoices. Fallback approach is to use REST API method 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.
• Use GET /v1/invoices/{id} to download the invoice XML file in the specified format, or to download the invoice image.

See more guidance and recommended routine for invoice receiving in Integration guide

Enable receiving from Peppol

To enable receiving of documents from Peppol. Use the POST /v1​/company​/profiles endpoint.

Example request:

{
  "network":"PEPPOL",
  "profiles":["INVOICE_AND_CREDIT_NOTE"]
}

Example response:

{
  "id": "ce2e8bda-355a-4e58-b2be-830c434b8ab9",
  "status": "pending",
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": null,
  "endpoint_id": "003712345678",
  "scheme": "0216",
  "network": "PEPPOL"
}

The identifier used when registering varies depending on the country and what kind of identifier has been used to when the company was created. The current defaults are listed in the table below.

The Peppol identifier (scheme and endpoint_id) to be used for receiving will be automatically resolved from identifiers associated with the company. In addition to the defaults it is possible to register alternative or additional identifiers such as GLN, please contact your integration support for more information.

Receiving invoices and credit notes

To enable receiving of invoices and credit notes from Peppol. The profile to use when registering is INVOICE_AND_CREDIT_NOTE.

Note: Receiving of invoices in the VISMA network should have been enabled before Peppol receiving can be enabled. See the Invoice receiving guide for details.

Receving invoice extensions

To enable receiving of invoice extensions you need to use the following endpoint. PUT /v1/company/profiles/{id}/extensions

Example request:

{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": ["GACCOUNT10"]
}

To view the extensions you need to use the following endpoint GET /v1/company/profiles/{id}

Example response:

{
  // ...
  "profiles_with_extensions": [
    {
      "profile_name": "INVOICE_AND_CREDIT_NOTE",
      "extensions": ["GACCOUNT10"]
    }
  ]
}

To disable receiving of invoice extensions you need to use the following endpoint. PUT /v1/company/profiles/{id}/extensions

Example request:

{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": []
}

Supported extensions for countries:

Receiving ordering and other document types

The receiving of ordering and other document types can also be enabled using this endpoint. In these cases it’s also required to specify the desired profile version (profile_version) in the request. Note: Make sure the system integrating is able to process the requested profile version. See Document receiving for details.

Example request:

{
  "network":"PEPPOL",
  "profiles":["INVOICE_RESPONSE"],
  "profile_version":"PEPPOLBIS30"
}

Supported profiles and versions:

EHF30 is a Norwegian national format and should be preferred for Norwegian customers.

Scan Account

• Use POST /v1/company/profiles to activate scan account for a company

  {
  "network_settings": {
    "return_email":"example@example.com",
    "return_address":{
      "post_code":"00000",
      "post_office":"cityX",
      "street_address":"Street 1"
      },
    "other_docs":false
    },
  "network":"SCAN",
  "profiles":["INVOICE_AND_CREDIT_NOTE"]
  }
  

• Use GET /v1​/company​/profiles (network: SCAN) to list and see status of existing scan account registrations
• Use PATCH /v1​/company​/profiles​/{id} to update information on existing scan account registration
• Use DELETE /v1​/company​/profiles​/{id} to close the scan account

Fraud reporting on received invoices

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.

• Use GET /v1​/invoices​/reports​/definitions
  • to get the reporting information text, available in EN, FI, SE, NO, DK, NL.
  • to get the reporting reason categories and descriptions, available in EN, FI, SE, NO, DK, NL.
• Use POST /v1​/invoices​/{id}​/reports to submit the report.
• Use GET /v1​/invoices​/{id}​/reports to get information about already reported invoice.
• Use DELETE /v1​/invoices​/{id}​/reports​/{report_id} to cancel the report on invoice.

See more guidance and example flow for fraud reporting in Integration guide

Document Exchange

Note that this endpoint is meant for other trading documents than invoices and credit notes, such as order documents, vouchers and reminders. For exchanging invoices and credit notes see Invoice Exchange. Please also note that format conversions and full look up features are not supported for this endpoint.

Document sending

Documents are sent by sending a document file, usually an XML, and specifying other necessary data as parameters on the api call.

• Use POST /v1/documents to send a document, getting back a document ID in return
• Use GET /v1/documents/{id} to poll status of sent documents to see those are either delivered successfully or failed in delivery. You can also use webhooks to get notifications of document states

Currently POST /v1/documents does not provide automatic lookup features, so in order to send a document both the recipient and the operator needs to be specified during the send. This can be done by specifying the recipient and recipient operator as parameters in the POST call. Recipient information is also parsed from supported XML file formats.

Document receiving

To receive documents, register first the company as document receiver, like this.

Documents are received by listing new incoming documents in Maventa and then downloading the document and attachments into the financial system.

List and download documents

• Use GET /v1/documents with params direction=RECEIVED, received_at_start, and received_at_end to get list of documents available for download. It is possible to use the param fields to limit the amount of data returned on the response.
• Use GET /v1/documents/{id} to download the document

Webhooks

Maventa supports registering webhooks. Using the AX API you can subscribe to certain type of events, and when that event happens we will send a HTTP POST request to the endpoint you defined.

Currently the event types are following:

• DOCUMENTS.*.DELIVERED
  • Happens when we complete send to the given route
• DOCUMENTS.*.DELIVERY_CONFIRMED
  • Happens when we get a positive response from the recipient operator
  • We do not have this for many routes, so not maybe yet a feasible one to listen to only currently
  • For example: Handled by Nets
• DOCUMENTS.*.FAILED
  • Happens when we get a final error.
  • This can happen after the DELIVERED event.
• DOCUMENTS.*.RECEIVED
  • Happens when your company receives a document
• NETWORKS.*
  • Events on different network registrations, such as BANK, SCAN, and PEPPOL. Event types can be CREATED, ENABLED, or DISABLED. So for example an event where Bank network request is sent, is NETWORKS.BANK.CREATED, and the following event after the bank network is opened is NETWORKS.BANK.ENABLED.
• COMPANIES.AUTHORIZATION.*
  • When a company’s authorization status changes to either VERIFIED, UNVERIFIED or UNKNOWN.
• UNACKNOWLEDGED_WEBHOOKS
  • Happens when your system experiences issues and fails to respond within 24 hours, the company will receive a single notification encompassing all unacknowledged webhook events. Unacknowledged webhooks are dispatched once per company per day and will continue for up to one month

We expect HTTP 200, 201 or 204 responses when the server has successfully handled the event. If for some reason the response is something else or the server is unavailable we will retry the request every hour for 24 hours.

The requests are expected to finish in under 5 seconds, requests that timeout are considered as failures and will be retried. No long running processing should ever be done in the webhook request.

Webhooks provide a convenient mechanism for real-time notifications, but they are not always 100% reliable. To ensure that you never miss an event, we offer the following fallback strategies:

• Option 1: Subscribe to unacknowledged webhooks

  We highly recommend subscribing to UNACKNOWLEDGED_WEBHOOKS. This ensures that you are alerted to any missed events. Once receiving a notification for unacknowledged webhooks, companies can easily retrieve all failed webhooks at once by calling the API method POST /v1/company/notifications_resend_unacknowledged. This API method will resend all unacknowledged webhook events for the company. Once an event is successfully processed, any future retry attempts for sending acknowledged webhooks will stop.

• Option 2: Use REST API as a fallback

  Alternatively, you can use our REST API to actively check for updates, to be sure nothing was left behind in case handling a webhook has failed.

  • Check sent document status

  Use the GET /v1/invoices method with param direction=SENT or GET /v1/invoices/{id}to poll the status of sent documents.

  • Check unfetched documents

  Use the GET /v1/invoices method to check for any unfetched invoices.

We will automatically disable a webhook subscription if all events for that subscription have been continuously failing for a month.

Example payloads

Below you can find examples of the payload we send to your webhook address when something happens. It is possible to add more details, so if you have any ideas what would be useful, just contact Maventa support.

{
  "event":"DOCUMENTS.INVOICE.RECEIVED",
  "company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"c154feee-399b-488e-aecd-580578b140e0",
    "invoice_number":"1002",
    "origin": "PEPPOL",
    "sender_name": "Sender",
    "sender_bid": "937729111"
  }
}

{
  "event":"DOCUMENTS.INVOICE.DELIVERED",
  "company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"12f88354-5998-495b-8675-67bf05de60e5",
    "invoice_number":"1003",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920"
  }
}

{
  "event":"DOCUMENTS.INVOICE.FAILED",
  "company_id":"53a4e05d-42f0-4e76-acd6-968ab4558c6f",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"da01a81d-1995-440c-971b-7e56c6c10e1d",
    "invoice_number":"1001",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920",
    "error_message": "Error that happened"
  }
}

{
  "event": "NETWORKS.PEPPOL.CREATED",
  "company_id": "d93a645e-ff69-42d3-88ad-5957ee173b28",
  "event_timestamp": "2020-02-04T10:24:47+02:00",
  "event_data": {
    "network": "PEPPOL",
    "profiles": [
      "INVOICE_AND_CREDIT_NOTE"
    ],
    "id": "f22c4a82-68a5-44fe-8e53-02ccc657f50d"
  }
}

{
  "event": "COMPANIES.AUTHORIZATION.VERIFIED",
  "company_id": "74700284-d794-4fdd-a2ae-d72c3589f7a2",
  "event_timestamp": "2021-10-29T11:33:24+03:00",
  "event_data": {
    "state": "VERIFIED"
  }
}

{
  "event":           "UNACKNOWLEDGED_WEBHOOKS",
  "company_id":      "74700284-d794-4fdd-a2ae-d72c3589f7a2",
  "event_timestamp": "2021-10-29T11:33:24+03:00"
}

Registering to receive events via webhooks

Subscribing to events happens through the POST /v1/company/notifications endpoint.

For a single company

Once you have authenticated as a company you can call this endpoint to register a webhook for that particular company.

For all partner’s companies

We have also a possibility to register webhooks for partners (aka vendor webhooks).

When a registration is done for a partner it covers all the companies that have been linked to the partner company’s vendor api key. The registration for a partner is a one time operation, after the registration is active the endpoint registered will receive events for all companies associated with the partner. This is the recommended way for partners to register their webhooks. Linking and unlinking the vendor api key is a requirement for this feature to fully function. More about partner accounts here.

If you want to register webhooks for a partner, authenticate with the partner company credentials and specify destination_type as VENDOR_WEBHOOK when subscribing to the events.

Request

For partner’s companies based on vendor key

There is a third posibility to register vendor webhooks based on vendor key.

This registration allows you to filter notifications based on vendor keys. This is helpful if you own multiple vendor api keys, and want notifications separately.

Registering based on vendor keys requires you to pass vendor_key in the payload.

Request

Examples

{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint?secret=my_secret",
  "events": [
    "DOCUMENTS.*.*"
  ]
}

{
  "id": "b77cdf0f-4b3b-4d56-b2c8-a7f94d83bd77",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint?secret=my_secret",
  "events": [
    "DOCUMENTS.*.*"
  ]
}

{
  "destination_type": "WEBHOOK",
  "destination": "https://postb.in/1580823541530-123456789",
  "events": [
    "NETWORKS.*"
  ]
}

{
  "id": "935026df-b548-4260-9c54-4a595a7a9c75",
  "destination_type": "WEBHOOK",
  "destination": "https://postb.in/1580823541530-123456789",
  "events": [
    "NETWORKS.*"
  ]
}

{
  "destination":      "https://your.example/endpoint",
  "destination_type": "WEBHOOK",
  "events":           [ "UNACKNOWLEDGED_WEBHOOKS" ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "UNACKNOWLEDGED_WEBHOOKS"
  ]
}

Security

It might be a good idea to include some sort of authorization in your URL to ensure that the messages sent to your endpoint are really from us.

Use can use:

• Basic access authentication Example: https://user:examplesecret@your-erp.com/webhooks
• Secret in the URL parameters Example: https://your-erp.com/webhooks?secret=examplesecret

Please note that the webhook endpoint needs to support TLS 1.2. Older versions such as SSLv2, SSLv3, TLS 1.0 and TLS 1.1 are not supported.

OP Laskulaina - Invoice credit service

Scope for the /oauth2/token: company

• use PUT /v1​/services​/op_invoice_credit start the OP Laskulaina onboarding.
• use GET /v1​/services​/op_invoice_credit to finalize the activation and get the current information about the service
• use GET /v1​/services​/op_invoice_credit​/available_credit to check the credit balance
• use POST /v1​/services​/op_invoice_credit​/withdrawal to make a withdrawal
• use POST ​/v1​/services​/op_invoice_credit​/direct_payment to inform OP about a direct payment to company’s own account
• use GET /v1​/services​/op_invoice_credit​/account_statement to fetch the account statement (SEPA XML)

See more guidance for OP Laskulaina - Invoice credit service in Integration guide

Detect service

Scope for the /oauth2/token: analysis

• use PATCH /v1​/services/detect/checks to activate and deactivate checks
• use GET /v1​/services/detect/checks to see check activation status
• use GET /v1/definitions/detect/checks to see all available checks, their description and possible result messages
• use GET /v1​/analysis​/{id} to fetch the check results with invoice id

See more guidance for Detect service in Integration guide

Definitions used by the API

You will find more information about the data type definitions used by this API from /v1/definitions namespace.

Some of these methods are publicly available, others will require an authenticated API user.

• use GET /v1/definitions/detect/checks to see all available checks, their description and possible result messages
• use GET /v1/definitions/operators to list all the currently supported roaming operators and their operator codes.
  • Authentication required

Validator API

The Validator API can be used for validation service, which provides XML schema and schematron validations for XML business documents.

• Use POST /v1​/validate to identify and validate the chosen xml

Receivables API

Receivables API is used for Receivables management service. The service helps to automate the debt collection process and is currently available for Finnish customers.

See more information of and integrating instructions for the service in the Integration guide

Detailed technical information in Swagger: Receivables API technical documentation

For using Receivables API the authentication scope receivables:assignments is required.

To activate the service

• Use PUT /v1/services/receivables to initiate the activation of Receivables Management service.

{
  "iban": "FI4900000000000000",
  "bic": "DABAFIHH",
  "bank": "Danske Bank",
  "contact_person": "John Doe",
  "contact_email": "john.doe@company.fi",
  "customer_service_email": "customer_service@company.fi",
  "customer_service_phone_number": "05050505",
  "contact_phone_number": "04040404",
  "authorization_email": "signatureperson@company.fi",
  "billing_address": {
    "country": "FI",
    "streets": [
      "Street 1"
    ],
    "city": "Helsinki",
    "zip_code": "00100"
  },
  "postal_address": {
    "country": "FI",
    "streets": [
      "Street 2"
    ],
    "city": "Helsinki",
    "zip_code": "00100"
  }
}

• Use GET /v1/services/receivables to fetch the status of the activation to see when the service is activated. Or register a webhook to get a event from Maventa when the service gets activated (or rejected).

{
  "iban": "FI4900000000000000",
  "bic": "DABAFIHH",
  "bank": "Bank 1",
  "contact_person": "John Doe",
  "contact_email": "john.doe@company.fi",
  "customer_service_email": "customer_service@company.fi",
  "customer_service_phone_number": "05050505"
  "contact_phone_number": "04040404",
  "authorization_email": "signatureperson@company.fi",
  "billing_address": {
      "country": "FI",
      "streets": [
        "Street 1",
        "Street 2"
        ],
      "city": "Helsinki",
      "zip_code": "00100"
  },
  "vfsfi": {
    "iban": "FI2357169020052929",
    "bic": "OKOYFIHH",
    "account_number": "571690-20052929",
    "notes": [
      {
        "phrase": "Olemme siirtäneet laskujen lähettämisen sekä saataviemme eräpäivän jälkeisen seurannan ja sitä koskevat toimenpiteet Visma Financial Solutions Oy:n laskutuspalveluun. Palvelua tai tilausta koskevissa asioissa pyydämme ottamaan yhteyttä suoraan: Yritys Oy, e-mail: customer_service@company.fi. Maksamiseen liittyvissä asioissa pyydämme ottamaan yhteyttä Visma Financial Solutions Oy:n verkkopalveluun tai asiakaspalvelun numeroon 024 808 8020.",
        "code": "FI"
      },
      {
        "phrase": "Yritys Oy har externaliserat övervakningen av fordringar till Visma Financial Solutions Oy:s faktureringstjänst. I ärenden som gäller faktureringen ber vi Erta kontakt med faktureringstjänsten per telefon (024 8088020) eller e-post(fsf.asiakaspalvelu@visma.com). Vi ber Er då uppge vår uppdragsgivare samtfakturans nummer. I ärenden som gäller innehållet av tjänsten ellerbeställningen ber vi Er kontakta Yritys Oy, Email: customer_service@company.fi.",
        "code": "SV"
      },
      {
        "phrase": "We have transferred the sending of invoices and follow-up of our claims after the due date and measures related thereto to the invoicing service of Visma Financial Solutions Oy. Regarding matters concerning the service or an order, please contact Yritys Oy, e-mail: customer_service@company.fi. Regarding matters concerning invoicing, please contact the invoicing service at tel. +358 24 808 8020 or e-mail fsf.asiakaspalvelu@visma.com. In that case we request you to state the name of our client and the invoice number.",
        "code": "EN"
      }
    ]
  },
  "status": "ACTIVE"
}

• Use PATCH /v1/services/receivables to change the setting for using own invoice image and own payments details with the service

Assignments and assignments’ events

More information about the assignments and event usage is explained in the Integration guide

• use GET /v1/assignments to list and get all the assignments and their events based on given filtering parameters (e.g. debtor name, assignment creation date, closing date..).
• use GET /v1/assignments/{assignment_id} to fetch one assignment and it’s events.
• use GET /v1/assignments/{assignment_id}/events to fetch only events related to the one assignment.
• use GET /v1/assignments/overview to fetch an overview of assignments (how many assignments are all together open, how many are soon to due and how many are already dued. See an example implementation)
• use POST /v1/assignments/{assignment_id}/events to add a new event to an assignment (e.g. mark direct payment, request due date change, cancel assignment..)
• use POST /v1/assignments/{assignment_id}/events/{event_id}/seen to mark event as seen
• use GET /v1/events to list assignment events

Service levels

• use GET /v1/service_levels to list the service levels for all of your customers. This method will only return customers that have a special service level set (premium, vip or service_bypass), the default service level is named “default” and that applies to every customer that does not have a service level. There is no way to list customers with the default service level.
• use GET /v1/service_levels/{customer_bid} to get service level for specific customer (with customer bid)
• use PATCH /v1/service_levels/{customer_bid} to set service level for customer (with customer bid)

Messaging functionality

Messaging functionality is used for the communication between Visma Amili and the customer. It is highly recommended to add this functionality as part of the integration to make sure both parties have a functional discussion connection and important messages do not get lost.

API endpoints for messaging functionality

GET /v1/message_threads - Lists all the message threads (shown latest message from each of the message thread)
PATCH /v1/message_threads/{thread_id} - Flag a message thread
GET /v1/message_threads/{thread_id} - Show message thread information (shows only the latest message)
GET /v1/message_threads/{thread_id}/messages - Show all the messages inside a message thread
POST /v1/message_threads/{thread_id}/messages - Add a message to a message thread
POST /v1/assignments/{assignment_id}/messages - Add a message for an assignment (this will create message thread if one does not exist yet, or add a new message to an existing message thread)
GET /v1/assignments/{assignment_id}/messages - Show all the messages for an assignment

PUT /v1/messages/{message_id}/seen - Mark a message as seen

Payslip API

Maventa Direct Print (also known as Payslip) is a service that enables sending of EPL and PDF files as letters through the printing service in Finland. Service was initially build to send payslip material, but it can be used for sending any kind of letters, as long as the printing service rules are followed.

See more information of the Mass printing service (Payslip) in the Integration guide

Stage: https://payslip-stage.maventa.com
Prod: https://payslip.maventa.com

Use POST /register to activate the service

Authentication as HTTP headers with on of the following authentication keys:

• USERNAME and USERPW with which you registered your Direct Print API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

Use POST /input_public to send zip package

Use POST /file_status to check the status of the sent package