| 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 | Text | 1 | Identifier type, allowed values: taxidentificationnumber foreignpersonalidentifier other | foreignpersonalidentifier |
| 4 | issuingcountry | Text | 1 | Country | AF |
| Attr. | type | Text | 1 | Country type | ISO-3316 |
| 4 | gender | Text | 1 | Gender, male female | male |
| 4 | dateofbirth | Date | 1 | Date of birth | 1970-10-20 |
| Attr. | format | Text | 1 | Date format | ansi |
| 3 | employeeidentifier | Text | 1 | Finnish employee social security number | 010277-xxxp |
| 3 | companyidentifier | Text | 0...1 | Company indentifier (y-tunnus), when company is added as an employee | 0174564-5 |
| 3 | companyname | Text | 0...1 | Name of the company | Test Company |
| 3 | firstname | Text, max 50 | 1 | Employee's first name | Carl |
| 3 | lastname | Text, max 50 | 1 | Employee's last name | Customer |
| 3 | phonenumber | Text, max 50 | 1 | Employee's phone number | 0501234567 |
| 3 | Text, max 100 | 1 | Employees E-mail | carl.customer@company.fi | |
| 2 | employeepayrollinformation | Aggr. | 1 | ||
| 3 | streetaddress | Text, max 255 | 1 | Employee's address | Examplestreet 1 |
| 3 | postnumber | Text, max 50 | 1 | Employee's post number | 56123 |
| 3 | city | Text, max 255 | 1 | Employee's post office | Lappeenranta |
| 3 | municipality | Text, max 255 | 0...1 | Employees's home city | Lappeenranta |
| 3 | country | Text, max 2 | 0...1 | Employee's home country. Default is 'fi' | fi |
| 3 | nationality | Text, max 2 | 0...1 | Employee's nationality | se |
| 3 | language | Text, max 2 | 0...1 | Employee's language | fi |
| 3 | employeenumber | Numeric | 0...1 | Employee's unique identification number | 12 |
| 3 | profession | Text, max, 255 | 0...1 | Employee's profession | Seller |
| 3 | jobbegindate | Text, max 10 | 0...1 | Employee's job begin date, yyyy-mm-dd | 2014-08-10 |
| Attr. | format | Text | 1 | Date format, always ansi | ansi |
| 3 | payrollrulegroupname | Text, max 50 | 1 | Payroll group name | Monthly salary |
| 3 | bankaccountnumber | Text, maks. 34 | 0...1 | Employee's bank account number | FI21 1234 xxxx xxxx xx |
| 3 | bankidentificationcode | Text, 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 | Text | 0...1 | Hierarchy level | Oy Yritys Ab |
| Attr. | type | Text | 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 | Text | 1 | Dimension header name. Created if needed | Cost centers |
| 4 | dimensionitem | Text | 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 | Text | 0...1 | Payslip delivery method | 1 = local printing 2 = printing service 3 = e-salary |
| Attr. | type | Text | 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 | Text | 1 | Date format | ansi |
| 4 | startdate | Date | 1 | Start date | 2017-01-01 |
| Attr. | format | Text | 1 | Date format | ansi |
| 4 | probationenddate | Date | 0...1 | End date of probation | 2017-04-01 |
| Attr. | format | Text | 1 | Date format | 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 | Text | 1 | Linking type of employment | Attribute type is always netvisor, which is Netvisor ID |
| 4 | profession | Text, max 250 | 1 | Professional title | Tester |
| 4 | comment | Text, max 500 | 0...1 | Comment | Knows what she is doing |
| 4 | enddate | Date | 0...1 | End date | 2017-12-31 |
| Attr. | format | Text | 1 | Date format | 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 | Text | 1 | Linking type of endreason | Attribute type is always netvisor, which is Netvisor ID |
| 4 | occupationclassification | Text | 0...1 | Occupation class | TK10-code of occupation class |
| Attr. | type | Text | 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 | Text | 1 | Linking type of employment contract | always netvisor |
| 4 | employmentform | Numeric | 0...1 | 1 = Full-time 2 = Part-time | |
| Attr. | type | Text | 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 | Text | 1 | always keva | keva |
| Attr. | pensionprovidercode | Text | 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 |
| 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 | Text | 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 | Text | 0...1 | Payroll operations service | enabled or disabled |
| 3 | resourcemanagement | Text | 0...1 | Resource management | |
| 2 | employeesettlementpoints | Aggr. | 0...1 | Settlement points | |
| 3 | employeeworkpensioninsurance | Aggr. | 0...1 | Work pension insurance | |
| 4 | type | Text | 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 | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeeunemploymentinsurance | Aggr. | 0...1 | Unemployment insurance | |
| 4 | type | Text | 0...1 | Settlement point 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 | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeeaccidentinsurance | Aggr. | 0...1 | Accident insurance | |
| 4 | type | Text | 0...1 | Settlement point handling | nohandling or attachedtosettlementpoint |
| 4 | name | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeegrouplifeinsurance | Aggr. | 0...1 | Group life insurance | |
| 4 | type | Text | 0...1 | Settlement point handling | nohandling or attachedtosettlementpoint |
| 4 | name | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeeotherinsurance | Aggr. | 0...1 | Other insurance | |
| 4 | type | Text | 0...1 | Settlement point handling | nohandling or attachedtosettlementpoint |
| 4 | name | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeeunionmembershipfee | Aggr. | 0...1 | Union membership fee | |
| 4 | type | Text | 0...1 | Settlement point handling | nohandling or attachedtosettlementpoint |
| 4 | name | Text | 0...1 | Insurance specific settlement point definition (* | |
| 3 | employeeforeclosure | Aggr. | 0...1 | fore closure | |
| 4 | type | Text | 0...1 | Settlement point handling | nohandling or attachedtosettlementpoint |
| 4 | name | Text | 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 | salaryparameters | 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 | Text | 1 | Identification of the employee | 123456-123A |
| Attr. | Type | Text | 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 | Name | Text | 1-3 | Name of salary type | Ulkomaan päiväraha |
| Attr. | ISO639-1Code | Text | 1 | Language information of salary type's name: fi,se, en | fi |
| 3 | Identifier | Numeric | 1 | ID of salary type | 1 |
| 3 | Source | Text | 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 | Text | 1 | Has to exist in Netvisor and the employee must be determined for correct wage model in Netvisor before transferring the data | 10 |
| Attr. | type | Text | 1 | Type of identiier, 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 | 2018-02-01 |
| Attr. | format | Text | 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 | 2018-02-28 |
| Attr. | format | Text | 1 | Date format, always ansi | ansi |
| 2 | freetextbeforelines | Text | 0...1 | Free text before payroll lines | |
| 2 | freetextafterlines | Text | 0...1 | Free text after payroll lines | |
| 2 | duedate | Date | 1 | Due date | 2018-02-17 |
| Attr. | format | Text | 1 | Date format. always ansi | ansi |
| 2 | valuedate | Date | 1 | Value date | 2018-02-17 |
| Attr. | format | Text | 1 | Date format, always ansi | ansi |
| 2 | payrollpaycheckbatchline | Aggr. | 1...n | ||
| 3 | payrollratioidentifier | Text | 1 | Salary type as number, has to excist in Netvisor | 1 |
| Attr. | type | Text | 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 | Text | 0...1 | Description of the line | |
| 3 | dimension | Aggr. | 0...n | ||
| 4 | dimensionname | Text | 1 | Title of the dimension. If not found, it will be created | |
| 4 | dimensionitem | Text | 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 | Employeee 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 | Text | 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 | Text | ansi | ansi | |
| 2 | duedate | Date | 1 | Due date, salary will be charged from company's account | 2017-01-01 |
| Attr. | format | Text | ansi | ansi | |
| 2 | externalpaymentsum | Decimal | 1 | Amount of payment (0.01 < sum < 10000000.0) | 100,0 |
| 2 | iban | Text | 1 | Employee's bank account number | FI21 1234 xxxx xxxx xx |
| 2 | bic | Text | 1 | Bank's identification code | NDEAFIHH |
| 2 | hetu | Text | 1 | Employee's social security number | 140785-xxyy |
| 2 | realname | Text | 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 feedbackSorry we couldn't be helpful. Help us improve this article with your feedback.