Table of contents
- Roles and access
- How data flows
- Before you start
- Set up the integration
- When the integration is active
- Supported fields
- Error log and troubleshooting
- FAQ
- Related articles
Roles and access
| Role in Huma | System role with full access to Organization |
| Role in Finago | Access to settings, so you can generate an API key |
💡 Not sure which roles you need in Finago? Contact your Finago administrator or Finago support.
How data flows
| Data | Huma → Finago | Finago → Huma | When |
|---|---|---|---|
| Profile fields | ✅ Automatic | ✅ Manual only | Changes in Huma are sent in real time. Changes in Finago are brought in when you click "Sync users". |
| New employees | ✅ Manual only | ✅ Manual only | When you click "Sync users" |
| Positions (employments) | ✅ Automatic, if turned on | ❌ | When a position is created or updated in Huma |
| Absence | ❌ | ❌ | Not supported |
| Salary | ❌ | ❌ | Not supported |
⚠️ Historical data is not transferred. Only positions created or updated after the integration is active are sent to Finago.
Before you start
- You have a system role with full access to Organization in Huma.
- You, or a colleague, can log in to Finago and generate an API key.
- Employees who exist in both systems have the same email address in Huma and Finago. Huma matches employees by email only.
- You know if your company in Finago is Norwegian or Swedish. Huma uses the company's country to choose which contract types and end reasons to send.
Set up the integration
Step 1: Generate an API key in Finago
- Log in to Finago.
- Open "Settings" in the main menu.
- Go to the "Misc" tab.
- Generate a new API key at the bottom of the page.
- Copy the API key.
Step 2: Connect Huma to Finago
- In Huma, go to "Integrations" and select "Finago".
- 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 API key from Finago.
- Confirm that you have the authority to accept the terms on behalf of your organization.
- Click "Continue".
🔗 Need more than one connection, for example one per company? See Multiple connections.
Step 3: Choose what to sync
Finago has one setting. You can change it later.
| Setting | When on | When off |
|---|---|---|
| Positions: Create, update and delete | A new position in Huma creates a new employment in Finago. Changes to a position in Huma update the matching employment in Finago. | No position data is sent to Finago. |
⚠️ Positions deleted in Huma are not deleted in Finago. The integration can't delete an employment in Finago, even though the setting mentions delete.
💡 We recommend turning on positions before you start managing positions in Huma.
💡 New employees in Huma are not created in Finago automatically. To create them in Finago, click "Sync users".
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 complete this step.
- 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 Finago, update Finago 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: Finago → Huma, or Huma → Finago.
- Click "Sync users".
The status changes to "Connected and active". You get an email with the result.
💡 Note
Before you sync, decide which system has the most up-to-date information. The choices you make here overwrite data.
⚠️ Users missing required fields are not synced until the values are filled in.
When the integration is active
What happens automatically
- Changes to supported profile fields in Huma are sent to Finago in real time.
- If positions are turned on, new and updated positions in Huma are sent to Finago.
When you need to sync manually
Click "Sync users" when:
- You have changed a supported field in Finago and want it in Huma.
- You have added employees in Finago that should be created in Huma.
- You have added employees in Huma that should be created in Finago.
How positions are matched
- Finago allows overlapping employments. Every new position in Huma creates a new employment in Finago.
- When you update a position, Huma finds the employment in Finago with the same start date as the position had before the change.
- If no employment in Finago has that start date, the update is not sent, and you see an error in the error log.
- If you add an end date without an end reason, Finago gets the end reason "Employee resigned".
💡 When you edit the first position that Huma created automatically when Employee history was launched, make sure the start date matches the employment in Finago. Or make your changes, save them, and click "Create new position".
When an employee leaves
Deactivated in Huma:
- The employee is not deactivated in Finago.
- The employee is locked from updates from the integration.
Deleted in Huma:
- The employee is not deleted in Finago.
- The next time you click "Sync users", you are offered to create the employee in Huma again.
💡 To register that an employment ends in Finago, set an end date and end reason on the position in Huma.
Change settings or the API key
- Go to the Finago integration in Huma.
- Click ··· in the top-right corner.
- Select an option:
- "Edit connection settings" to change the setting or paste a new API key.
- "Edit connection details" to change the name or who is included in the connection.
Disconnect or remove
- Disconnect: Stops syncing but keeps your setup.
- Remove: Stops syncing and deletes all saved setup.
Supported fields
Profile fields
Changes in Huma are sent automatically. Changes in Finago are brought in with "Sync users".
| Huma field | Finago field | Required | Notes |
|---|---|---|---|
| Email address | ✅ | Used to match employees. Must be unique in Huma and Finago. When you change the email in Huma, it is updated in Finago. API name: email |
|
| Given name | First name | ✅ | API name: firstname |
| Family name | Last name | ✅ | API name: lastname |
| Phone number | Phone | Must be unique in Huma. API name: telefon |
|
| Address | Address, Postal code, City, Country | Address lines are sent as one line, separated by commas. API names: postaddress, zipcode, city, countryCode |
|
| Identifications | Personal number and International ID | Finago has room for two identifications. A Norwegian national identity number goes to the personal number. One other identification goes to the international ID. Any other identifications are not sent. The personal number is cleared in Finago when you remove it in Huma. The international ID can't be cleared by the integration. You see a warning in the error log, and must remove it manually in Finago. API names: personnr, internationalID.ID, internationalID.countryCode, internationalID.type |
|
| Bank account | Account number, Clearing number, BIC | Norwegian account: account number. Swedish account: clearing number and account number. International account: IBAN and BIC. The account must be valid for its format. API names: account, clearingno, bic |
Position fields (Huma → Finago)
Sent only when "Positions: Create, update and delete" is turned on.
| Huma field | Finago field | Required | Notes |
|---|---|---|---|
| Contract start date | Start date | Used to match updates to the right employment. Can't be cleared in Finago. API name: startdate |
|
| Contract end date | End date | Cleared in Finago when you remove it in Huma. API name: enddate |
|
| Employment percentage | Employment rate | Can't be cleared in Finago. API name: employment_rate |
|
| Contract type | Employment form | See the table below. Can't be cleared in Finago. API name: employment_form |
|
| End reason | End date reason | See the table below. If there is an end date but no end reason, "Employee resigned" is sent. API name: enddate_reason |
Contract types
| Contract type in Huma | Norwegian company in Finago | Swedish company in Finago |
|---|---|---|
| Permanent | Fast | Tillsvidare |
| Temporary | Midlertidig | Tidsbegränsad |
| Seasonal | Midlertidig | Behovsanställd |
| Casual | Midlertidig ansatt som tilkallingsvikar | Behovsanställd |
| Trainee | Midlertidig | Tidsbegränsad |
| Job training program | Midlertidig | Tidsbegränsad |
End reasons
| End reason in Huma | Norwegian company in Finago | Swedish company in Finago |
|---|---|---|
| The employee has resigned | Arbeidstaker har sagt opp selv | Egen begäran |
| The employer has terminated the employee | Arbeidsgiver har sagt opp arbeidstaker | Uppsagd arbetsbrist |
| The contract, engagement, or temporary position has expired | Kontrakt, engasjement eller vikariat er utløpt | Tidsbegränsad anställning |
| Change in organizational structure or internal job transfer | Endring i organisasjonsstruktur eller byttet jobb internt | Annan orsak |
| Changed payroll system or accountant | Byttet lønnssystem eller regnskapsfører | Annan orsak |
| Other | Arbeidsforholdet skulle aldri vært rapportert | Annan orsak |
⚠️ For Norwegian companies, the end reason "Other" is sent as "Arbeidsforholdet skulle aldri vært rapportert" (the employment should never have been reported). Choose a more specific end reason when you can.
Error log and troubleshooting
Where to find the error log
- Go to the Finago 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 Finago. 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 |
|---|---|---|
| We couldn't find a matching position … | No employment in Finago has the same start date as the position you updated in Huma. | Check that the employment exists in Finago with the same start date. Correct the start date in one of the systems, or create a new position in Huma. |
| An identification could not be removed from Finago | The international ID can't be cleared by the integration. | Remove the international ID manually in Finago. |
| Email mismatch when trying to update | The email address in Finago no longer matches the employee in Huma. | Make sure the email address is the same in both systems, and click "Sync users". |
| The connection to Finago stops working | The API key no longer works, for example because it was deleted in Finago. | Generate a new API key in Finago and paste it in "Edit connection settings". |
FAQ
Why don't changes I make in Finago show up in Huma?
Changes only go automatically from Huma to Finago. To bring changes from Finago into Huma, click "Sync users".
Why isn't a new employee in Huma created in Finago?
Finago has no setting for creating employees automatically. Click "Sync users" and choose to create the employee in Finago.
What happens in Finago when I delete a position in Huma?
Nothing. The integration can't delete employments in Finago. Remove the employment manually in Finago if needed.
Why do I get an error when I update a position?
Huma matches the position to an employment in Finago by start date. If no employment has the same start date, the update fails. Check the start date in both systems.
Can I sync absence or salary with Finago?
No. The Finago integration supports profile fields and positions only.
Can historical positions be transferred?
No. Only positions created or updated after the integration is active are sent. To send an older position, update it in Huma after the integration is turned on.
Related articles