> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounting Integrations

> Connect an accounting platform to import a Chart of Accounts and export journal entries.

Nmbr integrates with **Xero** and **QuickBooks Online**. A connected integration imports a client's Chart of Accounts and tracking dimensions, and exports each payroll's journal entries into their books, tag allocations included.

An integration comes together in three phases, each with its own cadence:

1. **Register an OAuth application** with each platform you support: one application per platform, one time.
2. **Connect the client's account**: each Business Entity connects its own Xero or QuickBooks account.
3. **Import and export**: sync the Chart of Accounts and tracking dimensions as the client's books change, and export journal entries payroll by payroll.

## Registering your OAuth application

Register a developer account with the platform and create an OAuth 2.0 application, with the redirect URI set to:

```
https://uni-api.nmbr.co/oauth/code
```

Then add the application's client ID and secret in the Nmbr Portal.

Platform notes:

* **Xero**: create a [Demo company](https://central.xero.com/s/article/Use-the-demo-company) to test against.
* **QuickBooks**: select the "Sandbox" environment when creating a testing application, and create a [Demo company](https://quickbooks.intuit.com/learn-support/en-ca/help-article/small-business-processes/test-drive-quickbooks-online/L9C12ODlA_CA_en_CA) to test against.

## Connecting a client's account

Request an authentication URL and send the client there to approve access:

**Request**

```bash theme={null}
curl --request POST \
     --url 'https://sandbox.nmbr.co/services/payroll/integrations/xero/authenticate' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <access_token>' \
     --data '{
       "business_entity_id": "<business_entity_id>"
     }'
```

**Response**

```json theme={null}
{
  "id": "xero",
  "object": "oauth_auth_url",
  "data": {
    "authentication_url": "https://login.xero.com/identity/connect/authorize?..."
  }
}
```

Once the client approves, Nmbr stores the connection and sends an `integration_authentication_success` (or `integration_authentication_failure`) [webhook](/api/overview/webhook-structure) on the Business Entity. Clients can also be connected directly in the Nmbr Portal.

If you run the OAuth flow against your own application yourself, you can supply the resulting tokens with [`POST /integrations/{integration}/connection`](/api-reference/integrations/import-a-partner-supplied-oauth-connection) instead.

[`GET /integrations`](/api-reference/integrations/list-integrations) lists both platforms for a Business Entity, with `is_enabled` and the connected account's details. Disconnect with [`DELETE /integrations/{integration}`](/api-reference/integrations/delete-an-integration).

## Importing the Chart of Accounts

After a client connects, import their Chart of Accounts into their Business Entity:

```bash theme={null}
curl --request POST \
     --url 'https://sandbox.nmbr.co/services/payroll/integrations/xero/sync' \
     --header 'Authorization: Bearer <access_token>' \
     --data '{
       "business_entity_id": "<business_entity_id>",
       "sync": "accounting_codes"
     }'
```

The sync runs in the background: the endpoint returns `202 Accepted`, and an `integration_sync_account_codes_complete` (or `_failure`) webhook fires when it finishes.

Imported accounts are limited to the `expense`, `liability`, and `bank` types. Each imported code carries the platform's identifier for its account, which the export uses to address rows. If an import leaves duplicates of codes you created by hand, [merge them](/guides/accounting/codes-and-rules#merging-accounting-codes) into the imported ones.

## Importing tracking dimensions

Accounting platforms also expose tracking dimensions: Xero tracking categories; QuickBooks classes, departments, and projects. Each imported dimension becomes a Tag Group and its values become Tags, ready for [tag allocation](/guides/accounting/tagging).

List the dimensions a connection exposes with [`GET /integrations/{integration}/tracking_dimensions`](/api-reference/integrations/list-integration-tracking-dimensions), then import with the `category`, `department`, or `project` sync type:

```bash theme={null}
curl --request POST \
     --url 'https://sandbox.nmbr.co/services/payroll/integrations/quickbooks/sync' \
     --header 'Authorization: Bearer <access_token>' \
     --data '{
       "business_entity_id": "<business_entity_id>",
       "sync": "department"
     }'
```

An `integration_sync_tags_complete` (or `_failure`) webhook fires when the import finishes. Imported tag groups and tags keep their external identifiers, so re-running the sync updates them in place. See [Setting up tag groups and tags](/guides/accounting/tagging#setting-up-tag-groups-and-tags).

## Exporting journal entries

Export a payroll's journal entries into the connected platform:

```bash theme={null}
curl --request POST \
     --url 'https://sandbox.nmbr.co/services/payroll/integrations/xero/sync' \
     --header 'Authorization: Bearer <access_token>' \
     --data '{
       "payroll_id": "<payroll_id>",
       "sync": "journal_entries"
     }'
```

The export runs in the background and fires an `integration_sync_journal_entries_complete` (or `_failure`) webhook on the payroll. Only the two payroll-level entries are exported, the [accrual entry and the payment entry](/guides/accounting/journal-entries). Zero-amount rows are skipped, and row descriptions are prefixed with your partner name and the pay schedule so they read clearly in the client's books.

For the export to succeed:

* Every exportable row needs an accounting code with the connected platform's identifier: one imported from the platform, or [merged](/guides/accounting/codes-and-rules#merging-accounting-codes) into one that was.
* The Business Entity must have its [default **bank** and **payroll payable** codes](/guides/accounting/codes-and-rules#business-entity-accounting-settings) set.

To stop payrolls from being approved before their entries can export, enable `block_approval_on_missing_export_identifiers` in the Business Entity's [accounting settings](/guides/accounting/codes-and-rules#business-entity-accounting-settings).

Rows carry their tags into the platform: allocations land as Xero tracking categories, or QuickBooks classes, departments, and projects. After a successful export, the entry's `integrations.xero.reference` or `integrations.quickbooks.reference` holds the platform's id for the created journal.