Skip to content
  • There are no suggestions because the search field is empty.

Xledger integration

Connect Huma to Xledger to keep employee profiles, employment details, absence and salary in sync

 

Table of contents

 


 

Introduction

The Xledger integration keeps employee information in Huma and Xledger in sync. You manage employees, positions, absence and salary in Huma, and Huma sends the changes to Xledger.

This is what the integration supports, and how the data flows:

Data Huma → Xledger Xledger → Huma When
Employee data ✅ Automatic ✅ Manual only Huma changes are sent in real time. Xledger changes are brought in when you click «Sync users».
New employees ✅ Automatic, if turned on ✅ Manual only When an employee is added in Huma, or when you click «Sync users»
Positions (employment details) ✅ Automatic, if turned on ❌ When a position is created, changed or deleted in Huma
Absence ✅ Automatic, if turned on ❌ When absence is approved in Huma and has an end date
Salary ✅ Automatic, if turned on (annual and hourly) ❌ When salary is created, changed or deleted in Huma

 

⚠️ Historical data is not transferred. Only positions, absence and salary created or changed after you turn on each setting are sent to Xledger.

💡 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 token in Xledger «Administrator» in Xledger
API token scopes See the scope table in Step 1. Absence and salary need extra scopes.

 

💡 Not sure which roles you need in Xledger? Contact Xledger support.

💡 When Huma sends data to Xledger, the name of the user who created the API token is shown in the change history in Xledger.

 

 

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 Xledger as «Administrator» and create an API token.
  • Employees who exist in both systems have the same email address in Huma and Xledger. Huma matches employees by email only.
  • If you want to sync absence, absence must be set up in Huma first (absence types or work schedules).
  • If you want to sync salary, decide which position is the main position in Xledger for employees with several positions.

 

 

Step 1: Create an API token in Xledger

  1. Log in to Xledger as «Administrator».
  2. Go to «Administration» › «System Access» › «GraphQL» › «API tokens».
  3. Create a new access token and give it the scopes in the table below.
  4. Click «Generate token».
  5. Copy the token and keep it somewhere safe.

Screenshot 2026-08-31 at 11.53.16

Scopes for the API token

Scope Access Needed for
Human Resources: Employee Read/write All connections
Common: Address, Company, Country, Object Value, System Value Read All connections
Common: Contact, Subledger, Supplier Read/write All connections
General ledger: Bank Read All connections
Human Resources: Absence Read/write Absence sync
Common: Object Kind Read Absence sync
Payroll: PayrollRate Read/write Salary sync
Employee: EmployeePosition Read Salary sync

 

💡 Only add the absence and salary scopes if you plan to use those features. Scopes can be changed on an existing token, but this often causes errors in the connection to Huma. If you need more scopes later, we recommend creating a new token. See Turn on absence or salary sync later.

 

Step 2: Connect Huma to Xledger

  1. In Huma, go to «Integrations» and select «Xledger».
  2. Read the «Overview» and «Details» tabs.
  3. Click «Set up» in the top right corner.
  4. Give the connection a name.
  5. Choose who should be part of this connection: everyone, or a specific team, location or company.
  6. Click «Continue».
  7. Paste the API token from Xledger.
  8. Confirm that you have the legal authority to accept the terms on behalf of your organization.
  9. Click «Continue».

 

Step 3: Choose what to sync

You can change the settings later. See Change integration settings.

Setting When it's on When it's off
Users: Create in Xledger when added in Huma New employees in Huma are created in Xledger automatically. New employees are only created in Xledger when you click «Sync users».
Positions: Create, update and delete Position changes in Huma are sent to Xledger. Positions are not sent.
Salary: Create, update and delete in Xledger when updated in Huma Annual and hourly salaries in Huma are sent to Xledger. Requires the salary scopes. Salary is not sent.
Absence: Create, update and delete in Xledger when updated in Huma Approved absence is sent to Xledger. Requires the absence scopes. Absence is not sent.

 

💡 Entering historical positions? Turn position sync off while you enter them. Historical positions aren't meant for the payroll system and can cause errors. Turn it on before you create positions that start today or in the future.

 

Step 4: Map absence types

Do this step if you turned on absence.

  1. Go through each absence type in Huma.
  2. Select the matching absence code in Xledger.
  3. Leave any type you don't want to send unmapped.
  4. Click «Save».

⚠️ Some Xledger absence codes only allow whole days, typically self-certified sick leave. They reject graded absence, such as partial sick leave or graded parental leave. Only map graded absence types to codes that accept a percentage. Check with your Xledger administrator which codes support this.

 

Step 5: Sync users to activate the integration

After setup, the integration page says «This integration has been set up, but is not active». Nothing is sent until you sync users. See Sync employees.

 

 

Sync employees

«Sync users» compares the employees in Huma and Xledger. You decide what to update and which employees to create. The first sync also activates the integration.

