Xero
Overview
This article explains how to connect your Kompass account to Xero for automatic syncing of organizations, invoices, and optionally payments. Only admin users can set up and manage the Xero connection.
Prerequisites
- A Xero account with access to the organization you wish to connect
- Admin access to your Kompass account
- The Xero permission group on your user. If you do not see a Xero group in the Admin site, contact Kompass support to have Xero permissions added to your account.
Step 1: Create a Xero Configuration
- Navigate to the Admin site by adding /admin after your Kompass URL (e.g. your-server.kompassbms.com/admin).
- Under the Xero group, select Configurations. If the Xero group is not visible, your user is missing the required permissions; contact Kompass support to have them added.
- Click Add in the top right to create a new configuration.
- Select the Kompass org(s) that should be linked to this Xero connection.
- Click Save. Leave the Enable checkbox unticked for now; you will enable the sync in Step 5 once contacts have been reconciled.
Step 2: Authorize with Xero
- On the Configurations list page, select the configuration you just created using the tick-box.
- From the Action drop-down menu, select Authorize with Xero and click Go.
- You will be redirected to the Xero login page. Sign in with your Xero credentials.
- Xero will ask you to select which Xero organization to authorize. Choose the organization you wish to connect.
- Review the permissions Kompass is requesting and click Allow access.
- You will be redirected back to the Kompass Admin with a success message.
If you authorize multiple Xero organizations, Kompass will automatically select the first one. To use a different organization, disconnect and re-authorize with only the desired organization selected.
Step 3: Reconcile Existing Xero Contacts
Stop here if the Xero organization you just authorized already contains contacts. Once the Clients sync is on, Kompass creates a Xero contact when a project is accepted or an invoice is synced, if the client has no contact link yet. That creates a duplicate alongside the existing Xero contact. Reconcile contacts first, then enable the sync.
3a. Run the comparison
- On the Configurations list page, select your configuration using the tick-box.
- From the Action drop-down, select Compare contacts with Kompass clients (email CSV) and click Go. Kompass will fetch the customer contacts from the connected Xero organization, match them against your Kompass organizations by name, and email a download link for a zipped CSV report to the address on your user account. This typically takes a few minutes for organizations with a few hundred contacts.
Note: only Xero contacts marked as customers (that is, contacts that have at least one sales invoice in Xero) are included. A contact created in Xero but never invoiced won't appear in the report; link it by hand using option A below.
3b. Review the CSV
- Download and unzip the file, then open the CSV. Each row shows a Xero contact, a candidate Kompass organization match, and a confidence percentage. Rows with no match indicate either a Kompass client missing from Xero, or a Xero contact with no corresponding Kompass organization.
- Review the high and medium-confidence matches and confirm they are correct.
- Correct any false positives by editing the kompass_id column, or clearing it to leave the row unmatched.
3c. Create the links
For each confirmed match, Kompass needs a Xero Contact link so the sync uses the existing Xero contact instead of creating a new one. You can do this one at a time or all at once.
Option A: one at a time (Admin site)
In the Admin site under Xero, open Contacts, click Add, select the Kompass organization, and paste the corresponding Xero UUID from the CSV. Save.
Option B: all at once (Bruno)
Upload your reviewed CSV in a single request. The comparison file already uses the right column names, so you can upload it as it is once you've reviewed it.
| Setting | Value |
|---|---|
| Method | POST |
| URL | https://your-server.kompassbms.com/api/xero/contacts/import/ |
| Authentication | Authorization: Bearer kmps_pat_your_token_here, using a personal access token from a staff account with Write access. A staff account on its own does not authenticate the request. |
| Body | Multipart Form |
| Form field | file (type: File), pointing at your reviewed .csv |
Columns used by the import
| Column | Required | Description |
|---|---|---|
xero_uuid |
Yes | The Xero contact's ID (its UUID). |
kompass_id |
Yes | The ID of the Kompass organization to link it to. |
Any other columns in the file (xero_name , kompass_name , match_percentage , xero_match_count ) are ignored, so there's no need to delete them.
If you'd rather build the file from scratch, only these two columns are needed:
xero_uuid,kompass_id
Rules the import applies
- The file must be a
.csv, no larger than 5 MB and no more than 10,000 rows. Unzip the comparison file before uploading it. - Rows where both columns are blank are skipped.
- Rows with only one column filled in (unmatched contacts or organizations) are reported as errors. They don't stop the other rows from importing, but for a clean result, delete unmatched rows before uploading.
- The same
xero_uuidorkompass_idcan't appear twice in one file. Both rows are rejected. - A Kompass organization that is already linked to a different Xero contact is rejected. Remove the old link in the Admin site first if you need to change it.
- Re-uploading a row for a Xero contact that is already linked updates that link to the organization in the file.
- You can only link organizations belonging to orgs you have access to.
The response
Kompass replies with a summary: how many links were created, updated and skipped, plus a list of errors with the row number and reason for each. Fix the rows listed and upload them again.
Permission error? The import endpoint requires an authenticated staff account, so use a personal access token from a staff user with Write access. If Bruno returns a permission denied error, send your reviewed CSV to Kompass support and we'll import it for you.
3d. Check your work
The import response is the confirmation that the links were created: it reports how many were created, updated and skipped, and lists any rows that failed. The comparison only matches names and does not use the saved links, so running it again returns the same suggested matches and cannot show which links now exist.
You can run the comparison as often as you like. Each run produces a fresh CSV; the download link in the email expires after 7 days.
Step 4: Map Items, Accounts, and Tax Rates
Before you enable invoice sync, configure the mappings you need in the Admin site under Xero. Item and account mappings are optional; tax rate mappings are required for every VAT rate used on an invoice.
- Items: map Kompass departments/services to Xero items. You can also set a default item as a fallback.
- Accounts: map Kompass nominal accounts to Xero general ledger accounts.
- Tax rates: link Kompass VAT rates to Xero tax types.
Step 5: Configure Sync Settings and Enable
Once contact reconciliation is complete (or if the Xero organization was empty to start with), configure the sync and enable it:
- Open the configuration and set the Account default. This is the Xero account used for invoice, credit note and journal lines whose Kompass nominal account has no mapping, and it is required before the connection can be enabled.
- Under Sync modules, select the modules you wish to sync:
- Clients: syncs Kompass organizations as Xero contacts
- Invoices: syncs Kompass invoices as Xero invoices, credit notes, or manual journals
- Payments: pulls payments recorded in Xero back into Kompass; requires Invoices
- If you enable Invoices, you must also enable Clients. Payments requires Invoices.
- Tick the Enable checkbox to activate the connection.
- Click Save.
Checking a record's sync
To check whether a record reached Xero, or to send it again after fixing a sync error, open the client or invoice and look at the sync status icon beside the Actions menu, or choose Sync now from that menu. See Syncing records to your integrations.
Disconnecting from Xero
If you need to disconnect your Xero integration:
- Go to Xero → Configurations.
- Select the configuration using the tick-box.
- From the Action drop-down, select Disconnect from Xero and click Go.
- Confirm the disconnection when prompted.
The sync will stop immediately. You can re-authorize at any time by following Step 2 again.