> For the complete documentation index, see [llms.txt](https://docs.labii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labii.com/widgets/dashboard-widgets/integration/quickbooks/quickbooks-customers.md).

# Quickbooks Customers

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 1.0.0 (updated on 2026-07-12) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Dashboard                     |
| **Support Configuration** | Yes                           |

## Overview

The Quickbooks Customers widget imports customer data from QuickBooks Online into Labii and keeps existing records synchronized. It organizes downloaded customer information into two linked data areas, including company-level account records and person-level contact records. This widget helps teams centralize customer master data, reduce manual entry, and improve consistency across finance and operational processes.

## Use Cases

* **Bulk Customer Import**: Download all QuickBooks customers into Labii in one run.
* **Account and Contact Sync**: Keep company and contact records aligned with QuickBooks updates.
* **CRM Data Readiness**: Prepare customer data for invoicing, communication, and account management workflows.
* **Cross-System Consistency**: Maintain shared identifiers for reliable downstream integrations.

## Configuration

### Initial Setup

{% stepper %}
{% step %}
Navigate to the dashboard where you want to add the widget.
{% endstep %}

{% step %}
Click **Add Widget** and select **Quickbooks Customers** from the dashboard widget catalog.
{% endstep %}

{% step %}
Configure required authorization, project assignment, and table-to-column mappings for account and contact data.
{% endstep %}

{% step %}
Click **Save** to add the widget to your dashboard.
{% endstep %}
{% endstepper %}

### Required Settings

* **Realm ID**: Unique identifier for your QuickBooks Online company.
* **Refresh Token**: OAuth refresh token used to authenticate and retrieve customer data.
* **Is Sandbox**: Enable when connecting to QuickBooks sandbox instead of production.
* **Projects**: Project(s) to associate with synchronized accounts and contacts.
* **Account Table**: Table that stores account-level customer data.
* **Account: QuickBooks Customer ID Column**: Column for QuickBooks customer ID.
* **Account: QuickBooks Sync Token Column**: Column for QuickBooks sync token.
* **Account: Billing Address Column**: Column for billing address data.
* **Account: Shipping Address Column**: Column for shipping address data.
* **Account: Point of Contact Column**: Column for account-level primary contact reference.
* **Contact Table**: Table that stores contact-level customer data.
* **Contact: Account Column**: Column linking contact to account.
* **Contact: Title Column**: Column for contact title.
* **Contact: Email Column**: Column for contact email.
* **Contact: Office Phone Column**: Column for office phone.
* **Contact: Cell Phone Column**: Column for cell phone.

### Optional Settings

* **Project Scope Selection**: Limit synchronization to selected project contexts.
* **Sandbox Mode**: Use for testing mappings before production data sync.

{% hint style="info" %}
Run initial synchronization in sandbox mode to validate account-contact relationships before production import.
{% endhint %}

## Readonly View

Dashboard widgets are displayed in read-only mode on dashboards for monitoring and actions.

### Display Features

* **Start Download Button**: Triggers customer download and synchronization.
* **Status Feedback**: Indicates sync progress and completion status.
* **Mapped Destinations**: Uses configured account and contact tables for writes.

### Interactive Features

* **Start Download**: Manually run customer synchronization.
* **Re-run Sync**: Repeat download to update existing customer records.

## Additional Functions

### Download and Synchronize

After configuration is complete, click **Start Download** to import customer data from QuickBooks. Existing Labii records are updated when matching identifiers are found.

### Dual-Table Data Organization

* Splits imported data into account and contact structures for better data management.
* Preserves linkage between customer accounts and associated contacts.

## Best Practices

* Validate both account and contact mappings in sandbox before production sync.
* Keep QuickBooks customer ID and sync token columns immutable to prevent duplicates.
* Ensure account-contact relationship columns are correctly configured before first run.
* Perform periodic re-sync to keep customer communication data current.

## Related Widgets

* [**Quickbooks Accounts**](/widgets/dashboard-widgets/integration/quickbooks/quickbooks-accounts.md): Synchronize chart of accounts for financial consistency.
* [**Quickbooks Items**](/widgets/dashboard-widgets/integration/quickbooks/quickbooks-items.md): Import product and service items used in billing workflows.
* [**Quickbooks Invoices**](/widgets/dashboard-widgets/integration/quickbooks/quickbooks-invoices.md): Import invoices that depend on synchronized customer records.