> For the complete documentation index, see [llms.txt](https://wiki.roaddirect.co.nz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.roaddirect.co.nz/eboard/settings/xero-integration.md).

# Xero integration

The Xero integration connects eBoard to your Xero organisation so you can export invoices to Xero, link your eBoard users and clients to Xero employees and contacts, and import Xero contacts as new clients.

To open it, go to **Settings** → **Xero Integration**.

## Connect to Xero

You need to connect once before you can export invoices.

1. Click **Connect to Xero**. You're taken to Xero's login page ("Log in to your account … to continue to Road Direct").
2. Log in to Xero with an account that has access to your organisation.
3. On Xero's consent screen, check the **organisation** is the right one, then allow Road Direct access.
4. You're returned to the Xero Integration page with your organisation selected under **Xero Organisation**.

If you have access to more than one Xero organisation, choose the one to use from the **Xero Organisation** drop-down. To stop using Xero, click **Disconnect from Xero**.

{% hint style="warning" %}
Invoices are exported to the organisation shown under **Xero Organisation**. Check it's the right one before exporting, especially if you also have test or demo organisations in Xero.
{% endhint %}

## Link clients to Xero contacts

Every client you invoice must be linked to a contact in Xero, so exported invoices go to the right contact.

1. Under **Sync Xero Contacts**, click **Get Xero Contacts**. This only reads your contacts from Xero; nothing is changed yet.
2. Each Road Direct client is listed with eBoard's suggested Xero contact:
   * An exact match is selected automatically (e.g. "ACME INC (100% match)"). Click **see other matches…** to choose a different one.
   * Otherwise click **Show matches** to see possible contacts with a percentage match, and pick one. Contacts already linked to another client are greyed out.
   * If the contact doesn't exist in Xero yet, tick **Create New Xero Contact?** to create it.
3. Tick the clients you want to sync (or use **Select all**). The button shows how many will be synced, e.g. **Sync 1 clients**.
4. Click **Sync clients**. eBoard confirms the result, e.g. "1 Xero contacts created." The client then shows as **(already Synced)**.

Use **Reset New Sync Selections** to clear your choices and start again.

### Already-linked clients

Clients that are already linked are hidden by default. Tick **Show existing syncs** to see them. To remove a link, click **Unsync** on the client; you can then link it to a different contact. Tick **Show deleted Road Direct clients** to include deleted clients.

### "Invalid sync detected"

If a client shows **Invalid sync detected. Unable to match xero id to a known contact.**, it's linked to a contact that doesn't exist in the connected Xero organisation, for example because you've switched to a different Xero organisation, or the contact was deleted in Xero.

To fix it:

1. Tick **Show existing syncs** so the client is listed.
2. Click **Unsync** on the client. The warning disappears.
3. Click **Show matches** and pick the right contact, or tick **Create New Xero Contact?**.
4. Click **Sync clients**.

## Link users to Xero employees

Works the same way as contacts, under **Sync Xero Employees**:

1. Click **Get Xero Employees**.
2. For each Road Direct user, choose the matching Xero employee, or tick **Create New Xero Employee?**.
3. Click **Sync users**.

Tick **Show existing syncs**, **Show disabled Road Direct users** or **Show deleted Road Direct users** to include those users. A synced user's Xero Employee Id appears on their [user record](/eboard/resources/users.md).

## Import Xero contacts as new clients

Creates new eBoard [clients](/eboard/resources/clients.md) from your Xero contacts.

1. Under **Import Xero Contacts to Road Direct**, click **Get Xero Contacts**.
2. Tick the contacts you want to import. Use **Show only Xero customers** or **Show only Xero suppliers** to narrow the list, and **Show existing imports** to see contacts already imported.
3. Click **Create Road Direct clients**.

## Next steps

* Set the account codes and Xero tracking category used on exported invoices: see [System settings](/tracking/settings/system-settings.md) and [Xero settings](/tracking/settings/xero-settings.md).
* Export an invoice: see [Preview export](/tracking/invoices/preview-export.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.roaddirect.co.nz/eboard/settings/xero-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.