Resources - Employees, salary parameters and payslips

Integration	HTTP-method	Resource	DTD	Example
Import an employee	POST	employee.nv	employee.dtd	Download
Get employee salary parameters	GET	getemployeesalaryparameters.nv		Download
Import employee salary parameters	POST	employeesalaryparameters.nv	employeesalaryparameters.xsd	Download
Get salary types	GET	payrollratiolist.nv		Download
Import a payroll paycheck batch	POST	payrollpaycheckbatch.nv	payrollpaycheckbatch.dtd	Download
Import record line for pay period	POST	payrollperiodcollector.nv	payrollperiodcollector.dtd	Download
Import pay advance	POST	payrolladvance.nv	payrolladvance.dtd	Download
Import external salary payment data	POST	payrollexternalsalarypayment.nv	payrollexternalsalarypayment.dtd	Download

Import an employee

Resource: employee.nv

Import an employee's information.
Querystring parameters:

Parameter name	Occurs	Example	Description
Method	1	Add	Add or Edit

Request:

Level	Element name	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	employee	Aggr.	1
2	employeebaseinformation	Aggr.	1
3	foreignemployeeidentification	Aggr.	0...1	Foreign employee	If given, do not give employeeidentifier value
4	identifier	Text	1	Identifier	23011970
Attr.	type	String	1	Identifier type, allowed values: taxidentificationnumber foreignpersonalidentifier other	foreignpersonalidentifier
4	issuingcountry	String	1	Country	AF
Attr.	type	String	1	Country type	ISO-3316
4	gender	String	1	Gender, male female	male
4	dateofbirth	Date	1	Date of birth	1970-10-20
Attr.	format	String	1	Date format, always ansi	ansi
3	employeeidentifier	String	1	Finnish employee social security number	010277-xxxp
3	companyidentifier	String	0...1	Company indentifier (y-tunnus), when company is added as an employee	0174564-5
3	companyname	String	0...1	Name of the company	Test Company
3	firstname	String, max 50	1	Employee's first name	Carl
3	lastname	String, max 50	1	Employee's last name	Customer
3	phonenumber	String, max 50	1	Employee's phone number	0501234567
3	email	String, max 100	1	Employees E-mail	carl.customer@company.fi
2	employeepayrollinformation	Aggr.	1
3	streetaddress	String, max 255	1	Employee's address	Examplestreet 1
3	postnumber	Text, max 50	1	Employee's post number	56123
3	city	String, max 255	1	Employee's post office	Lappeenranta
3	municipality	String, max 255	0...1	Employees's home city	Lappeenranta
3	country	String, max 2	0...1	Employee's home country. Default is 'fi'	fi
3	nationality	String, max 2	0...1	Employee's nationality	se
3	language	String, max 2	0...1	Employee's language	fi
3	employeenumber	Numeric	0...1	Employee's unique identification number	12
3	profession	String, max, 255	0...1	Employee's profession	Seller
3	jobbegindate	String, max 10	0...1	Employee's job begin date, yyyy-mm-dd	2014-08-10
Attr.	format	String	1	Date format, always ansi	ansi
3	payrollrulegroupname	String, max 50	1	Payroll group name	Monthly salary
3	bankaccountnumber	String, maks. 34	0...1	Employee's bank account number	FI21 1234 xxxx xxxx xx
3	bankidentificationcode	String, max. 20	0...1	Bank's identification code
3	accountingaccountnumber	Numeric	0...1	You can access company's accounting information in Netvisor from ACCOUNTING > Administration > Accounting basic information > Account list	1751
3	hierarchy	String	0...1	Hierarchy level	Oy Yritys Ab
Attr.	type	String	1	Linking type of hierarchy	netvisor - Netvisor ID or customer - If identified by name, name has to be unique Read about company hierarchy
3	dimension	Aggr.	0...n		Default dimensions
4	dimensionname	String	1	Dimension header name. Created if needed	Cost centers
4	dimensionitem	String	1	Dimension name. Created if needed	DevOps
Attr.	fatherid	Numeric	0...1	Dimensions parent ID tunnus. IDs can be retrieved with this resource.	1
3	payslipdeliverymethod	String	0...1	Payslip delivery method	1 = local printing 2 = printing service 3 = e-salary
Attr.	type	String	1	Linking type of delivery method	Attribute type is always netvisor, which is Netvisor ID
3	isjointowner	Numeric	0...1	In a shareholder relationship with payer	1=yes 0=no
3	isathlete	Numeric	0...1	Athlete	1=yes 0=no
3	isperformingartist	Numeric	0...1	Performing atrist	1=yes 0=no
3	employeeincurancetype	Numeric	0...1	Employee pension insurance type	1=Tyel 2=MYEL 3=YEL 4=No pension insurance
3	ispersonworkingonaroadferryonalandislands	Numeric	0...1	Person working on a road ferry on Åland Islands	1=yes 0=no
3	isentrepreneurwithoptionalyelormyel	Numeric	0...1	Entrepreneur, no YEL or MYEL insurance obligation	1=yes 0=no 1 can be given only when employeeincurancetype=4
3	nosocialsecuritypayment	Numeric	0...1	Not subject to employer's sickness insurance payment	1=yes 0=no
2	employmentperiods	Aggr.	0...1	Employments
3	employmentperiod	Aggr.	1...n	Employment
4	companystartdate	Date	0...1	Start date of continuous employment	2017-01-01
Attr.	format	String	1	Date format, always ansi	ansi
4	startdate	Date	1	Start date	2017-01-01
Attr.	format	String	1	Date format, always ansi	ansi
4	probationenddate	Date	0...1	End date of probation	2017-04-01
Attr.	format	String	1	Date format, always ansi	ansi
4	employmentmode	Numeric	0...1	Form of employment	1 = employed 2 = leased employee 3 = self-employed person or similar 4 = trainee 5 = voluntary work
Attr.	type	String	1	Linking type of employment	Attribute type is always netvisor, which is Netvisor ID
4	profession	String, max 250	1	Professional title	Tester
4	comment	String, max 500	0...1	Comment	Knows what she is doing
4	enddate	Date	0...1	End date	2017-12-31
Attr.	format	String	1	Date format, always ansi	ansi
4	endreason	Numeric	0...1	End reason	2=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.	type	String	1	Linking type of endreason	Attribute type is always netvisor, which is Netvisor ID
4	occupationclassification	String	0...1	Occupation class	TK10-code of occupation class
Attr.	type	String	1	Linking type of occupation classification	always isco
4	employmentcontract	Numeric	0...1	Duration of employment	1 = Permanent 2 = Temporary Note: For temporary contract must be given end date
Attr.	type	String	1	Linking type of employment contract	always netvisor
4	employmentform	Numeric	0...1		1 = Full-time 2 = Part-time
Attr.	type	String	1	Linking type of employment form	always netvisor
4	parttimepercent	Numeric	0...1	Part-time percentage	Permissible 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
4	regularworkinghours	Numeric	0...1	Regular working hours	Permissible value: decimal number from 0 to 168 Rounding to the nearest two decimal places
4	groundsforemployment	Numeric	0...1	Grounds for employment	0=Other grounds 1=Working or employment relationship
4	kevaprofessionalclasscode	Numeric	0...1	Keva 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
4	kevaemploymentregistration	Numeric	0...1	Keva employment registration code, max 2 characters.	Keva employment registration codes: Keva employment registration codes
Attr.	type	String	1	always keva	keva
Attr.	pensionprovidercode	String	0...1	Pension company ID code. If not given, default (20) will be used. This defines which values can be given in kevaemploymentregistration	Codes can be found here: Pension company ID codes
4	ispaymenttypemonthlywage	Numeric	0...1	Form of payment: Monthly wages	1=yes 0=no
4	ispaymenttypehourlywage	Numeric	0...1	Form of payment: Hourly wages	1=yes 0=no
4	ispaymenttypepiecewage	Numeric	0...1	Form of payment: Contract pay	1=yes 0=no
4	collectiveagreement	Numeric	0...1	Collective agreement	Incomes registers collective agreement codes: Collective agreement codes
Attr.	type	String	1	always cbacode	cbacode
4	stateemploymentfund	Numeric	0...1	Employed with assistance from the State employment fund	1=yes 0=no
4	carbenefityear	Numeric	0...1	Year of commissioning of the company car, max 4 characters	2012
4	isabroadcarbenefit	Numeric	0...1	Company car benefit received in another country.	1=yes 0=no
2	employeesettings	Aggr.	0...1	Settings for the employee
3	payrollservice	String	0...1	Payroll operations service. enabled or disabled	enabled
3	resourcemanagement	String	0...1	Resource management
2	employeesettlementpoints	Aggr.	0...1	Settlement points
3	employeeworkpensioninsurance	Aggr.	0...1	Work pension insurance
4	type	String	0...1	Settlement point handling	nohandling=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
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeeunemploymentinsurance	Aggr.	0...1	Unemployment insurance
4	type	String	0...1	Settlement point handling	nohandling=no handling automatichandling =Automatic handling  under17yearsold=under 17 years old 17to64yearsold=17 to 64 years old over65yearsold=over 65 years old partowner=part owner
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeeaccidentinsurance	Aggr.	0...1	Accident insurance
4	type	String	0...1	Settlement point handling	nohandling or attachedtosettlementpoint
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeegrouplifeinsurance	Aggr.	0...1	Group life insurance
4	type	String	0...1	Settlement point handling	nohandling or attachedtosettlementpoint
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeeotherinsurance	Aggr.	0...1	Other insurance
4	type	String	0...1	Settlement point handling	nohandling or attachedtosettlementpoint
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeeunionmembershipfee	Aggr.	0...1	Union membership fee
4	type	String	0...1	Settlement point handling	nohandling or attachedtosettlementpoint
4	name	String	0...1	Insurance specific settlement point definition (*
3	employeeforeclosure	Aggr.	0...1	fore closure
4	type	String	0...1	Settlement point handling	nohandling or attachedtosettlementpoint
4	name	String	0...1	Insurance 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):

