Xledger integration

 

Table of Contents

Set up integration

• Multiple connections
• Step 1: Get an API token from Xledger
• Step 2: Connect Huma to Xledger
• Step 3: Activate the integration. Synchronize users and choose how to handle conflicts or missing values
• Step 4: Your connection between Huma and Xledger is active

Active integration

• How to sync users
• Deactivated or deleted users
• Supported fields - Employee fields
• Supported fields - Position fields
• Adding absence or salary sync to an existing connection
• Supported fields - Absence
• Supported fields - Salary

General questions

• FAQ: Xledger and Huma position integration
• FAQ: Xledger and Huma absence integration
• FAQ: Xledger and Huma salary integration

---

 

 

Xledger

Xledger integration makes HR and payroll more efficient and reliable by keeping your people data consistent across Huma and Xledger.

• To configure an integration in Huma, you must have a "System role with full access permissions for Organization".
• If you are unsure which roles are required on the Xledger side to complete the integration setup, please contact Xledger support for guidance.

 

 

Multiple connections

⛓️‍💥 If you need to configure multiple integration instances, follow the setup guidance provided here.

 

 

1. Get an API token from Xledger

To create a token in Xledger, you must be an "Administrator".

1. Log in as "Administrator"
2. Go to Administration > System Access > GraphQL > API tokens
3. Generate a new access token and give the following access
4. Click "Generate token"
5. Copy token to clipboard

 

 

Scope	Access (read/write)
Human Resources	Employee: read/write Absence: read/write (absence)
Common	Address: read Contact: read/write Company: read Country: read Object Value: read Object Kind: read (absence) Subledger: read/write Supplier: read/write System Value: read
General ledger	Bank: read
Payroll	PayrollRate: read/write (salary)
Employee	EmployeePosition: read (salary)

 

💡 Absence and Salary scopes are only needed if you plan to use absence sync and/or salary sync. If you only need user and position sync, you can leave these out. See "Supported fields - Absence" and "Supported fields - Salary" below for exactly which scopes each feature needs.

 

 

2. Connect Huma to Xledger

2a. To set up the integration in Huma, you must be a "System administrator with full access to Organization > Organization-wide settings".

1. Login to your Huma account as Administrator
2. Go to 'Integrations' in the main menu
3. Open 'Xledger'
   • Read through the documentation in the "Overview" and "Details" tabs.
4. Click 'Set up' in the upper right corner
5. Paste the created Xledger API token key and check the box to verify you have the proper authority.

 

 

2b. Configure integrations settings

On the "Settings" step, choose what should sync between Huma and Xledger. You can turn each of these on or off, and change them later at any time.

• Users: Create in Xledger when added in Huma
• Positions: Create, update and delete
  • ⚠️ Positions will only be sent from Huma to Xledger, and not from Xledger to Huma.
  • ⚠️ Only positions created or updated after the integration is activated will be transferred to Xledger.
• Salary: Create, update and delete in Xledger when updated in Huma
  • ⚠️ Your Xledger API key must be configured with specific permissions before salary can be transferred. 🔗 Read more in our knowledge base.
  • 💡 Annual and hourly salaries are sent to Xledger automatically. Monthly and weekly salaries have no equivalent in Xledger and must be registered there manually.
  • 💡 The salary is attached to the Xledger position covering its entire period. If no matching position is found, it is sent without one.
  • ⚠️ Salary data will only be sent from Huma to Xledger, and not from Xledger to Huma.
  • ⚠️ Only salaries created or updated after the integration is activated will be transferred to Xledger.
• Absence: Create, update and delete in Xledger when updated in Huma
  • ⚠️ Your Xledger API key must be configured with specific permissions before absence can be transferred. 🔗 Read more in our knowledge base.
  • ⚠️ Absence arrives in Xledger unapproved and must be approved there.
  • ⚠️ Xledger absence types that only allow full days reject graded absence, such as partial sick leave.
  • 💡 Map absence types in the next step.

 

💡 You can always edit these settings later on. 

1. Click "Save" to continue.

 

 

 

3. Activate the integration, synchronize users, and choose how to handle any conflicts or missing values

After you click "Save", you'll be taken to the connection overview page. To activate the integration, you need to "Sync users."

1. Click "Sync users."

• Matching users: Users found in both Huma and Xledger (same email address in both systems).
  • Click "View users" to see which supporting fields don't match or are missing.
  • Resolve any non-matching or missing values.
  • Click "Next."
• Non-matching users: Users who exist in only one of the systems.
  • Choose whether to create all users / selected users / do not create.
  • Choose how users should be created:
    • Huma → Xledger: Add users to Huma.
    • Huma → Xledger: Add users to Xledger.

          2.  Click "Sync users." You'll receive an email with the results.

 

💡Note - Users who have not completed the "Required fields" will not be synchronized.

 

 

4. Your connection between Huma and Xledger is active

• Any changes made to supported fields in Huma (listed below) will be automatically updated in Xledger in real-time.
• Please be aware that you need to sync users to get the latest changes from Xledger. Changes made in Xledger will not be automatically updated in Huma.

 

 

 

