Authentication

All requests to the Netvisor API must be authenticated. This page explains how the API communicates, how it protects your data and how to calculate the MAC code that each request needs.

How the API communicates

The Netvisor Web Service API follows the REST model. Your application and the server communicate with HTTP requests. The API works in both directions and is based on transactions.

Importing data to Netvisor: Your system creates an XML message that describes the data. It sends the message UTF-8 encoded in the body of the HTTP request. The resource you call defines the type of the transaction. Some transactions return an identifier for the new data, which you can use later.

Exporting data from Netvisor: You do not need to send an XML message. Send the request to the resource you need. If needed, limit the results with the parameters of that resource. The response returns the data in XML format.

Responses

All responses are in XML format. Each response contains a ResponseStatus element that tells you if the request was successful.

If the request succeeds, the Status element contains OK.
If the request fails, the Status element contains FAILED. The response also includes the error type and a description. For more information, see Controlling errors.

Example of a successful response:

<Root>

</ResponseStatus>

</Replies>

</Root>

Security

The API protects your data in two ways:

Encrypted connection: All traffic to the production and test environments uses an encrypted HTTPS connection.
One-way encryption of credentials: You do not send your credentials as such. Instead, you send a checksum that is calculated from them. The original credentials cannot be recovered from the checksum.

Proxy configuration

If you use a proxy with Netvisor's integration services, apply these settings:

Replace $host with integration.netvisor.fi.
The proxy_ssl_server_name on; directive is mandatory.

proxy_set_header Host integration.netvisor.fi;

proxy_ssl_server_name on;

HMACSHA256 authentication

Use HMACSHA256 in new integrations

The Netvisor API supports HMACSHA256 authentication from May 2025. New integrations must use HMACSHA256 authentication.

The API identifiers and a unique identifier for each request keep the Netvisor API secure.

To send data through the Netvisor API, you need two sets of API identifiers:

The user's API identifiers: the user identifier (CustomerId) and the user key (CustomerKey). The user creates these in Netvisor. See API identifiers.
The software partner's API identifiers: the partner identifier (PartnerId) and the partner key (PartnerKey). Netvisor customer service delivers these to the partner.

Every request must include the HTTP headers described below. For each request, you also calculate a MAC code with the HMACSHA256 algorithm. The API uses the MAC code to check that the request is valid.

Do not send the keys in the headers

The request headers do not include the user key (CustomerKey) or the partner key (PartnerKey). You need the keys only to calculate the MAC code.

Calculate a new MAC code for every request. If the API has already received a request with the same transaction identifier, it returns an error.

HTTP headers

Send these headers with every request. All header values must be strings. The example uses the same values as the MAC calculation example below.

X-Netvisor-Authentication-Sender: ClientName

X-Netvisor-Authentication-CustomerId: Integration user identifier

X-Netvisor-Authentication-PartnerId: Partner identifier

X-Netvisor-Authentication-Timestamp: 2026-10-20 18:00:00.000

X-Netvisor-Authentication-TimestampUnix: 1792519200

X-Netvisor-Authentication-TransactionId: 123456

X-Netvisor-Interface-Language: FI

X-Netvisor-Organisation-ID: 1967543-8

X-Netvisor-Authentication-MAC: 4e906334b43c7b9184f782cb0d561e316f059ecdc161305db80470f355e221d6

X-Netvisor-Authentication-MACHashCalculationAlgorithm: HMACSHA256

X-Netvisor-Authentication-UseHTTPResponseStatusCodes: 1

X-Netvisor-Authentication-Sender

A free-form name for the integration. If you have several systems connected to Netvisor, give each integration a unique name. The name helps Netvisor support and technical teams solve problems.

X-Netvisor-Authentication-CustomerId

The user identifier (CustomerId) from the customer company's API identifiers.

In the test environment, an employee of the software partner creates the API identifiers.
In production, a Netvisor user of the company that starts using the integration creates the identifiers. The user then gives the identifier and the integration user's key to the developer of the integration, or adds them to the integration settings.

To learn how to create API identifiers, see API identifiers.

X-Netvisor-Authentication-PartnerId

The partner identifier (PartnerId). Netvisor support creates a partner identifier and a partner key (PartnerKey) for each integration. We send them to the partner by email. If you have several systems connected to Netvisor, each integration gets its own partner identifiers.

X-Netvisor-Authentication-Timestamp

The time of the request in ANSI format with time, GMT+0. Example: 2026-10-20 18:00:00.000

X-Netvisor-Authentication-TimestampUnix

The time of the request in UNIX format, UTC. This is the number of seconds since January 1, 1970. Example: 1792519200

X-Netvisor-Interface-Language

The language of the API responses. The language mainly affects error messages. Allowed values are FI, SE and EN.

X-Netvisor-Organisation-ID

The Business ID of the target company. The Business ID defines which company the request saves data to or gets data from. The Netvisor user whose API identifiers the integration uses must have access rights to this company.

X-Netvisor-Authentication-TransactionId

A unique identifier for the request in GUID (Globally Unique Identifier) format. Use a new value in every request. If the API has already received data with the same identifier, it rejects the request and returns the REQUEST_NOT_UNIQUE error. The API checks the identifier at partner identifier level. This means that you cannot use the same identifier for different customers.