How to sync users

  1. Go to the Xledger integration in Huma and click «Sync users».
  2. Matching users are employees with the same email in both systems.
    • Click «View users» to see fields with different or missing values.
    • For each case, choose to update Huma with the value from Xledger, update Xledger with the value from Huma, or leave it.
    • Click «Next».
  3. Non-matching users are employees that exist in only one system.
    • Choose whether to create all of them, only the ones you select, or none.
    • Choose the direction: Xledger → Huma, or Huma → Xledger.
  4. Click «Sync users».

The status changes to «Connected and active». You'll get an email with the result.

💡 Before you sync, decide which system has the most up-to-date information. Your choices here overwrite data.

⚠️ Users missing required fields, such as the country on an identification, are not synced until the missing values are added.

 

When you need to sync users

Changes in Huma are sent to Xledger automatically. Click «Sync users» when:

  • You have just set up the integration and want to activate it.
  • You have changed a supported field in Xledger and want it in Huma.
  • You have added employees in Xledger that should be created in Huma.
  • You have added employees in Huma and «Users: Create in Xledger when added in Huma» is off.

 

When an employee leaves

Deactivated in Huma:

  • The employee is not deactivated in Xledger.
  • The employee is locked for updates from the integration.

Deleted in Huma:

  • The employee is not deleted in Xledger.
  • The next «Sync users» suggests creating them in Huma again.
  • The employee can't be synced if they were changed in Xledger after they were deleted in Huma.

💡 To register the end of employment in Xledger, set the contract end date on the employee's last position in Huma. See Position data.

 

 

Employee data

Changes in Huma are sent automatically. Changes in Xledger are brought in with «Sync users».

Huma field Field in Xledger Required Notes
Email address Email (contact and subledger) ✅ Used to match employees. Must be unique in Huma.
API names: employee.contact.email, employee.subledger.email
Employee ID Code   Must be unique in Huma.
API name: employee.code
First name First name (contact), Description (subledger)   The subledger description is the full name.
API names: employee.contact.firstName, employee.subledger.description
Last name Last name (contact), Description (subledger)   API names: employee.contact.lastName, employee.subledger.description
Phone number Phone (contact and subledger)   Must be unique in Huma.
API names: employee.contact.phone, employee.subledger.phone
Date of birth Birthday   API name: employee.contact.birthday
Identifications Social security number   Only Norwegian national identity numbers.
API name: employee.contact.socialSec
Bank account Bank account (subledger)   The integration updates the account number. It can't update the company country on the subledger.
API names: employee.subledger.bankAccount, employee.subledger.company.country
Address Address (contact and subledger)   The integration can't remove the contact address in Xledger when it's removed in Huma.
API names: contact.address.*, subledger.address.* (streetAddress, zipCode, place, country.code)
Gender Gender   API name: employee.contact.gender

 

 

Position data

Positions go one way: from Huma to Xledger. They are sent as employment details on the employee when «Positions: Create, update and delete» is turned on.

Huma field Field in Xledger Required Notes
Job title Job Title (XRM › Contact)   API name: employee.contact.jobTitle
Contract start date Employment from   Uses the contract start date of the employee's first position in Huma.
API name: employee.employmentFrom
Probation end date Trial to   Uses the value from the employee's current, upcoming or latest primary position.
API name: employee.trialTo
Termination notice date Notice date   API name: employee.noticeDate
Contract end date Employment to   Uses the contract end date of the employee's last position in Huma.
API name: employee.employmentTo

 

💡 Xledger has two places for job titles. Huma updates the «Job Title» field on the contact. You find it under XRM › Contact › select the employee.

 

 

Absence data

Absence goes one way: from Huma to Xledger. Approved absence with an end date is sent on the absence code you mapped in step 4, if «Absence: Create, update and delete in Xledger when updated in Huma» is turned on.

Huma field Field in Xledger Required Notes
Absence type Absence code ✅ Set up in step 4.
API name: absence.absenceCode
Time period From date / To date ✅ API names: absence.fromDate, absence.toDate
Percentage Leave % ✅ Some absence codes only allow whole days.
API name: absence.leavePercent
Note Text   API name: absence.text

 

⚠️ Absence from Huma arrives in Xledger unapproved and must be approved there.

💡 Overlapping absences are supported.

 

When Xledger rejects absence

If Xledger rejects an absence, for example because the absence code only allows whole days, the error is logged. Register the absence manually in Xledger, or map the absence type to a code that accepts a percentage.

 

 

Salary data

Salary goes one way: from Huma to Xledger. It is sent when salary is created, changed or deleted in Huma, if «Salary: Create, update and delete in Xledger when updated in Huma» is turned on.

Huma field Field in Xledger Required Notes
From date Date from ✅ A salary without a start date is not sent.
API name: payrollRate.dateFrom
To date Date to   API name: payrollRate.dateTo
Interval Rate element: Årslønn / Timelønn   Annual → Årslønn. Hourly → Timelønn. Monthly and weekly are not sent.
API name: payrollRate.rateElement
Amount Rate ✅ Sent as it is, without conversion.
API name: payrollRate.rate

 

