IntegrationHTTP-methodResourceDTDExample
Import an employeePOSTemployee.nvemployee.dtdDownload
Get employee salary parametersGETgetemployeesalaryparameters.nv Download
Import employee salary parametersPOSTemployeesalaryparameters.nvemployeesalaryparameters.xsdDownload
Get salary typesGETpayrollratiolist.nv Download
Import a payroll paycheck batchPOSTpayrollpaycheckbatch.nvpayrollpaycheckbatch.dtdDownload
Import record line for pay periodPOSTpayrollperiodcollector.nvpayrollperiodcollector.dtdDownload
Import pay advancePOSTpayrolladvance.nvpayrolladvance.dtdDownload
Import external salary payment dataPOSTpayrollexternalsalarypayment.nvpayrollexternalsalarypayment.dtdDownload

Import an employee

Resource: employee.nv

Import an employee's information.
Querystring parameters:

Parameter nameOccursExampleDescription
Method1AddAdd or Edit

Request:

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1employeeAggr1  
2employeebaseinformationAggr.1  
3foreignemployeeidentificationAggr.0...1Foreign employeeIf given, do not give employeeidentifier value
4identifierText1Identifier23011970
Attr.typeString
1Identifier type, allowed values:
taxidentificationnumber
foreignpersonalidentifier
other
foreignpersonalidentifier
4issuingcountryString
1CountryAF
Attr.typeString
1Country typeISO-3316
4genderString
1Gender,
male
female
male
4dateofbirthDate1Date of birth
1970-10-20
Attr.formatString
1Date formatansi
3employeeidentifierString
1Finnish employee social security number010277-xxxp 
3companyidentifierString
0...1Company indentifier (y-tunnus),
when company is added as an employee
0174564-5
3companynameString
0...1Name of the companyTest Company
3firstnameString, max 50 1Employee's first name Carl
3lastnameString, max 50 1Employee's last name Customer
3phonenumberString, max 50 1Employee's phone number 0501234567
3emailString, max 100 1Employees E-mail carl.customer@company.fi
2employeepayrollinformationAggr.1  
3streetaddressString, max 2551Employee's address Examplestreet 1
3postnumberText, max 501Employee's post number 56123
3cityString, max 2551Employee's post officeLappeenranta
3municipalityString, max 2550...1Employees's home cityLappeenranta
3countryString, max 20...1Employee's home country. Default is 'fi'fi
3nationalityString, max 2 0...1Employee's nationalityse
3languageString, max 2 0...1Employee's language fi
3employeenumberNumeric0...1Employee's unique identification number 12
3professionString, max, 2550...1Employee's profession Seller
3jobbegindateString, max 100...1Employee's job begin date, yyyy-mm-dd2014-08-10
Attr.formatString
1Date format, always ansiansi
3payrollrulegroupnameString, max 501Payroll group nameMonthly salary
3bankaccountnumberString, maks. 340...1Employee's bank account numberFI21 1234 xxxx xxxx xx
3bankidentificationcodeString, max. 200...1Bank's identification code  
3accountingaccountnumberNumeric 0...1You can access company's accounting information in Netvisor from ACCOUNTING > Administration > Accounting basic information > Account list1751
3hierarchyString
0...1Hierarchy levelOy Yritys Ab 
Attr.typeString
1Linking type of hierarchynetvisor - Netvisor ID
or
customer - If identified by name, name has to be unique
Read about company hierarchy
3dimensionAggr.0...n Default dimensions
4dimensionnameString1Dimension header name.
Created if needed
Cost centers
4dimensionitemString
1Dimension name. Created if neededDevOps
Attr.fatheridNumeric0...1Dimensions parent ID tunnus. IDs can be retrieved with this resource.1
3payslipdeliverymethodString
0...1Payslip delivery method1 = local printing
2 = printing service
3 = e-salary
Attr.typeString
1Linking type of delivery methodAttribute type is always netvisor, which is Netvisor ID
3isjointownerNumeric0...1In a shareholder relationship with payer1=yes
0=no
3isathleteNumeric0...1Athlete1=yes
0=no
3isperformingartistNumeric0...1Performing atrist1=yes
0=no
3employeeincurancetypeNumeric0...1Employee pension insurance type1=Tyel
2=MYEL
3=YEL
4=No pension insurance
3ispersonworkingonaroadferryonalandislandsNumeric0...1Person working on a road ferry on Åland Islands1=yes
0=no
3isentrepreneurwithoptionalyelormyelNumeric0...1Entrepreneur, no YEL or MYEL insurance obligation1=yes
0=no