Active integration - How to sync users

Use "synchronize users" when you have updated supported fields in Xledger, or when you have created new users in Huma.

If you need to do a manual sync between Xledger and Huma:

• Go to the integration page for Xledger in Huma
• Click "Synchronize users" and follow the steps. ⛓️‍💥 Read more about the steps here.

 

💡 Note

• Please be aware that you need to sync users to get the latest changes from Xledger. Changes made in Xledger will not be automatically updated in Huma.
• When a transfer of data from Huma to Xledger is triggered, the name of the user who created the API token in Xledger will remain in the history of the change.
• If an error occurs during synchronization, you can see detailed information in the "Error log" on the Xledger integration page in Huma.

 

 

Deactivated or deleted users

When a user is deactivated in Huma...

• the user will not be deactivated in Xledger.
• the user will be locked for updates.

 

When a user is deleted in Huma...

• the user will not be deleted in Xledger.
• the manual sync will ask you to create this user in Xledger.
• the user cannot be synced if there have been changes to their record in Xledger.

 

 

Supported fields - Employee fields that are synchronized

Changes made to supported fields in Huma (listed below) are automatically updated in Xledger in real time. Changes made in Xledger, however, must be synchronized manually in Huma.

Huma field	Xledger Field
Email address*	employee.contact.email  employee.subledger.email — must be unique in Huma
Employment ID	employee.code — must be unique in Huma
Given name	employee.contact.firstName employee.subledger.description
Family name	employee.contact.lastName employee.subledger.description
Phone number	employee.contact.phone employee.subledger.phone — must be unique in Huma
Date of birth	employee.contact.birthday
Bank account number	employee.subledger.bankAccount - the integration will update this field in Xledger  employee.subledger.company.country  - the integration can't update this field's value in Xledger with the value in Huma
Address	contact.address.streetAddress/zipCode/place/country.code - -- the integration can't unset this field's value in Xledger when the value is unset in Huma  subledger.address.streetAddress/zipCode/place/country.code
Gender	employee.contact.gender
Identification	employee.contact.socialSec — only Norwegian national identity numbers are supported in Xledger

 

💡Note: If you receive "Error parsing query: Unterminated string," it may indicate that one of the supported fields contains a special character that cannot be interpreted.

 

 

Supported fields - Position fields that are synchronized

📄 Learn more about how employee data synchronization works in integrations in general.

⚠️ Note that activating the integration does not transfer historical position data to Xledger. Only positions that are created or updated in Huma after the integration is activated will be synchronized.

💡Position data is synchronized only from Huma to Xledger, not from Xledger to Huma.

Huma field	Xledger Field
Job title	employee.contact.jobTitle
Contract start date	employee.employmentFrom — uses the contract start date of the employee's earliest position in Huma
Probation end date	employee.trialTo — uses the value from the employee's current, upcoming or latest primary position
Termination notice date	employee.noticeDate
Contract end date	employee.employmentTo — uses the contract end date of the employee's latest position in Huma

 

 

Adding absence or salary sync to an existing connection

If you're setting up a new Xledger connection, you can enable Salary and/or Absence sync directly during setup (step 2b) — you don't need the steps below.

If you already have an active Xledger connection and want to turn on absence and/or salary sync, your existing API token does not have the scopes required for this.

⚠️ You cannot add scopes to an existing Xledger API token. You must generate a new token that includes the full scope table from  ⛓️‍💥 "Step 1: Get an API token from Xledger" above, both your original scopes and the new ones for absence and/or salary.

1. Generate a new API token in Xledger with the full set of required scopes
2. In Huma, go to the Xledger integration page, click ··· and select "Edit connection settings"
3. Paste in the new API token to replace the old one
4. Continue with the setup steps for absence and/or salary sync described below

 

Additional scopes needed for Salary and Absence sync

Feature	Scope	Access (read/write)
Absence sync	Human Resources: Absence	Read/write
Absence sync	Common: Object Kind	Read
Salary sync	Payroll: PayrollRate	Read/write
Salary sync	Employee: EmployeePosition	Read

 

 

Supported fields - Absence

Absence approved in Huma can sync automatically to Xledger. Absence sync flows one way only: from Huma to Xledger.

💡 Absence sync requires the Human Resources → Absence and Common → Object Kind scopes — see the full scope table under "Step 1: Get an API token from Xledger" above.

💡If you see the error "This token does not have permission to read and write for type Absence," you need a new token with these scopes. See ⛓️‍💥 "Adding absence or salary sync to an existing connection" above.

 

Supported fields — absence fields that are synced

Huma field	Xledger field
Absence type* (REQUIRED)	Xledger absence code (via your type mapping)
Time period* (REQUIRED)	Start date / end date
Grade* (REQUIRED)	Percentage
Note	Comment

 

⚠️ Absence synced from Huma is not automatically approved in Xledger. It still needs to be approved there separately.

💡 Changes to absence in Huma will lead to changes in the absence created in Xledger. If the absence is deleted in Huma, it is also deleted in Xledger.