X-Netvisor-Authentication-UseHTTPResponseStatusCodes

Makes the API use the correct HTTP status codes in its responses. Set the value to 1.

Without this header, the API returns the status code 200 for every request. In that case, you can see the result of the request only in the ResponseStatus element.

When the value is 1, the API returns these status codes:

200: The request was successful.
400: The data is invalid or incorrectly formed.
401: Authentication failed. For example, the MAC code is wrong, the keys have expired or headers are missing.
403: The partner does not have access to this resource in the target company.
410: The target company's Netvisor service has been suspended or terminated.

Always be ready to handle the status code 500. The API can return it for serious server errors, whether or not you use this header.

X-Netvisor-Authentication-MACHashCalculationAlgorithm

Tells the API to accept the HMACSHA256 checksum. Set the value to HMACSHA256.

X-Netvisor-Authentication-MAC

The MAC code that verifies the sender of the request. The next section explains how to calculate it.

Calculate the MAC code

The MAC code is an HMACSHA256 checksum. You calculate it from the request URI, some of the HTTP headers, the user key (CustomerKey) and the partner key (PartnerKey).

First, join these values into one string in exactly this order. Put the & character between the values.

URI: The address that you send the request to. It must match exactly, including uppercase and lowercase letters. Example: https://isvapi.netvisor.fi/accounting.nv
X-Netvisor-Authentication-Sender: Example: ClientName
X-Netvisor-Authentication-CustomerId: Example: Integration user identifier
X-Netvisor-Authentication-Timestamp: Example: 2026-10-20 18:00:00.000
X-Netvisor-Interface-Language: Example: FI
X-Netvisor-Organisation-ID: Example: 1967543-8
X-Netvisor-Authentication-TransactionId: Example: 123456
X-Netvisor-Authentication-TimestampUnix: Example: 1792519200
The integration user's key (CustomerKey): Example: 7CD680E89E880553358BC07CD28B0EE2
The integration partner's key (PartnerKey): Example: 7F94228D149A96B2F25E3EDAD55096E1

In short, the order is: URL&Sender&CustomerId&Timestamp&Language&OrganisationId&TransactionId&TimestampUnix&CustomerKey&PartnerKey

Do not use the PartnerId, UseHTTPResponseStatusCodes or MACHashCalculationAlgorithm headers in the MAC calculation.

Next, form the key for the HMAC calculation (the secrets parameter). Join the user key and the partner key in the format CustomerKey&PartnerKey.

Finally, calculate the HMACSHA256 checksum from the string with this key. The result is the MAC code.

Encode special characters with ISO-8859-15

If the MAC string contains special characters or Nordic letters (å, ä, ö), encode it with the ISO-8859-15 character set before you calculate the checksum. This applies only to the MAC calculation. The message body is not used in the MAC calculation, and you send the body UTF-8 encoded.

Example

The string formed from the example values:

https://isvapi.netvisor.fi/accounting.nv&ClientName&Integration user identifier&2026-10-20 18:00:00.000&FI&1967543-8&123456&1792519200&7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E1

The key:

7CD680E89E880553358BC07CD28B0EE2&7F94228D149A96B2F25E3EDAD55096E1

The resulting MAC code:

4e906334b43c7b9184f782cb0d561e316f059ecdc161305db80470f355e221d6

If authentication fails, see the common error situations in Controlling errors.

Code examples

PHP example

This example calculates the MAC code and forms the HTTP headers. With the example values, it prints the MAC code shown above.

<?php

// MAC calculation

class MACCalculation

{

public $url;

public $sender;

public $customerId;

public $partnerId;

public $timestamp;

public $language;

public $organisationId;

public $transactionId;

public $timestampUnix;

public $customerKey;

public $partnerKey;

public function get_MAC()

{

$parameters = array(

$this->url,

$this->sender,

$this->customerId,

$this->timestamp,

$this->language,

$this->organisationId,

$this->transactionId,

$this->timestampUnix,

$this->customerKey,

$this->partnerKey

);

$key = array(

$this->customerKey,

Python example

This example calculates the MAC code and forms the HTTP headers. It creates a new timestamp and transaction identifier every time it runs, so the MAC code is different each time.

import hashlib

import hmac

import time

import uuid

# Identifiers

Sender = "ClientName"

PartnerId = "Partner identifier"

PartnerKey = "7F94228D149A96B2F25E3EDAD55096E1"

CustomerID = "Integration user identifier"

CustomerKey = "7CD680E89E880553358BC07CD28B0EE2"

MacHashAlgorithm = "HMACSHA256"

Organisationid = "1967543-8"

URL = "https://isvapi.netvisor.fi/accounting.nv"

Language = "FI"

# Values that must be new for every request

now = time.time()

timestampUnix = int(now)

timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime(now)) + ".%03d" % (int(now * 1000) % 1000)

TransactionID = str(uuid.uuid4())

# Compile the string for the MAC calculation

sha256string = URL + "&" + Sender + "&" + CustomerID + "&" + timestamp + "&" + Language + "&" + Organisationid + "&" + TransactionID + "&" + str(timestampUnix) + "&" + CustomerKey + "&" + PartnerKey

Last updated on

Was this page helpful?