Integration | HTTP-method | Resource | DTD | Schema | Example |
Get customer list | GET | customerlist.nv | Download | ||
Get customer details | GET | getcustomer.nv | Download | ||
Import customer details | POST | customer.nv | Download | Download | |
Delete customer details | GET | deletecustomer.nv | |||
Import customer office | POST | office.nv | Download | Download | |
Import customer contact person | POST | contactperson.nv | |||
Get sales personnel list | GET | salespersonnellist.nv | Download |
Get customer list
Resource: customerlist.nv
This section describes how to retrieve a list of customers from Netvisor. The customer list contains basic information (NetvisorID, name, customer's code, company ID and URI for retrieving detailed customer information). Detailed customer information can then be retrieved with Get Customer Details.
Querystring parameters:
Parameter name | Occurs | Description | Example |
keyword | 0...1 | Filters result list with given keyword. Match is searched from following fields: Name, Customer Code, Organization identifier, CoName | |
changedsince | 0...1 | Filters result to contain only customers having change after given date, date in format YYYY-MM-DDTHH:mm:ss | 2012-01-01 |
customercodelist | 0...1 | Filters result with given customercodes. Customercodes should be separated with comma. The list can include maximum of 100 alfanumeric customer codes. Note! Parameter keyword can be used with customercodelist. Filters result with given customercodes AND with given keyword. |
Keyword parameter is used over changedsince
Response:
Level | Element name | Type and length | Occurs | Description | Example |
1 | Customerlist | Aggr. | 1 | ||
2 | Customer | Aggr. | 0...n | ||
3 | Netvisorkey | Integer | 1 | Customer identifier in Netvisor | 123 |
3 | Name | String | 1 | Name of the customer | Customer X |
3 | Code | String | 1 | Customer code | 234 |
3 | OrganisationIdentifier | String | 1 | Customers organization identifier if not consumer customer | 12345678-9 |
3 | CustomerGroupID | Integer | 1 | Customer Group ID, where the customer belongs. Can be empty. | 2 |
3 | CustomerGroupName | String | 1 | Customer Group Name, where the customer belongs. Can be empty | Customer group 1 |
3 | Uri | String | 1 | URI that can be used to get details of current customer | /getcustomer.nv?id=123 |
Get customer details
Resource: getcustomer.nv
In order to retrieve the wanted customer details, the customer ID is needed. This can be picked from the customerlist.
Querystring parameters:
Parameter name | Occurs | Description | Example |
id | 1 | ID of the customer | 123 |
idlist | 0...1 | Can be used to get the details of several customers with given id. Max. 500 identifiers | 1,2,3 |
replyoption | 0...1 | Returns customer's invoicing history details. | 1 |
Response:
Level | Element name | Type and length | Occurs | Description | Example |
1 | Customer | Aggr. | 1 | ||
2 | CustomerBaseInformation | Aggr. | 1 | ||
3 | NetvisorKey | Integer | 1 | Customer Netvisor key | 1001 |
3 | InternalIdentifier | String | 1 | Customer code | MM |
3 | ExternalIdentifier | String | 1 | Organization identifier | 1234567-8 |
3 | OrganizationUnitNumber | Integer | 0...1 | Organization unit number | 0037123456715 |
3 | CustomerGroupNetvisorKey | String | 0...1 | Netvisor identifier of customer group | |
3 | CustomerGroupName | String | 0...1 | Name of the customer group | |
3 | Name | String | 1 | Name of the customer | Matti Meikäläinen |
3 | NameExtension | String | 1 | Extension for the name of the customer | Toimitusjohtaja |
3 | StreetAddress | String | 1 | Customer's street address | Pajukuja 1 |
3 | AdditionalStreetAddress | String | 1 | Address extension | |
3 | City | String | 1 | Customer's post office | Lappeenranta |
3 | PostNumber | String | 1 | Customer's post number | 53100 |
3 | Country | String | 0...1 | Country code | FI |
Attr. | Type | String | 0...1 | Always ISO-3166 | ISO-3166 |
3 | PhoneNumber | String | 1 | Customer's phone number | 040 123 4567 |
3 | FaxNumber | String | 1 | Customer's fax number | 05 123 4567 |
3 | String | 1 | Customer's E-mail address | matti.meikalainen@firma.fi | |
3 | EmailInvoicingAddress | String | 1 | E-mail invoice address | matti.meikalainen@firma.fi |
3 | HomePageUri | String | 1 | Customer's web site | www.firma.fi |
3 | IsActive | Numeric | 1 | 0 or 1, is customer active | 1 |
3 | IsPrivateCustomer | Numeric | 1 | 0 or 1. Value 1 indicates customer is a private customer | 1 |
2 | CustomerFinvoiceDetails | Aggr. | 1 | ||
3 | FinvoiceAddress | String | 1 | E-invoice address | FI10970021497 |
3 | FinvoiceRouterCode | String | 1 | E-invoice operator | NDEAFIHH |
2 | CustomerDeliveryDetails | Aggr. | 1 | Customer's default office | |
3 | DeliveryName | String | 1 | Name for the delivery | Matti Meikäläinen |
3 | DeliveryStreetAddress | String | 1 | Delivery address | Pajukuja 1 |
3 | DeliveryCity | String | 1 | Delivery Post office | Lappeenranta |
3 | DeliveryPostNumber | String | 1 | Delivery post number | 53100 |
3 | DeliveryCountry | String | 0...1 | Delivery country | FI |
Attr. | type | String | 0...1 | Always ISO-3166 | ISO-3166 |
2 | CustomerContactDetails | Aggr. | 1 | ||
3 | ContactPerson | String | 1 | Default contact person's name | |
3 | ContactPersonEmail | String | 1 | Default contact person's E-mail address | |
3 | ContactPersonPhone | String | 1 | Default contact person's Phone number | |
2 | CustomerContactPersons | Aggr. | 0...1 | ||
3 | CustomerContactPerson | Aggr. | 1 | ||
4 | ContactPersonID | Integer | 1 | Contact person's NetvisorID | 1006 |
4 | ContactPersonFirstName | String | 1 | Contact person's first name | Eric |
4 | ContactPersonLastName | String | 1 | Contact person's last name | Example |
4 | ContactPersonPhoneNumber | Numeric | 1 | Contact person's phone number | 0501234567 |
4 | ContactPersonEmail | String | 1 | Contact person's E-mail address | eric.example@company.com |
4 | ContactPersonOfficeNetvisorKey | Numeric | 1 | Contact person's office NetvisorID | 2 |
2 | CustomerOfficeDetails | Aggr. | 0...n | Customer offices details | |
3 | OfficeNetvisorKey | Numeric | 1 | Office NetvisorID | 10 |
3 | OfficeName | String | 1 | Office name | Helsingin toimisto |
3 | OfficePhoneNumber | String | 1 | Office phone | 040 312 654 |
3 | OfficeTelefaxNumber | String | 1 | Office fax | 05 321 654 |
3 | OfficeIdentifier | String | 1 | Office identifier | Officeidentifier |
3 | OfficeContactAddress | Aggr. | 1 | Office postal address | |
4 | StreetAddress | String | 0...1 | Street address | Keskuskatu 1 |
4 | PostNumber | String | 0...1 | Postcode | 00100 |
4 | City | String | 0...1 | City | Helsinki |
4 | Country | String | 0...1 | Country | Finland |
3 | OfficeVisitAddress | Aggr. | 1 | Visiting address | |
4 | StreetAddress | String | 0...1 | Street address | Keskuskatu 1 |
4 | PostNumber | String | 0...1 | Postcode | 00100 |
4 | City | String | 0...1 | City | Helsinki |
4 | Country | String | 0...1 | Country | Finland |
3 | OfficeFinvoiceDetails | Aggr. | 1 | Office electronic invoicing details | |
4 | FinvoiceAddress | String | 0...1 | E-invoice address (IBAN or EIA) | 003716264123 |
4 | FinvoiceRouterCode | String | 0...1 | E-invoice operator code | 003721291126 |
2 | CustomerAdditionalInformation | Aggr. | 1 | ||
3 | Comment | String | 1 | Comment text | |
3 | CustomerAgreementIdentifier | String | 1 | Contract ID | |
3 | ReferenceNumber | String | 1 | Standard reference | |
3 | UseCreditorReferenceNumber | Numeric | 1 | Use RF-reference in invoicing. 1 or 0. | 1 |
3 | YourDefaultReference | String | 1 | Your default reference | |
3 | DefaultTextBeforeInvoiceLines | String | 1 | Default text before invoice rows | |
3 | DefaultTextAfterInvoiceLines | String | 1 | Default text after invoice rows | |
3 | DefaultPaymentTerm | String | 1 | Default payment term | 14 days net |
Attr. | NetvisorKey | String | 1 | NetvisorKey (ID) | 2 |
3 | TaxHandlingType | String | 1 | Default tax handling type | countrygroup |
3 | BalanceLimit | Decimal | 1 | Customer's balance limit, two decimal accuracy. | |
3 | DefaultSalesPerson | String | 0...1 | Name of the default sales person | |
3 | DiscountPercentage | Numeric | 0...1 | Discount percentage | 10 |
3 | PriceGroup | String | 0...1 | Price group in which customer is linked | |
3 | FactoringAccount | String | 0...1 | Customer's factoring account name | Factoring |
Attr. | NetvisorKey | Numeric | 1 | Factoring account's NetvisorID | 1 |
3 | InvoicingLanguage | String | 0...1 | Customer's invoicing language | FI |
Attr. | type | String | 1 | Always ISO-3166 | |
3 | EUStandardFinvoice | Numeric | 0...1 | E-invoice that complies w/ EU standard. 1= Yes, 0 = No. | 1 |
3 | CustomerDimensions | Aggr. | 0...1 | ||
4 | Dimension | Aggr. | 0...n | ||
5 | DimensionName | String | 1 | Customer specific dimension header | Animals |
Attr. | NetvisorKey | String | 1 | Dimension header Netvisor ID | 4 |
5 | DimensionItem | String | 1 | Customer specific dimension name | Cats |
Attr. | NetvisorKey | String | 1 | Dimension Netvisor ID | 117 |
2 | AdditionalInformation | Aggr. | 0...1 | ||
3 | ReceivablesManagement | Aggr. | 1 | Customer's invoicing details | |
4 | TurnoverDays | Numeric | 1 | The turnover days for customer's invoices | 42 |
4 | TurnoverDeviation | Numeric | 1 | The turnover deviation for customer's invoices | 28 |
Import customer details
Resource: customer.nv
With customer.nv old customer details can be edited or a new customer can be added to Netvisor.
When editing existing customer details, the XML should only include details that are intended to be updated. If the XML contains blank fields(elements), are these fields updated as blank in Netvisor.
If customerfinvoicedetails element is given, element content validity is not checked. The operator must be still found from system. Below is list of operator codes that are allowed in Netvisor:
Operator | Code |
Aktia/Paikallisosuuspankki | HELSFIHH |
Ålandsbanken | AABAFI22 |
Apix Messaging Oy | 003723327487 |
Apix Messaging Oy (old code) | 00372332748700001 |
BasWare Einvoices Oy | BAWCFI22 |
CGI Suomi (ent. Logica Suomi Oy) | 003703575029 |
Danske Bank | DABAFIHH |
DNB Bank ASA, Finland Branch | DNBAFIHX |
Enfo | 003714377140 |
Handelsbanken | HANDFIHH |
InExchange Factorum AB | INEXCHANGE |
InExchange Factorum AB (old code) | SE556700997101 |
Liaison Technologies Oy (ent. Anilinker) | 003708599126 |
Maventa | 003721291126 |
Netbox Finland Oy | 003726044706 |
Nordea | NDEAFIHH |
Notebeat Oy | 003717203971 |
OpusCapita (can be used until 31.12.2018) | 003710948874 |
OpusCapita Solutions Oy | E204503 |
Osuuspankki | OKOYFIHH |
Pagero | 003723609900 |
POP Pankki | POPFFI22 |
PostNord Strålfors Oy | 003701150617 |
Ropo Capital | 003714377140 |
Säästöpankki | ITELFIHH |
S-Pankki/LähiTapiola | SBANFIHH |
Sproom ApS | SPROOM |
Telia/CGI Finland Oyj | 003703575029 |
Tieto Oyj | 003701011385 |
Peppol | PEPPOL |
Querystring parameters:
Parameter name | Occurs | Description | Example |
method | 1 | Add or Edit | Add |
id | 0...1 | Must be defined if method = Edit, defines customer to update | 123 |
If method has not been supplied or the customer to update is not found for the id, an INVALID_DATA -error with further information is returned.
The id of a customer to update can be obtained with Get Customer List, and salesperson id with Get Salespersonnel List.
The data to import is sent with the query as an XML with the following structure:
Level | Element name | Type and length | Occurs | Description | Example |
Root | root | Aggr. | 1 | ||
1 | customer | Aggr | 1 | ||
2 | customerbaseinformation | Aggr. | 1 | ||
3 | internalidentifier | String, max 50 | 0...1 | Customer's identifier | MM123 |
Attr. | type | String | 0...1 | automatic (if given and internalidentifier is empty, customer's identifier in Netvisor will be the next free customer identifier) | automatic |
3 | externalidentifier | String | 0...1 | Organization identifier or private customer social security number | 123456-7 |
3 | organizationunitnumber | String, max 17 | 0...1 | Organization unit number | 0037123456715 |
3 | name | String, max 250 | 0...1 | Customer's name | Matti Meikäläinen |
3 | nameextension | String, max 250 | 0...1 | Extension for name | Toimitusjohtaja |
3 | streetaddress | String, max 80 | 0...1 | Customer's Street address | Pajukuja 1 |
3 | additionaladdressline | String, max 80 | 0...1 | Additional address line | |
3 | city | String, max 80 | 0...1 | Customer's post office | Lappeenranta |
3 | postnumber | String, max 50 | 0...1 | Customer's post number | 53100 |
3 | country | String, | 0...1 | Customer's country code | FI |
Attr. | type | String | 0...1 | Always ISO-3166 | ISO-3166 |
3 | customergroupname | String, max 50 | 0...1 | Customer is attached to group by its name. If group does not exists, new group is created | Alennusasiakkaat |
3 | phonenumber | String, max 80 | 0...1 | Customer's phone number | 040 123456 |
3 | faxnumber | String, max 80 | 0...1 | Customer's fax number | 05 123456 |
3 | String, max 200 | 0...1 | Customer's E-mail address | matti.meikäläinen@firma.fi | |
3 | homepageuri | String, max 80 | 0...1 | Customer www-address | www.firma.fi |
3 | isactive | Integer | 0...1 | 0 or 1, indicates whether customer is active | 1 |
3 | isprivatecustomer | Integer | 0...1 | 0 or 1, indicates whether customer is a Private Customer | 1 |
3 | emailinvoicingaddress | String, max 500 | 0...1 | Valid e-mail invoice address. Can be given as a list, separated with ;. | matti.meikäläinen@firma.fi |
2 | customerfinvoicedetails | Aggr. | 0...1 | ||
3 | finvoiceaddress | String | 1 | E-Invoice address | FI109700021497 |
3 | finvoiceroutercode | String | 1 | E-invoice operator, see valid values from list above | NDEAFIHH |
2 | customerdeliverydetails | Aggr. | 0...1 | ||
3 | deliveryname | String, max 250 | 0...1 | Recipient of the delivery | Matti Meikäläinen |
3 | deliverystreetaddress | String, max 80 | 0...1 | Street address | Pajukuja 1 |
3 | deliverycity | String, max 80 | 0...1 | Post office | Lappeenranta |
3 | deliverypostnumber | String, max 50 | 0...1 | Post number | 53100 |
3 | deliverycountry | String | 0...1 | Country code | FI |
Attr. | type | String | 0...1 | Always ISO-3166 | ISO-3166 |
2 | customercontactdetails | Aggr. | 0...1 | ||
3 | contactname | String | 0...1 | ||
3 | contactperson | String, max 80 | 0...1 | Contact person's name | Matti Meikäläinen |
3 | contactpersonemail | String, max 200 | 0...1 | Contact person's E-mail | matti.maikalainen@firma.fi |
3 | contactpersonphone | String, max 80 | 0...1 | Contact person's phone number | 040 123 4567 |
2 | customeradditionalinformation | Aggr. | 0...1 | ||
3 | comment | String, max 2500 | 0...1 | Comment for the customer register | |
3 | customeragreementidentifier | String, max 35 | 0...1 | Contract ID | |
3 | customerreferencenumber | String | 0...1 | standard reference | |
3 | Invoicinglanguage | String | 0...1 | Invoice language: FI, EN or SE. If the element is not given by message, the default language is Finnish | FI |
Attr. | type | String | 0...1 | Always ISO-3166 | ISO-3166 |
3 | invoiceprintchannelformat | Integer | 0...1 | Invoice print channel format 1= Invoice+bank transfer 2=Invoice | 1 |
Attr. | type | String | 1 | Always netvisor | netvisor |
3 | yourdefaultreference | String, max 200 | 0...1 | Your default reference | |
3 | defaulttextbeforeinvoicelines | String, max 500 | 0...1 | Default text before invoice rows | |
3 | defaulttextafterinvoicelines | String, max 500 | 0...1 | Default text after invoice rows | |
3 | defaultpaymentterm | String | 0...1 | Customer default payment term | 14 days net |
Attr. | type | String | 1 | netvisor (ID) or customer (name) | customer |
3 | defaultsecondname | String | 0...1 | Default second name | Second name |
Attr. | type | String | 1 | netvisor (ID) or customer (name) | customer |
3 | paymentinterest | Integer | 0...1 | Penalty interest, value can be between 0-100 | 5 |
3 | balancelimit | Integer | 0...1 | Customer balance limit | 5000 |
3 | receivablesmanagementautomationrule | String | 0...1 | Automatic rule for reminders | Private customers |
Attr. | type | String | 1 | netvisor (ID) or customer (name) | customer |
3 | factoringaccount | String | 0...1 | Factoring account | 1 |
Attr. | type | String | 1 | netvisor (ID) or customer (name) | netvisor |
3 | taxhandlingtype | String | 0...1 | Customer tax handling type, valid values are countrygroup, forcedomestic, notaxhandling and domesticconstructionservice | countrygroup |
3 | eustandardfinvoice | Integer | 0...1 | E-invoice that complies w/ EU standard. 1= Yes, 0 = No. | 1 |
3 | defaultsalesperson | Aggr. | 0...1 | ||
4 | salespersonid | String | 0...1 | Default salesperson's id | |
Attr. | type | String | 1 | Always netvisor | netvisor |
2 | customerdimensiondetails | Aggr. | 0...1 | ||
3 | dimension | Aggr. | 1 | ||
4 | dimensionname | String | 1 | Default dimension header name. Created if needed. | Project |
4 | dimensionitem | String | 1 | Dimension name. Created if needed. | Project 1 |
Delete customer details
Resource: deletecustomer.nv
Resource can be used to delete single customer's details from Netvisor. The response is "OK" if the customer can be deleted and if the message fails, API tells the reason e.g. "The customer has invoices".
Query string parameter:
Parameter | Occurs | Description | Example |
customerid | 1 | Customer's NetvisorKey (ID) | 12 |
Import customer office
Resource: office.nv
Importing and editing customer's office details.
Querystring parameters:
Parameter | Occurs | Description | Example |
method | 1 | Add or Edit | Add |
customerid | 1 | Customer's NetvisorID | 123 |
officeid | 0...1 | Office NetvisorID, mandatory when editing existing | 1 |
Notify these:
- With edit you can remove information by giving tag as empty
- Office name is mandatory, it can never be empty
- FinvoiceAddress needs to be genuine OVT or IBAN-number
- FinvoiceOperator accepts all the same ID's than other resources, see list above
Level | Element | Type and length | Occurs | Description | Example |
Root | root | Aggr. | 1 | ||
1 | office | Aggr. | 1 | ||
2 | name | String | 1 | Office name | |
2 | phonenumber | String | 0...1 | Office phone | |
2 | telefaxnumber | String | 0...1 | Office fax | |
2 | officeidentifier | String | 0...1 | Office code | |
2 | emailinvoicingaddress | String | 0...1 | E-mail invoice address of the office | |
2 | officecontactaddress | Aggr. | 0...1 | Office postal information | |
3 | streetaddress | String | 1 | Street name | |
3 | postnumber | String | 1 | Post number | |
3 | city | String | 1 | City | |
3 | country | String | 1 | Country code | |
Attr. | type | String | 1 | Always ISO-3166 | |
2 | officevisitaddress | Aggr. | 0...1 | Office visiting address | |
3 | streetaddress | String | 1 | Street name | |
3 | postnumber | String | 1 | Post number | |
3 | city | String | 1 | City | |
3 | country | String | 1 | Country code | |
Attr. | type | String | 1 | Always ISO-3166 | |
2 | officefinvoicedetails | Aggr. | 0...1 | Office electronic invoicing details | |
3 | finvoiceaddress | String | 1 | E-invoice address (IBAN or OVT) | |
3 | finvoiceroutercode | String | 1 | E-invoice operator |
Import customer contact person
Resource: contactperson.nv
Importing, editing and deleting customer's contact person details.
The data to import is sent with the query as an XML with the following structure:
Level | Element | Type and length | Occurs | Description | Example |
Root | root | Aggr. | 1 | ||
1 | contactperson | Aggr. | 1 | ||
2 | method | String | 1 | add|edit|delete | |
2 | customeridentifier | Numeric | 1 | Customer's netvisorkey | 12 |
Attr. | type | String | 1 | netvisor | netvisor |
2 | contactpersonidentifier | String | 0...1 | Contact person's netvisorkey, if editing or deleting contact person | 1 |
Attr. | type | String | 1 | netvisor | netvisor |
2 | isdefault | String | 0...1 | True, sets contact person as default | true |
2 | firstname | String, max. 100 | 1 | First name | Example |
2 | lastname | String, max. 100 | 1 | Last name | Customer |
2 | language | String | 1 | FI|EN|SE | EN |
Attr. | type | String | 1 | Always ISO-3166 | ISO-3166 |
2 | phonenumber | Numeric, max. 80 | 0...1 | Phone number | 0401234567 |
2 | String, max. 200 | 0...1 | Email address | example@example.com | |
2 | title | String, max. 200 | 0...1 | Director | |
2 | officeidentifier | String | 0...1 | Contact person's office netvisorkey, reset with value 0 | 4 |
Atrr. | type | String | 1 | netvisor | netvisor |
2 | positionidentifier | String | 0...1 | Contact person's position netvisorkey, reset with value 0 | 1 |
Attr. | type | String | 1 | netvisor | netvisor |
2 | contactpersonaddress | Aggr. | 1 | ||
3 | streetaddress | String, max. 80 | 0...1 | Address | Street 1 |
3 | postnumber | Numeric, max. 50 | 0...1 | Post number | 00100 |
3 | city | String, max. 80 | 0...1 | City | Helsinki |
3 | country | String | 0...1 | Country | Finland |
Attr. | type | String | 1 | Always ISO-3166 | ISO-3166 |
Get sales personnel list
Resource: salespersonnellist.nv
Returns a list of sales personnel.
Level | Element | Type | Occurences | Description | Example |
Root | root | Aggr. | 1 | ||
1 | SalesPersonnelList | Aggr. | 1 | ||
2 | SalesPerson | Aggr. | 0...n | ||
Attr. | NetvisorKey | String | 1 | Sales person's Netvisor id | 1 |
3 | FirstName | String | 1 | Sales person's first name | Matt |
3 | LastName | String | 1 | Sales person's last name | Smith |
3 | ProvisionPercent | Integer | 1 | Sales person's provision percent | 10 |
Did you find it helpful? Yes No
Send feedback