Parameter	Occurs	Description
identifiertype	1	Value: pin = employee personal identity code or number = employee number
identifier	1	Identifier defined by the type: employee personal identity code or employee number

Response:

Level	Element name	Type and length	Occurs	Description	Example
root	root	Aggr.	1
1	employeesalaryparameters	Aggr.	1
2	parameters	Aggr.	1
3	parameter	Aggr.	0...n
4	rationumber	Numeric	1	Number of the salary parameter	123
4	value	Decimal	1	Value of the salary parameter	12,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. 

Level	Element name	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	employeesalaryparameters	Aggr.	1
2	employeeidentification	String	1	Identification of the employee	123456-123A
Attr.	type	String	1	Type of the employee identificationi: pin or number	pin
2	salaryparameters	Aggr.	1
3	salaryparameter	Aggr.	1...24
4	rationumber	Numeric	1	Number of salary parameter's salary type (company-spesific salary types)	123
4	value	Decimal	0...1	Value of salary parameter	12,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.

Parameter	Occurs	Description	Example
source	1...n	The 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:

Level	Element	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	PayrollRatios	Aggr.	1
2	PayrollRatio	Aggr.	0...n
3	Names	Aggr.	0...n
4	Name	String	1-3	Name of salary type	Ulkomaan päiväraha
Attr.	ISO639-1Code	String	1	Language information of salary type's name: fi,se, en	fi
3	Identifier	Numeric	1	ID of salary type	1
3	Source	String	1	Type of salary type	Matkalasku, kulurivit
3	RatioNumber	Numeric	1	Number of salary type	123
3	DefaultDebitAccountNumber	Numeric	1	Debit account for bookkeeping	7890
3	DefaultCreditAccountNumber	Numeric	1	Credit account for bookkeeping	2961