💡 Xledger has no monthly or weekly rate type. Huma doesn't convert these, so register monthly and weekly salaries manually in Xledger.

💡 To see the salary in Xledger, go to «Payroll/Expenses» › «Employees» › «Employees register», click the folder icon next to the employee and select «Individual rate».

Individual rate in Xledger

 

Which position the salary is attached to

  • No position covers the salary period: the salary is registered on the employee without a position.
  • One position covers it: the salary is attached to that position.
  • Several positions cover it: Huma uses the position marked as the main position in Xledger. If none or several are marked as main, the salary is not sent.

 

 

Change integration settings

  1. Go to the Xledger integration in Huma.
  2. Click ··· in the top right corner.
  3. Select an option:
    • «Edit connection settings» to change sync settings or paste a new API token.
    • «Edit connection details» to change the name or who is part of the connection.
    • «Map absence types» to change the absence mapping.

The settings are explained in Step 3: Choose what to sync.

 

Turn on absence or salary sync later

If you already have an active connection, your API token probably doesn't have the absence or salary scopes. Scopes can be changed on an existing token in Xledger, but this often causes errors in the connection to Huma. We therefore recommend creating a new token.

  1. Create a new API token in Xledger with the full scope table from Step 1, including the absence and/or salary scopes.
  2. In Huma, go to the Xledger integration, click ··· and select «Edit connection settings».
  3. Paste the new token.
  4. Turn on absence and/or salary sync, and map absence types if needed.

💡 If you see the error «This token does not have permission to read and write for type Absence», the token is missing the absence scopes.

 

Disconnect or remove

  • Disconnect: Stops syncing but keeps your configuration.
  • Remove: Stops syncing and deletes all stored configuration.

 

 

Error log

Where to find the error log

  1. Go to the Xledger integration in Huma.
  2. Open the «Error log» tab.

Errors are grouped by day. Each entry shows a message, the time, the employee it applies to and a level:

Level Meaning
🔴 Error Something was not sent to Xledger. You need to act.
🟡 Warning Something needs your attention.
🔵 Info For your information. No action needed.

 

Integration status

Status on the integration page What to do
This integration has been set up, but is not active Click «Sync users» to activate it.
Connected and active Everything is running.
Authorization failure: «Something is wrong with your connection to Xledger. Please reconnect and synchronize again.» The API token has expired or can't be used. Create a new API token in Xledger, paste it in «Edit connection settings», and click «Sync users».

 

Common errors

Error message (or part of it) What it means How to fix
Salary not synced to Xledger: Xledger has no monthly/weekly salary rate element… Only annual and hourly salaries are sent. Register the salary manually in Xledger.
Salary not synced to Xledger: the salary has no start date… A salary needs a start date to be sent. Add a start date in Huma, or register the salary manually in Xledger.
…several positions covering the salary period and none is marked as the main position Huma can't decide which position to attach the salary to. Mark one position as the main position in Xledger, then save the salary in Huma again.
…several positions covering the salary period marked as the main position More than one position is marked as main. Leave a single main position in Xledger, then save the salary in Huma again.
No single matching salary record in Xledger Huma matches salary by employee, rate element, position, start date and amount. Two identical records, or a record edited in Xledger, stops the sync. Correct the salary in Xledger manually.
This token does not have permission to read and write for type Absence The API token is missing the absence scopes. Create a new token with the full scope table. See Turn on absence or salary sync later.
Email mismatch when trying to update The email address in Xledger no longer matches the employee in Huma. Make the email address the same in both systems, then click «Sync users».
Error parsing query: Unterminated string A profile field contains a special character that can't be read. Retype the value in the field in Huma, then sync again.

 

 

FAQ

Why are changes I make in Xledger not showing in Huma?
Changes only go automatically from Huma to Xledger. To bring changes from Xledger into Huma, click «Sync users».

 

Where is the job title updated in Xledger?
Xledger has two places for job titles. Huma updates the «Job Title» field on the contact. You find it under XRM › Contact › select the employee.

 

Which salary types are sent?
Annual salary (Årslønn) and hourly salary (Timelønn). Monthly and weekly salaries are not sent and must be registered manually in Xledger.

 

Where do I find the salary in Xledger?
Go to «Payroll/Expenses» › «Employees» › «Employees register», click the folder icon next to the employee and select «Individual rate». The salary shows with rate element, from date, to date and rate.

 

Is absence from Huma approved automatically in Xledger?
No. Absence arrives unapproved and must be approved in Xledger.

 

I already have a connection. How do I turn on absence or salary sync?
We recommend creating a new API token with the full scope table. See Turn on absence or salary sync later.

 

Can I transfer historical absence, salary or positions?
No. Only data created or changed after the setting is turned on is sent.

 

Can I have more than one Xledger connection?
Yes. You can for example set up one connection per company. See Multiple connections.