Netvisor integration
Connect Huma to Netvisor to keep employee profiles and employment periods in sync
Table of contents
- Introduction
- Roles and access
- Set up the integration
- Sync employees
- Employee data
- Position data
- Absence data
- Salary data
- Change integration settings
- Error log
- FAQ
Introduction
The Netvisor integration keeps employee information in Huma and Netvisor in sync. You manage employees and positions in Huma, and Huma sends the changes to Netvisor.
This is what the integration supports, and how the data flows:
| Data | Huma → Netvisor | Netvisor → Huma | When |
|---|---|---|---|
| Employee data | ✅ Automatic | ✅ Manual only | Changes in Huma are sent in real time. Changes in Netvisor are brought in when you click "Sync users". |
| New employees | ✅ Manual only | ✅ Manual only | When you click "Sync users" |
| Positions (employment periods) | ✅ Automatic, if turned on | ❌ | When a position is created, updated or deleted in Huma |
| Absence | ❌ | ❌ | Not supported |
| Salary | ❌ | ❌ | Not supported |
⚠️ Historical data is not transferred. Only positions created, updated or deleted after the integration is active are sent to Netvisor.
💡 Need more than one connection, for example one per company? See Multiple connections.
Roles and access
| Access | Role |
|---|---|
| Set up and manage the integration in Huma | System role with full access to Organization |
| Create an API identifier and change API resource access rights in Netvisor | Administrator in Netvisor |
💡 Not sure which roles you need in Netvisor? Contact your Netvisor administrator or Netvisor support.
Set up the integration
Before you start
- You have a system role with full access to Organization in Huma.
- You, or a colleague, can log in to Netvisor as an administrator.
- Employees who exist in both systems have the same email address in Huma and Netvisor. Huma matches employees by email only.
- Employees you want to create in Netvisor from Huma have a Finnish personal identity code (HETU) and at least one position with a start date and a job title in Huma.
Step 1: Create an API identifier in Netvisor
- Log in to Netvisor as an administrator.
- Open the company menu and select "API identifiers".
- Create a new API identifier with the button on the right.
- Copy the "User ID" and the "Key" and keep them for later.
Allow the API resources
- Open the company menu and select "API resource access rights".
- Scroll down to the "Salaries" section.
- Allow these resources if they are not already allowed:
- employee.nv
- getemployee.nv
- getemployees.nv
- patchemployee.nv
- addjobperiod.nv, editjobperiod.nv and deletejobperiod.nv, if you will send positions to Netvisor