Import a payroll paycheck batch

Resource: payrollpaycheckbatch.nv

Import a payslip into Netvisor.

Request:

Level	Element name	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	payrollpaycheckbatch	Aggr.	1
2	employeeidentifier	String	1	Employee has to exist in Netvisor and the employee must be determined for correct wage model in Netvisor before transferring the data	10
Attr.	type	String	1	Type of identifier, either employeenumber or finnishpersonalidentifier	employeenumber
2	rulegroupperiodstart	Date	1	Pay 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	2022-02-01
Attr.	format	String	1	Date format, always ansi	ansi
2	rulegroupperiodend	Date	1	Pay 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	2022-02-28
Attr.	format	String	1	Date format, always ansi	ansi
2	freetextbeforelines	String	0...1	Free text before payroll lines
2	freetextafterlines	String	0...1	Free text after payroll lines
2	duedate	Date	1	Due date	2022-02-17
Attr.	format	String	1	Date format, always ansi	ansi
2	valuedate	Date	1	Value date	2022-02-17
Attr.	format	String	1	Date format, always ansi	ansi
2	payrollpaycheckbatchline	Aggr.	1...n
3	payrollratioidentifier	String	1	Salary type as number, has to exist in Netvisor. Can be foud from Salaries > Salary model management > Company-specific salary types.	1
Attr.	type	String	1	Always rationumber	rationumber
3	units	Numeric	1	Number of units	2
3	unitamount	Numeric	1	price of a single unit	39
3	linesum	Numeric	1	Sum of the line, will not be calculated automatically, has to be given in XML. Recomended max 2 decimals.	78,00
3	linedescription	String	0...1	Description of the line
3	earningperiodstartdate	Date	0...1	Start date of the earning period	2022-01-01
Attr.	type	String	1	Date format, always ansi	ansi
3	earningperiodenddate	Date	0...1	End date of the earning period	2022-31-01
Attr.	type	String	1	Date format, always ansi	ansi
3	dimension	Aggr.	0...n
4	dimensionname	String	1	Title of the dimension. If not found, it will be created
4	dimensionitem	String	1	Dimension name. If not found it will be created

