Customer register guide

Customer register – use case guide

This guide explains how to keep Netvisor's customer register (asiakasrekisteri) in sync with your own system: how to find customers, create and update them, and manage their offices and contact persons. Customer data is the basis for sales invoices, so a correctly maintained customer card (asiakaskortti) also determines how invoices are addressed, which language they use and how they are sent. For element-level details, see the API reference.

The Finnish UI term is shown in italics after the English description, for example customer code (Asiakaskoodi).

Resources

Resource	Method	Purpose
customerlist.nv	GET	List and search customers
getcustomer.nv	GET	Get the full details of one or more customers
customer.nv	POST	Create or update a customer
office.nv	POST	Create or update a customer's office (toimipaikka)
contactperson.nv	POST	Add, update or delete a customer's contact person (yhteyshenkilö)
deletecustomer.nv	POST	Delete a customer

Use case: find a customer

Search the customer list

customerlist.nv returns each customer's Netvisor key, name, customer code, business ID (for business customers), customer group and a Uri for fetching the full details.

Parameter	Use
`keyword`	Returns customers where the keyword is found in the name, customer number, business ID or c/o name. If keyword is given, changedsince is ignored.
`customercodelist`	Comma-separated list of up to 100 customer codes. Can be combined with `keyword`; the result then contains customers that have a code on the list and match the keyword.
`changedsince`	Customers changed after the given time (`YYYY-MM-DDThh:mm:ss`). Use this to sync changes made in Netvisor to your own system.
`emailkeyword`	Customers whose email address matches.

Get full customer details

Use the Netvisor key from the list with getcustomer.nv: id for one customer or idlist for up to 500 customers at once. Give exactly one of them.

The response always contains the customer's base information, e-invoice details, delivery details, contact details, contact persons, offices and additional information. Extra sections can be added with the replyoption bitmask; combine values by adding them up:

`replyoption`	Adds
1	Receivables turnover: average payment time and payment day in relation to the due date (myyntisaamisten kiertoajat)
2	Automatic reminders rule (Automaattiset muistutukset)
4	Custom fields (lisätietokentät)
8	Customer's default invoicing method (`BuyerServiceCode`, for example consumer e-invoice or direct payment)
16	Additional contact person details: contact prohibition, title, position, address, country and language

The Netvisor keys of the customer's offices and contact persons are also returned here. You need them for office.nv and contactperson.nv, and when linking a contact person or office to a sales invoice.

Use case: create or update a customer