1 can be given only when employeeincurancetype=4
3nosocialsecuritypaymentNumeric0...1Not subject to employer's sickness insurance payment1=yes
0=no
2employmentperiodsAggr.0...1Employments 
3employmentperiodAggr.1...nEmployment 
4companystartdateDate0...1Start date of continuous employment2017-01-01
Attr.formatString
1Date formatansi
4startdateDate1Start date2017-01-01
Attr.formatString
1Date formatansi
4probationenddateDate0...1End date of probation2017-04-01
Attr.formatString
1Date formatansi
4employmentmodeNumeric0...1Form of employment1 = employed
2 = leased employee
3 = self-employed person or
 similar
4 = trainee
5 = voluntary work
Attr.typeString
1Linking type of employmentAttribute type is always netvisor, which is Netvisor ID
4professionString, max 250
1Professional titleTester
4commentString, max 5000...1CommentKnows what she is doing
4enddateDate0...1End date2017-12-31
Attr.formatString
1Date formatansi
4endreasonNumeric0...1End reason2=Retirement
4=Employee's own request
5=Reason attributable to the employee
6=Fixed-term employment
11=Financial and production-related grounds for termination
12=End of employment by mutual agreement
13=Other reason
(Not in use anymore:
1 = Normal employment ending
3 = Employee's death
7 = Probation period
8 = Cancellation of the employment
9 = Bankruptcy of the company
10 = Change of ownership of the company)
Attr.typeString
1Linking type of endreasonAttribute type is always netvisor, which is Netvisor ID
4occupationclassificationString
0...1Occupation classTK10-code of occupation class 
Attr.typeString
1 Linking type of occupation classification always isco
4employmentcontractNumeric0...1Duration of employment1 = Permanent
2 = Temporary
Note: For temporary contract must be given end date 
Attr.typeString
1Linking type of employment contractalways netvisor
4employmentformNumeric0...1 1 = Full-time
2 = Part-time
Attr.typeString
1Linking type of employment formalways netvisor
4parttimepercentNumeric0...1Part-time percentagePermissible value: decimal number from 0 to 100
Note: employmentform must be 2 so that the setting is taken into account.
Rounding to the nearest two decimal places
4regularworkinghoursNumeric0...1Regular working hoursPermissible value: decimal number from 0 to 168
Rounding to the nearest two decimal places
4groundsforemploymentNumeric0...1Grounds for employment0=Other grounds
1=Working or employment relationship
4kevaprofessionalclasscodeNumeric0...1Keva professional class code, max 20 characters
KEVA information can only be given is company has selected "Company pension insurer is Keva"
Keva's professional class codes:
Professional class codes
4kevaemploymentregistrationNumeric0...1Keva employment registration code, max 2 characters.
Keva employment registration codes:
Keva employment registration codes
Attr.typeString
1always kevakeva
Attr.pensionprovidercodeString
0...1Pension company ID code. If not given, default (20) will be used. This defines which values can be given in kevaemploymentregistrationCodes can be found here: Pension company ID codes
ispaymenttypemonthlywageNumeric0...1Form of payment: Monthly wages1=yes
0=no
4ispaymenttypehourlywageNumeric0...1Form of payment: Hourly wages1=yes
0=no
4ispaymenttypepiecewageNumeric0...1Form of payment: Contract pay1=yes
0=no
4collectiveagreementNumeric0...1Collective agreementIncomes registers collective agreement codes:
Collective agreement codes
Attr.typeString
1always cbacodecbacode
4stateemploymentfundNumeric0...1Employed with assistance from the State employment fund1=yes
0=no
4carbenefityearNumeric0...1Year of commissioning of the company car, max 4 characters2012
4isabroadcarbenefitNumeric0...1Company car benefit received in another country. 1=yes
0=no
2employeesettingsAggr.0...1Settings for the employee 
3payrollserviceString
0...1Payroll operations service. enabled or disabledenabled
3resourcemanagementString
0...1Resource management 
2employeesettlementpointsAggr.0...1Settlement points 
3employeeworkpensioninsuranceAggr.0...1Work pension insurance 
4typeString
0...1Settlement point handlingnohandling=no handling
automatichandling=automatic handling
under17yearsold=under 17 years old 
17to52yearsold=17 to 52 years old 
53to62yearsold=53 to 62 years old
63to67yearsold=63 to 67 years old
over68yearsold=over 68 years old
4nameString
0...1Insurance specific settlement point definition (* 
3employeeunemploymentinsuranceAggr.0...1Unemployment insurance 
4typeString
0...1Settlement point handlingautomatichandling =Automatic handling 
under17yearsold=under 17 years old
17to64yearsold=17 to 64 years old
over65yearsold=over 65 years old
partowner=part owner
4nameString
0...1Insurance specific settlement point definition (* 
3employeeaccidentinsuranceAggr.0...1Accident insurance 
4typeString
0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameString
0...1Insurance specific settlement point definition (* 
3employeegrouplifeinsuranceAggr.0...1Group life insurance 
4typeString
0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameString
0...1Insurance specific settlement point definition (* 
3employeeotherinsuranceAggr.0...1Other insurance 
4typeString
0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameString
0...1Insurance specific settlement point definition (* 
3employeeunionmembershipfeeAggr.0...1Union membership fee 
4typeString
0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameString
0...1Insurance specific settlement point definition (* 
3employeeforeclosureAggr.0...1fore closure 
4typeString
0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameString
0...1Insurance specific settlement point definition (* 

 *) Settlement points: Salary > Payroll > Obligations > Settlements

Note when using this resource:

  • Editing employee is also possible when the employee's employment emplyment is not valid
  • If you are updating existing employee and you are not changing Employee number do not give tag
  • With this resource you cannot set holiday accural. This has to be done in Netvisor UI.
    • For a single employee, the information can be set on the employees's information page
    • For multiple employees, information can be set as mass in the management of holiday rights (Salaries > Holiday calculation settings): Select wanted employees, press "Handle select" and "Set holiday accumulation rule", and then select the wanted rule.
  • If employmentperiods-element has been defined, at least one employment has to be imported
    • startdate- and profession-elements are always mandatory
    • If enddate has been defined, then endreason is also mandatory
  • If employmentperiods-element has not been defined, employees employment will be set as it was before (employeepayrollinformation > profession and jobbegindate)
  • If employmentperiods-element has been defined, employment information will override employeepayrollinformation-definitions
  • If employments will be imported through API already existing (if any) employments will be deleted
  • If company is added as employee, do not give basic employee information, like:
    • employeeidentifier
    • firstname
    • lastname
    • foreignemployeeidentification -element

Get employee salary parameters

Resource: getemployeesalaryparameters.nv

If the paycheck does not have a value, the value element returns as an empty element (), whereas the zero value returns as a normal value ( 0,0 ).

With this resource it is possible to get employee salary parameters. Parameters used in the request (GET):

ParameterOccursDescription
identifiertype1Value: pin employee personal identity code or number employee number
identifier1 Identifier defined by the type: employee personal identity code or employee number

Response:

LevelElement nameType and lengthOccursDescriptionExample
rootrootAggr.1  
1employeesalaryparametersAggr.1  
2salaryparametersAggr.1  
3parameterAggr.0...n  
4rationumberNumeric1Number of the salary parameter123
4valueDecimal1Value of the salary parameter12,34

Import employee salary parameters

Resource: employeesalaryparameters.nv

It is possible to import part of the salary parameters (1-24 pcs at a time) in one request and the other part with another request. No changes are made in the salary parameters existing in Netvisor if they are not specified in the request.

If you want to set salary parameter to zero or update its value, a new value is given in the value element.  If the value of an existing salary parameter is to be completely eliminated, the value element is not given at all in the request.

This resource requires payroll accountant role (P role) from API user. 

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1employeesalaryparametersAggr.1  
2employeeidentificationString
1Identification of the employee123456-123A
Attr.typeString
1Type of the employee identificationi:
pin or number 
pin
2salaryparametersAggr.1  
3salaryparameterAggr.1...24  
4rationumberNumeric1Number of salary parameter's salary type (company-spesific salary types)123
4valueDecimal0...1Value of salary parameter12,30

Get salary types

Resource: payrollratiolist.nv

With this resource it is possible to get company-specific salary types. Salary types are used for importing trip expenses and payslips to Netvisor.

ParameterOccursDescriptionExample
source1...nThe request is limited by the salary type, which has to be one of the following:
- tripexpensecustomlines
- taxingrules
- collectorratiolines
- userparameters
- companyparameters
- userformula
- tabledata
- foreclosure
- lowsalarysupport
collectorratiolines

Vastaus:

LevelElementType and lengthOccursDescriptionExample
RootrootAggr.1  
1PayrollRatiosAggr.1  
2PayrollRatioAggr.0...n  
3NameString
1-3Name of salary typeUlkomaan päiväraha
Attr.ISO639-1CodeString
1Language information of salary type's name: fi,se, enfi
3IdentifierNumeric1ID of salary type1
3SourceString
1Type of salary typeMatkalasku, kulurivit
3RatioNumberNumeric1Number of salary type123
3DefaultDebitAccountNumberNumeric1Debit account for bookkeeping7890
3DefaultCreditAccountNumberNumeric1Credit account for bookkeeping2961

Import a payroll paycheck batch

Resource: payrollpaycheckbatch.nv

Import a payslip into Netvisor.

Request:

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1payrollpaycheckbatchAggr.1  
2employeeidentifierString
1Employee has to exist in Netvisor and the employee must be determined for correct wage model in Netvisor before transferring the data10
Attr.typeString1Type of identifier, either employeenumber or finnishpersonalidentifieremployeenumber
2rulegroupperiodstartDate1Pay period start date. Note! The period or the previous or next period has to exist in Netvisor. If period is not defined in Netvisor it will be added only if it is the first pay period of wage model or it begins right after the last pay period
2018-02-01
Attr.formatString
1Date format, always ansiansi
2rulegroupperiodendDate1Pay period end date. Note! The period or the previous or next period has to exist in Netvisor. If period is not defined in Netvisor it will be added only if it is the first pay period of wage model or it begins right after the last pay period
2018-02-28
Attr.formatString
1Date format, always ansi ansi
2freetextbeforelinesString
0...1Free text before payroll lines 
2freetextafterlinesString
0...1Free text after payroll lines  
2duedateDate1Due date 2018-02-17
Attr.formatString
1Date format. always ansiansi
2valuedateDate1Value date2018-02-17
Attr.formatString
1Date format, always ansiansi
2payrollpaycheckbatchlineAggr.1...n  
3payrollratioidentifierString
1Salary type as number, has to exist in Netvisor. Can be foud from Salaries > Salary model management > Company-specific salary types.1
Attr.typeString
1Always rationumberrationumber
3unitsNumeric1Number of units 2
3unitamountNumeric1price of a single unit 39
3linesumNumeric1Sum of the line, will not be calculated automatically, has to be given in XML. Recomended max 2 decimals.78,00
3linedescriptionString 0...1Description of the line 
3dimensionAggr.0...n  
4dimensionnameString
1Title of the dimension. If not found, it will be created  
4dimensionitemString
1Dimension name. If not found it will be created  

Import record line for pay period

Resource: payrollperiodcollector.nv

LevelElementType and lengthOccursDescriptionExample
RootRootAggr.1  
1payrollperiodcollectorAggr.1  
2dateDate1Date 
Attr.formatString1Always ansi 
2employeeidentifierString1Employee number in Netvisor 
Attr.typeString1number or personalidentificationnumber 
2payrollratiolineAggr.1...n  
3amountNumber1The amount of the record line 
3payrollratioNumber1Number of record type in Netvisor 
Attr.typeString0...1Always number 
3dimensionAggr.0...n  
4dimensionnameString1Title of dimension. If not found, it will be created 
4dimensionitemString1Name of the dimension. If not found, it will be created 
Attr.fatheridNumeric0...1Parent id of the dimension 

Import pay advance

Resource: payrolladvance.nv

Import payment for pay advance

LevelElementType and lenghthOccursDescriptionExample
RootRootAggr.1  
1payrolladvanceAggr.1  
2descriptionString0...1Open description of the event 
2employeeidentifierString1Employee number 
Attr.typeString0...1number or finnishpersonalidentifier 
2paymentdateDate1Date of pay advance's payment. Can't be earlier than today 
Attr.formatString0Always ansi (Notify that in the DTD there is a miskatake in this, if this attribute is given an error will occur) 
2advancesumNumber1Amount of pay advance 
Attr.paymentstatusString0...1ispaid or notpaid 
2paymenttypeString1payroll or tripexpence 

Importing external salary payment data

Resource: payrollexternalsalarypayment.nv

Is used to import external salary payment data. It is not necessary to import the whole
payslip, only the payment data. The data doesn't need to be linked to an employee in
Netvisor. Payment takes place in Netvisor, resource is quite similar to importing bank transfer.

LevelElement nameType and lengthOccursDescriptionExample
RootRootAggr.1  
1payrollexternalsalarypaymentAggr.1  
2descriptionString
1Description of the event. Informal definition
External payment
2paymentdateDate1Payment date = Payday, salary will be on employees account on this date2017-01-01
Attr.formatString
 ansiansi
2duedateDate1Due date, salary will be charged from company's account2017-01-01
Attr.formatString
 ansiansi
2externalpaymentsumDecimal1Amount of payment (0.01 < sum < 10000000.0)100,0
2ibanString
1Employee's bank account numberFI21 1234 xxxx xxxx xx
2bicString
1Bank's identification codeNDEAFIHH
2hetuString
1Employee's social security number140785-xxyy
2realnameString
1Employee's nameErkki Esimerkki

Either paymentdate or duedate will be set

Elements (paymentdate, duedate) terminology is according to SEPA-bank transfer standard:
SEPA Palkat Tiedote Tammikuu 2009

The date when payers account is charged is given in payment order instead of payment date; On this basis banks take care of that salaries and retirement payments are on recipients accounts at the payday in all banks that operate in Finland. This due date has to be banking day and it has must be a banking day before payday.

On the due date (duedate) salary is charged from company's account.
One banking day is added to the due date so that payment date = payday. If due date is eg. Friday, 3 days will be added so that due date is Monday.

Payment date (paymentdate) = payday, payroll is in employees account.
Banking day interpretation is not done at this moment, it will be interpreted in payment.

 


xml
(412 Bytes)
xml
(948 Bytes)
xml
(325 Bytes)
xml
(415 Bytes)
xml
xml
(299 Bytes)
xml
(2.95 KB)
xml
(513 Bytes)

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.