Find the Business ID
- Open the company menu and select "Service Management".
- Copy the "Business ID" and keep it for later.
Step 2: Connect Huma to Netvisor
- In Huma, go to "Integrations" and select "Netvisor".
- Read the "Overview" and "Details" tabs.
- Click "Set up" in the top-right corner.
- Give the connection a name.
- Choose who to include in the connection: everyone, or a specific team, location or company.
- Click "Continue".
- Paste the User ID, Key and Business ID from Netvisor.
- Confirm that you have the authority to accept the terms on behalf of your organization.
- Click "Continue".
Step 3: Choose what to sync
Netvisor has one setting. You can change it later. See Change integration settings.
| Setting | When on | When off |
|---|---|---|
| Positions: Create, update and delete | Positions created, updated or deleted in Huma create, update or delete the matching employment period in Netvisor. | No position data is sent to Netvisor. |
💡 We recommend turning on positions before you start managing positions in Huma.
Step 4: Sync users to activate the integration
After setup, the integration page shows "This integration is configured but not active". Nothing is sent until you sync users. See Sync employees.
Sync employees
"Sync users" compares the employees in Huma and Netvisor. You decide what to update and which employees to create. The first sync also activates the integration.
How to sync users
- Go to the Netvisor integration in Huma and click "Sync users".
- Matching users are employees with the same email in both systems.
- Review which fields have different or missing values.
- For each case, choose to update Huma with the value from Netvisor, update Netvisor with the value from Huma, or leave it as it is.
- Click "Next".
- Non-matching users are employees who exist in only one of the systems.
- Choose to create all, only the ones you select, or none.
- Choose the direction: Netvisor → Huma, or Huma → Netvisor.
- Click "Sync users".
The status changes to "Connected and active". You get an email with the result.
💡 Before you sync, decide which system has the most up-to-date information. The choices you make here overwrite data.
⚠️ Users missing required fields, such as the country on an identification, are not synced until the values are filled in. To create an employee in Netvisor, the employee needs a Finnish personal identity code (HETU) and a position with a start date and a job title in Huma.
When you need to sync users
Changes in Huma are sent to Netvisor automatically. Click "Sync users" when:
- You have just set up the integration and want to activate it.
- You have changed a supported field in Netvisor and want it in Huma.
- You have added employees in Netvisor that should be created in Huma.
- You have added employees in Huma that should be created in Netvisor. New employees are never created in Netvisor automatically.
Important information for the payroll clerk
When employees are created in Netvisor from Huma, check these fields manually in Netvisor under "Employee's information":
- Payroll information: The salary model is set to "No salary model".
- Settlement points: TyEL is set to "No handling". This causes an error when you update the employee. Select a suitable employment pension insurance.
When an employee leaves
Deactivated in Huma:
- The employee is not deactivated in Netvisor.
- The employee is locked from updates from the integration.
Deleted in Huma:
- The employee is not deleted in Netvisor.
- The next time you click "Sync users", you are offered to create the employee in Huma again.
💡 To register that an employment ends in Netvisor, set an end date and end reason on the position in Huma. See Position data.
Employee data
Changes in Huma are sent automatically. Changes in Netvisor are brought in with "Sync users".
| Huma field | Netvisor field | Required | Notes |
|---|---|---|---|
| Email address | ✅ | Used to match employees. Must be unique in Huma. When you change the email in Huma, it is updated in Netvisor. API name: employeebaseinformation.email |
|
| Identifications | Personal identity code | ✅ | A valid Finnish personal identity code (HETU) is required to create employees in Netvisor. Identity codes from other countries are accepted when you bring employees from Netvisor into Huma. Can't be updated or cleared by the integration. API name: employeebaseinformation.employeeidentifier |
| Given name | First name | ✅ | API name: employeebaseinformation.firstname |
| Family name | Last name | ✅ | API name: employeebaseinformation.lastname |
| Address | Street address, Municipality, Post number, Country | ✅ | All four must be filled in Netvisor for the address to be synced to Huma. API names: streetaddress, municipality, postnumber, country |
| Employee ID | Employee number | Must be unique. Must be a number. Max 10 characters. API name: employeepayrollinformation.employeenumber |
|
| Phone number | Phone number | Must be unique in Huma. API name: employeebaseinformation.phonenumber |
|
| Nationality | Nationality | If nationality is missing in Huma, Finnish is used. Can be updated, but not cleared, by the integration. API name: employeebaseinformation.nationality |
|
| Gender | Gender | Derived from the personal identity code in Netvisor. Only brought into Huma. Can't be updated or cleared by the integration. API name: employeebaseinformation.gender |
|
| Date of birth | Date of birth | Derived from the personal identity code in Netvisor. Only brought into Huma. Can't be updated or cleared by the integration. API name: employeebaseinformation.dateofbirth |
|
| Bank account | IBAN account number and Bank's BIC code | Only international format (IBAN and BIC). API names: bankaccountnumber, bankidentificationcode |
Position data
Positions go one way: from Huma to Netvisor, as employment periods. They are sent only when "Positions: Create, update and delete" is turned on.
How positions are sent
- Huma matches positions to employment periods in Netvisor by start date and job title.
- When you add a position in Huma, a new employment period is created in Netvisor. If a period with the same start date and job title already exists, nothing new is created.
- When you update a position, Huma finds the period with the start date and job title the position had before the change. If none is found, the update is not sent, and you see an error in the error log.
- When you delete a position, Huma deletes the matching period in Netvisor. If none is found, nothing is deleted.
- Netvisor doesn't allow overlapping employment periods. A new or updated position that overlaps another period is not sent, and you see an error in the error log.
- When an employee is created in Netvisor, their first position in Huma becomes the first employment period.
💡 When you edit the first position that Huma created automatically when Employee history was launched, make sure the start date and job title match the period in Netvisor. Or make your changes, save them, and click "Create new position".
| Huma field | Netvisor field | Notes |
|---|---|---|
| Contract start date | Start date and Company start date | Required. Used with the job title to match the period. Can't be cleared in Netvisor. API names: startdate, companystartdate |
| Job title | Profession | Required. Used with the start date to match the period. Can't be cleared in Netvisor. API name: profession |
| Contract end date | End date | API name: enddate |
| Probation end date | Probation end date | API name: probationenddate |
| Employment percentage | Employment form and Part-time percent | 100% is sent as full-time. Any other percentage is sent as part-time with the percentage. API names: employmentform, parttimepercent |
| Contract type | Employment method | See the table below. API name: employmentmode |
| End reason | End reason | See the table below. API name: endreason |
Contract types
| Contract type in Huma | Sent to Netvisor as |
|---|---|
| Permanent, Temporary, Seasonal, Casual, Job training program | Employed |
| Consultant, Freelance, Third party | Leased employee |
| Trainee | Trainee |
| Other | Not sent |
| Employment method in Netvisor | Brought into Huma as |
|---|---|
| Employed, Self employed | Permanent |
| Leased employee | Consultant |
| Trainee | Trainee |
| Voluntary work | Temporary |
End reasons
| End reason in Huma | Sent to Netvisor as |
|---|---|
| The employee has resigned | Employee's own request |
| The employer has terminated the employee | Reason attributable to the employee |
| The contract, engagement, or temporary position has expired | Fixed-term employment |
| Change in organizational structure or internal job transfer | Other reason |
| Changed payroll system or accountant | Other reason |
| Other | Other reason |
⚠️ "The employer has terminated the employee" is sent as "Reason attributable to the employee". If the termination was for financial or production-related reasons, correct the end reason in Netvisor.
Absence data
The Netvisor integration doesn't support absence. Absence is not sent between Huma and Netvisor.
Salary data
The Netvisor integration doesn't support salary. Salary is not sent between Huma and Netvisor.
Change integration settings
- Go to the Netvisor integration in Huma.
- Click ··· in the top-right corner.
- Select an option:
- "Edit connection settings" to change the setting or the User ID, Key and Business ID.
- "Edit connection details" to change the name or who is included in the connection.
The setting is explained in Step 3: Choose what to sync.
Disconnect or remove
- Disconnect: Stops syncing but keeps your setup.
- Remove: Stops syncing and deletes all saved setup.
Error log
Where to find the error log
- Go to the Netvisor integration in Huma.
- Open the "Error log" tab.
Errors are grouped by day. Each entry shows a message, the time, which employee it concerns and a level:
| Level | What it means |
|---|---|
| 🔴 Error | Something was not sent to Netvisor. You need to take action. |
| 🟡 Warning | Something needs your attention. |
| 🔵 Info | For your information. No action needed. |
Integration status
| Status on the integration page | What to do |
|---|---|
| This integration is configured but not active | Click "Sync users" to activate it. |
| Connected and active | Everything works. |
Common errors
| Problem | What it means | How to fix it |
|---|---|---|
| User must have a position with contract start date to create employee in netvisor | The employee has no position with a start date in Huma. | Add a position with a start date in Huma, and click "Sync users". |
| Netvisor does not allow overlapping employment periods | The position overlaps another employment period in Netvisor. | Adjust the dates so the periods don't overlap. |
| No matching position found | No employment period in Netvisor has the start date and job title the position had before the change. | Compare the period in Netvisor with the position in Huma, and make the change manually in Netvisor. |
| Email mismatch when trying to update | The email address in Netvisor no longer matches the employee in Huma. | Make sure the email address is the same in both systems, and click "Sync users". |
| Error when updating an employee created from Huma | TyEL is set to "No handling" in Netvisor. | Select a suitable employment pension insurance in Netvisor. |
| The connection to Netvisor stops working | The API identifier no longer works, or the API resource access rights are missing. | Check the API identifier and access rights in Netvisor, and update them in "Edit connection settings". |
FAQ
Why don't changes I make in Netvisor show up in Huma?
Changes only go automatically from Huma to Netvisor. To bring changes from Netvisor into Huma, click "Sync users".
Why isn't a new employee in Huma created in Netvisor?
Employees are never created automatically. Click "Sync users" and choose to create the employee in Netvisor. The employee needs a Finnish personal identity code and a position with a start date and a job title.
Can employment periods overlap?
No. Netvisor doesn't allow overlapping employment periods. Positions with overlapping dates are not sent.
What happens in Netvisor when I delete a position in Huma?
Huma deletes the employment period with the same start date and job title. If none is found, nothing is deleted.
Can I sync absence or salary with Netvisor?
No. The Netvisor integration supports employee data and positions only.
Can historical positions be transferred?
No. Only positions created, updated or deleted after the integration is active are sent.
Can I have more than one Netvisor connection?
Yes. You can for example set up one connection per company. See Multiple connections.