Xledger integration

 

Table of contents

• Roles and access
• How data flows
• Before you start
• Set up the integration
• After 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 Xledger	«Administrator», to create an API token
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 for guidance.

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

 

 

How data flows

Data	Huma → Xledger	Xledger → Huma	When
Profile fields	✅ Automatic	✅ Manual only	Huma changes are sent in real time. Xledger changes are brought in when you click «Sync users».
New employees	✅ Automatic, if enabled	✅ Manual only	When an employee is added in Huma, or during «Sync users»
Employment details	✅ Automatic	❌	When a position is created, changed or deleted in Huma
Absence	✅ Automatic	❌	When absence is approved in Huma and has an end date
Salary	✅ Automatic (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.

 

 

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.

🔗 Getting started with Payroll & accounting integrations

 

 

Set up the integration

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.

 

 

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. You can't add scopes to an existing token later. 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».

 

🔗 Need more than one connection, for example one per company? See Multiple integrations.

 

 

 

Step 3: Choose what to sync

You can change all of these settings later.

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

You only do this step if absence sync is on.

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 complete this step.

1. 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.

 

💡 Note

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

⚠️ Users missing required fields are not synced until the missing values are added.

 

 

 

After the integration is active

 

What happens automatically

• Changes to supported profile fields in Huma are sent to Xledger in real time.
• Employment details, absence and salary are sent when they change in Huma, if those settings are on.

 

When you need to sync manually

Click «Sync users» when:

• 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.

 

Change settings or the API token

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.

 

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. You can't add scopes to an existing token in Xledger.

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.

 

 

Supported fields

Profile fields

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

 

Employment details (Huma → Xledger)

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

 

Absence (Huma → Xledger)

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.

 

Salary (Huma → Xledger)

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.

 

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.

 

 

Error log and troubleshooting

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.

 

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.

 

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.

 

 

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.

 

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?
You need 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.

 

 

Related articles

🔗 Getting started with Payroll & accounting integrations

🔗 How positions work in integrations

🔗 How absence works in integrations

🔗 How salary works in integrations

🔗 Multiple integrations