💡 Overlapping absences are supported.

⚠️ Percentage-based absence: Some Huma absence types use a percentage (e.g. partial sick leave, graded parental leave). Some Xledger absence codes only support whole-day registration — typically self-certified sick leave — and will reject a percentage value. Only map percentage-based absence types to Xledger codes that accept a percentage. Otherwise the sync fails and the absence must be registered manually in Xledger. Check with your Xledger admin which codes support this.

 

 

Supported fields - Salary

Salary changes in Huma sync automatically to Xledger — new salaries, edits/corrections, and deletions. Salary sync flows one way only: from Huma to Xledger.

⚠️ Salary sync must be turned on separately for each Xledger connection. Go to Settings in that integration and switch on salary sync. Only salaries added or changed after it's enabled are sent — nothing is sent retroactively.

💡 Salary sync requires the Payroll → PayrollRate and Employee → EmployeePosition scopes — see the full scope table under ⛓️‍💥 "Step 1: Get an API token from Xledger" above.

💡 If your existing token doesn't have these scopes, see ⛓️‍💥 "Adding absence or salary sync to an existing connection" above.

 

Supported fields — salary fields that are synced

Huma field	Xledger field
Start date* (REQUIRED)	PayrollRate start date
Salary amount* (REQUIRED)	Årslønn (yearly and monthly, converted) or Timelønn (hourly) — depending on period unit

 

Which salary types sync

Huma salary type	Xledger name	Synced?
Yearly / annual	Årslønn	Yes
Hourly	Timelønn	Yes
Monthly	—	No
Weekly	—	No

 

💡 Xledger has no monthly or weekly rate type. Huma won't write anything incorrect — monthly and weekly salaries must be entered manually in Xledger. A start date is always required for a salary to sync.

How Huma finds the right record in Xledger
No hidden link is stored between the systems. Huma matches a salary based on employee, salary type, position, start date, and amount. If exactly one Xledger record matches, it's updated or removed automatically.

⚠️ Huma never guesses. If two salaries look identical, or a record was edited directly in Xledger and no longer matches, Huma stops and asks you to resolve it manually — it won't silently overwrite or delete the wrong record.

Which position the salary is attached to

• No position covers the salary period → registered on the employee directly, no position attached
• One position covers it → the salary is attached to that position
• Several positions cover it → Huma uses the one marked main position in Xledger. If none or several are marked main, you'll be asked to set a single main position in Xledger

 

 

FAQ: Huma to Xledger position integration

Where is the "Job Title" field updated in Xledger?

You can enter job titles in two places in Xledger, and customers use Xledger in different ways, not always utilizing the job title field Huma actually support. Today, job titles are synced from Huma to the field in Xledger called employee.contact.jobTitle. You can find this field in Xledger by navigating to: XRM > Contact > Select Employee > View the "Job Title" field.

 

Does the integration update position data?

Yes. When supported position fields are changed in Huma, the updates are automatically sent to Xledger. This includes changes such as updates to contract dates and title.

 

In which direction is data synchronized?

Position data is synchronized in one direction only: Huma → Xledger. Changes made directly in Xledger will not be sent back to Huma.

 

When is position data sent to Xledger? Position data is sent to Xledger when:

• A new position is created in Huma
• An existing position is updated in Huma
• A user with a position in Huma is created in Xledger through a manual sync
• The change happens after the integration has been activated

 

Can historical positions be transferred?

No. The integration does not automatically transfer historical position data that existed before the integration was activated.

 

Why aren't all position fields synchronized?

Not all position fields can be synchronized between Huma and Xledger because the two systems store and structure employment information differently. Some fields exist only in one system, or their data structures do not match directly. In other cases, limitations in the Xledger API or in how data is handled in Huma prevent a full one-to-one mapping between the systems.

 

 

FAQ: Xledger and Huma absence integration

Does absence sync work in both directions?

No. Absence flows one way only: from Huma to Xledger.

 

Is absence approved in Xledger automatically?

No. Absence synced from Huma still needs to be approved in Xledger.

 

What if I use a percentage-based absence type?

Only map percentage-based absence types to Xledger codes that support percentage registration. If the code only supports whole-day entries, the sync will fail and the absence must be registered manually.

 

I already have a Xledger connection — how do I turn on absence sync?

You need a new API token that includes the full scope table (including the Absence scope). See "Adding absence or salary sync to an existing connection" above.

 

 

FAQ: Xledger and Huma salary integration

Does salary sync work in both directions?

No. Salary flows one way only: from Huma to Xledger.

 

Which salary types are synced?

Yearly and hourly salary. Monthly and weekly salary are not synced and must be entered manually in Xledger.

 

What happens if Huma can't find a matching salary record in Xledger?

Huma won't guess. If there's no single clear match — or the record was edited directly in Xledger — the sync stops and you'll need to resolve it manually.

 

I already have a Xledger connection — how do I turn on salary sync?

You need a new API token that includes the full scope table (including PayrollRate and EmployeePosition). See ⛓️‍💥 "Adding absence or salary sync to an existing connection" above.