customer.nv creates a customer (method=add) or updates one (method=edit, with the customer's Netvisor key in id). The response returns the customer's Netvisor key in InsertedDataIdentifier. Store it for later calls.

If method is missing or the customer to be updated is not found, the API returns INVALID_DATA with an explanation.

Updating a customer: send only the elements you want to update. Any element included in the message is updated, so an element you send with an empty value is cleared in Netvisor.

A minimal new business customer looks like this:

<root>

<name>Example Customer Oy</name>

<streetaddress>Pajukuja 1</streetaddress>

<city>Lappeenranta</city>

</customerbaseinformation>

</customer>

</root>

Base information (`customerbaseinformation`)

Element	Netvisor UI name	Notes
`internalidentifier`	Asiakaskoodi	Customer code, max 50 characters. With `type="automatic"` and an empty value, Netvisor uses the next free customer number.
`externalidentifier`	Y-tunnus / henkilötunnus	Business ID, or personal identity code for a private customer.
`organizationunitnumber`	OVT-tunnus	Recipient's EDI identifier, only if it differs from the business ID. See below.
`name`	Asiakkaan nimi	Customer name, max 250 characters.
`nameextension`	Nimen jatke	Name extension, max 250 characters.
`streetaddress`, `additionaladdressline`, `postnumber`, `city`	Katuosoite, Osoitteen jatko, Postinumero, Postitoimipaikka	Billing address.
`country`	–	Country as an ISO-3166 code. Defaults to Finland.
`customergroupname`	Asiakasryhmä	Customer group by name. Created if it does not exist.
`phonenumber`, `faxnumber`, `email`, `homepageuri`	Puhelinnumero, Fax-numero, Sähköpostiosoite, www-osoite	Contact details.
`isactive`	–	1 = active customer.
`isprivatecustomer`	Henkilöasiakas	1 = private customer.
`emailinvoicingaddress`	Sähköpostilaskutusosoite	Must be a valid email address. Several addresses can be given separated with `;`.

About organizationunitnumber. Use this element only for a fixed customer-specific value that the recipient requires on their e-invoices, for example a factory number. It is sent in Finvoice as BuyerOrganisationUnitNumber. Do not put the customer's e-invoice address here. The value is validated: it must be 12–17 digits, typically in the format 0037AAAAAAAABBBBB, where 0037 is the ISO 6523 code of the Finnish Tax Administration, AAAAAAAA is the business ID with its check digit but without the hyphen, and BBBBB is an optional organisation unit identifier of up to five digits.

E-invoicing (`customerfinvoicedetails`)

Element	Netvisor UI name	Notes
`finvoiceaddress`	Verkkolaskuosoite	E-invoice address. Cannot be given without the operator.
`finvoiceroutercode`	Verkkolaskuoperaattori	Operator code. Must be one of the operators supported by Netvisor (verkkolaskuoperaattorit). Cannot be given without the address.

The e-invoice address itself is not validated, but the operator must exist in Netvisor. Keep these details correct: sales invoices are sent to the e-invoice and email addresses on the customer card, and they cannot be given in the invoice message.

Delivery, contact and additional information

Element	Netvisor UI name	Notes
`customerdeliverydetails`	Toimipaikka	Delivery name and address. Creates an office on the customer card.
`customercontactdetails/contactperson`	Yhteyshenkilö	Contact person's name. Saved in the UI's last name field (Sukunimi). For full contact person management, use `contactperson.nv`. Do not use `contactname`; it is not shown in the UI.
`invoicinglanguage`	Laskun kieli	FI, EN or SE. Defaults to Finnish. This determines the language of the customer's sales invoices.
`invoiceprintchannelformat`	Tulostusmuoto	1 = invoice + bank transfer form (Lasku + tilisiirto), 2 = invoice only (Lasku).
`defaultpaymentterm`	Oletusmaksuehto	Default payment term, `type="netvisor"` (Netvisor key) or `type="customer"` (name).
`defaultsecondname`	Oletusaputoiminimi	Default auxiliary business name, by Netvisor key or name.
`defaultsalesperson/salespersonid`	Oletusmyyjä	Default seller's Netvisor key, available from salespersonnellist.nv.
`customerreferencenumber`	Viitenumero	Valid reference number with check digit.
`usecreditorreferencenumber`	–	1 = use an RF reference (RF-viite) in invoicing.
`useorderreferencenumber`		1 = use the order's reference number in invoicing.
`yourdefaultreference`	Oletusviitteenne	Default "your reference".
`defaulttextbeforeinvoicelines` / `defaulttextafterinvoicelines`	Oletusteksti ennen laskurivejä / jälkeen laskurivien	Default invoice texts.
`customeragreementidentifier`	Sopimustunnus	Agreement identifier.
`paymentinterest`	Viivästyskorkoprosentti	Penalty interest percentage. Use a comma as the decimal separator.
`balancelimit`	Tiliraja	Credit limit.
`receivablesmanagementautomationrule`	Muistutusten automaatiosääntö	Automatic reminder rule, by Netvisor key or name.
`FactoringAccount`	Factoring-tili	Factoring account, by Netvisor key or name.
`taxhandlingtype`	Verotuskäsittely	`countrygroup`, `forcedomestic`, `notaxhandling` or `domesticconstructionservice`.
`eustandardfinvoice`		1 = use an EU-standard e-invoice.
`denyinvoicecollection`	Perintäkielto	1 = customer-specific collection prohibition.
`denydelivery`	Toimituskielto	1 = customer-specific delivery prohibition.
`comment`	Kommentti	Comment in the customer register, max 2,500 characters.
`customerdimensiondetails`	Oletuslaskentakohteet	Default dimensions. Dimension names and items are created if they do not exist. When `dimensionitemcode` or `dimensionitemname` is given, `dimensionitem` is ignored.

Use case: manage offices

A customer can have several offices (toimipaikat), for example separate delivery or invoicing addresses. Offices are used when linking a sales invoice to a specific office.

office.nv adds an office to a customer (method=add, with the customer's Netvisor key in customerid) or updates an existing office (method=edit, with the office's Netvisor key in officeid). Office keys are returned by getcustomer.nv.

Element	Netvisor UI name	Notes
`name`	Toimipaikan nimi	Required, and can never be empty.
`phonenumber`, `telefaxnumber`	–	Phone and fax.
`officeidentifier`	Toimipaikkatunnus	Office identifier.
`emailinvoicingaddress`	Toimipaikan laskutussähköposti
`officecontactaddress`	–	Postal address: street address, postcode, city and country (ISO-3166).
`officevisitaddress`	Käyntiosoite	Visiting address: street address, postcode, city and country (ISO-3166).
`officefinvoicedetails`	Verkkolaskutiedot	E-invoice address and operator. The address must be a valid EDI identifier (OVT) or IBAN, and the operator must be one of the operators supported by Netvisor.

When editing an office, you can clear a value by sending the element empty. The office name cannot be cleared.

Use case: manage contact persons

contactperson.nv adds, updates or deletes contact persons on a customer card. The operation is add, edit or delete. The API reference documents method as a query parameter, and the message also contains a method element; give the same value in both.

Element	Netvisor UI name	Notes
`customeridentifier`	Asiakas	The customer's Netvisor key, `type="netvisor"`. Required.
`contactpersonidentifier`		The contact person's Netvisor key, `type="netvisor"`. Required for `edit` and `delete`.
`isdefault`	–	`true` makes the contact person the customer's default. The default cannot be removed this way.
`firstname` / `lastname`	Etunimi / Sukunimi	Required, max 100 characters each.
`language`	–	FI, EN or SE, `type="ISO-3166"`. Required.
`phonenumber`, `email`	Puhelinnumero, Sähköpostiosoite
`title`	–	Title.
`officeidentifier`	Toimipaikka	The Netvisor key of the contact person's office. The value 0 clears it.
`positionidentifier`	–	The Netvisor key of the contact person's position. The value 0 clears it.
`contactpersonaddress`	Osoite	Street address, postcode, city and country (ISO-3166).

Only add returns the new contact person's Netvisor key in InsertedDataIdentifier. Contact person keys of existing contact persons are returned by getcustomer.nv. A contact person can be linked to a sales invoice with the contactpersonid attribute of invoicingcustomeridentifier in salesinvoice.nv.

Use case: delete a customer

deletecustomer.nv deletes one customer identified by its Netvisor key in customerid. Find the key with customerlist.nv.

A customer can only be deleted if it has no invoicing history. If the deletion fails, the response explains why, for example that the customer has invoices.
Deleting a customer also removes its contact persons, dimension links and customer-specific price lists. The deletion either succeeds completely or has no effect.

Glossary: English – Finnish

English	Finnish (Netvisor UI)
Customer register	Asiakasrekisteri
Customer / customer card	Asiakas / asiakaskortti
Customer code	Asiakaskoodi
Customer group	Asiakasryhmä
Business ID	Y-tunnus
Personal identity code	Henkilötunnus
Private customer	Henkilöasiakas
EDI identifier	OVT-tunnus
E-invoice address / operator	Verkkolaskuosoite / verkkolaskuoperaattori
Email invoicing address	Sähköpostilaskutusosoite
Office	Toimipaikka
Contact person	Yhteyshenkilö
Invoice language	Laskun kieli
Default payment term	Oletusmaksuehto
Credit limit	Tiliraja
Collection prohibition	Perintäkielto
Delivery prohibition	Toimituskielto
Custom field	Lisätietokenttä
Default dimensions	Oletuslaskentakohteet

Last updated on

Was this page helpful?