Import record line for pay period

Resource: payrollperiodcollector.nv

Level	Element	Type and length	Occurs	Description	Example
Root	Root	Aggr.	1
1	payrollperiodcollector	Aggr.	1
2	date	Date	1	Date
Attr.	format	String	1	Always ansi
2	employeeidentifier	String	1	Employee number in Netvisor
Attr.	type	String	1	number or personalidentificationnumber
2	payrollratioline	Aggr.	1...n
3	amount	Number	1	The amount of the record line
3	payrollratio	Number	1	Number of record type in Netvisor
Attr.	type	String	0...1	Always number
3	dimension	Aggr.	0...n
4	dimensionname	String	1	Title of dimension. If not found, it will be created
4	dimensionitem	String	1	Name of the dimension. If not found, it will be created
Attr.	fatherid	Numeric	0...1	Parent id of the dimension

Import pay advance

Resource: payrolladvance.nv

Import payment for pay advance

Level	Element	Type and lenghth	Occurs	Description	Example
Root	Root	Aggr.	1
1	payrolladvance	Aggr.	1
2	description	String	0...1	Open description of the event
2	employeeidentifier	String	1	Employee number
Attr.	type	String	0...1	number or finnishpersonalidentifier
2	paymentdate	Date	1	Date of pay advance's payment. Can't be earlier than today
Attr.	format	String	0	Always ansi (Notify that in the DTD there is a miskatake in this, if this attribute is given an error will occur)
2	advancesum	Number	1	Amount of pay advance
Attr.	paymentstatus	String	0...1	ispaid or notpaid
2	paymenttype	String	1	payroll 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.

Level	Element name	Type and length	Occurs	Description	Example
Root	Root	Aggr.	1
1	payrollexternalsalarypayment	Aggr.	1
2	description	String	1	Description of the event. Informal definition	External payment
2	paymentdate	Date	1	Payment date = Payday, salary will be on employees account on this date	2017-01-01
Attr.	format	String		ansi	ansi
2	duedate	Date	1	Due date, salary will be charged from company's account	2017-01-01
Attr.	format	String		ansi	ansi
2	externalpaymentsum	Decimal	1	Amount of payment (0.01 < sum < 10000000.0)	100,0
2	iban	String	1	Employee's bank account number	FI21 1234 xxxx xxxx xx
2	bic	String	1	Bank's identification code	NDEAFIHH
2	hetu	String	1	Employee's Personal identity code:	140785-xxyy
2	realname	String	1	Employee's name	Erkki 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.

 

Did you find it helpful? Yes No

Send feedback