QuickBooks Online Integrated Data
Field mapping reference for QuickBooks Online
What this page covers: A complete reference mapping every QuickBooks Online field to its Mosaic equivalent. Use this guide when configuring your integration, verifying synced data, or troubleshooting discrepancies.
| Integration type | Cloud (QuickBooks Online API) |
| Authentication | OAuth 2.0 |
| Setup complexity | Low |
| Prerequisite | QuickBooks Online Integration Setup |
How Data Flows
QuickBooks Online (API) → Mosaic Sync Engine (field mapping) → Mosaic (6 synced data types)
Mosaic connects to QuickBooks Online through the QuickBooks Online API to read employee, customer, item, and time activity data. The Customer hierarchy in QuickBooks (top-level Customers, Sub-Customers, and further nested Sub-Customers) is used to map Clients, Projects, and Phases. See Phases for how deeply nested Sub-Customers are handled.
Most data flows one-way from QuickBooks into Mosaic. Time Entries are the exception — they sync in both directions, with QuickBooks → Mosaic updates delivered in near real time via QuickBooks webhooks, and Mosaic → QuickBooks updates pushed back automatically. See Time Entries for details.
QuickBooks Time Approval Required
If you use QuickBooks Time (formerly TSheets), time entries must be approved and exported to QuickBooks Online before they sync to Mosaic. Unapproved or unexported time will not appear. See QuickBooks Time for details.
Integrated Data Types
The integration syncs 6 data categories from QuickBooks Online into Mosaic:
| Data Type | Description |
|---|---|
| Members | Employee name, email |
| Clients | Customer records (top-level QuickBooks Customers) |
| Projects | Project records (QuickBooks Sub-Customers / Jobs) |
| Phases | Phase breakdowns under projects (QuickBooks Sub-Customers nested below a Project) |
| Work Categories | QuickBooks Items used for time categorization |
| Time Entries | Timesheet entries with hours, rates, and billability |
This list may expand as new features are added.
Not Synced
| Data Type | Description |
|---|---|
| Member Cost Rates | Employee hourly cost rates are not synced from QuickBooks Online |
| Member Project Bill Rates | Member-to-project rate assignments are not available |
| Member / Project Roles | Role assignments are not synced — Mosaic uses its own role management |
| Rate Groups / Standard Bill Rates | Standard billing rate tables are not synced |
| Work Plans | Resource planning assignments are not synced from QuickBooks Online |
| Fee / Budget data | Project fees, budgets, and billing terms are not synced |
Reading the Field Mapping Tables
Symbol legend for technical tables
The Technical Reference tabs below use a shorthand notation for API sources. Read this legend before reviewing the mappings.
| Symbol | Meaning | Example |
|---|---|---|
. | API object field reference | Employee.GivenName = the GivenName field from the Employee object |
> | Fallback priority — use the first available value | Customer.CompanyName > Customer.DisplayName = use CompanyName; if null, use DisplayName |
• | Values combined into one composite value | TimeActivity.Hours • TimeActivity.Minutes = combined into total hours |
Members
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Employee ID | The unique QuickBooks employee identifier |
| First Name | The employee's given name |
| Middle Name | The employee's middle name |
| Last Name | The employee's family name, falling back to the display name if the family name is not set |
| The employee's primary email address |
Active Employees Only
Only employees marked Active in QuickBooks are synced to Mosaic. When an employee is marked inactive in QuickBooks, they stop receiving updates — their existing Mosaic record is preserved but will no longer change.
Syncing Vendors as Members (optional)
By default, Mosaic syncs QuickBooks Employees as Members. Some organizations use QuickBooks Vendors to track 1099 contractors or independent workers who log time. If this applies to you, Mosaic can be configured to sync Vendors as Members alongside Employees.
When enabled:
- Active Vendor records sync into Mosaic as Members using the same field mappings as Employees (name, email).
- Time entries logged against those Vendors in QuickBooks sync into Mosaic as Member time entries.
Contact your Customer Success Manager to enable this during onboarding.
Clients
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Client ID | The unique QuickBooks customer identifier |
| Client Title | The top-level Customer's display name, falling back to company name |
| Description | The customer's notes |
| Is Archived | Derived from the customer's active status — inactive customers are archived in Mosaic |
Projects
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Project ID | The unique QuickBooks customer identifier for the project |
| Project Title | The Sub-Customer / Job display name, falling back to company name |
| Company Name | The Sub-Customer's company name |
| Client | The top-level parent Customer |
| Description | The Sub-Customer's notes |
| Is Billable | Derived from the Sub-Customer's taxable flag |
| Is Archived | Derived from the Sub-Customer's active status — inactive = archived |
Phases
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Phase ID | The unique QuickBooks customer identifier for the phase |
| Phase Title | The Sub-Customer / Sub-Job display name, falling back to company name |
| Company Name | The Sub-Customer's company name |
| Parent | The parent Sub-Customer (a Project or another Phase) |
| Description | The Sub-Customer's notes |
| Is Billable | Derived from the Sub-Customer's taxable flag |
| Is Archived | Derived from the Sub-Customer's active status — inactive = archived |
Nested Phases
QuickBooks Sub-Customers can be nested several levels deep. Mosaic maps anything below a Project as a Phase — so a Sub-Customer's child becomes a sub-phase parented to the Phase above it. Your QuickBooks hierarchy is preserved in Mosaic regardless of depth.
Work Categories
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Activity ID | The unique QuickBooks item identifier |
| Activity Code | The item's fully qualified name, falling back to the item name |
| Work Category Title | The item's description, falling back to the item name |
| Is Billable | Derived from the item's taxable flag |
Which items sync?
All non-Category items sync — Service, Inventory, Non-Inventory, and Group items are included. Items with type "Category" are excluded, as are items marked inactive.
Time Entries
| What Syncs to Mosaic | Where It Comes From in QuickBooks Online |
|---|---|
| Time Entry ID | The unique QuickBooks time activity identifier |
| Date | The transaction date of the time entry |
| Employee | The employee who logged the time (or vendor, when vendors sync as members) |
| Project / Phase | The Customer the time was logged against, resolved to a Project or Phase based on hierarchy depth |
| Work Category | The item used on the time entry |
| Hours | The total hours logged, combining the hours and minutes fields |
| Description | The notes/comments on the time entry |
| Hourly Rate | The hourly rate on the time entry |
| Billable | Derived from the entry's billable status — Billable and Already Billed entries sync as billable; Not Billable entries sync as non-billable |
Two-Way Sync
Time Entries sync in both directions:
- QuickBooks → Mosaic: Time activities in QuickBooks are delivered to Mosaic in near real time via QuickBooks webhooks — new or edited entries are reflected in Mosaic within seconds of being saved in QuickBooks. All other data types (Members, Clients, Projects, Phases, Work Categories) are read-only from QuickBooks → Mosaic only.
- Mosaic → QuickBooks: Time entries created or updated in Mosaic are pushed back to QuickBooks automatically. Time entries that QuickBooks has already marked as billed cannot be modified from Mosaic — those updates are skipped to preserve invoice integrity.
QuickBooks Time Approval Required
If you use QuickBooks Time (formerly TSheets), time entries must be approved and exported to QuickBooks Online before they sync to Mosaic. Unapproved or unexported time will not appear. See QuickBooks Time for details.
Payroll for QuickBooks
If you are using Payroll for QuickBooks, reach out to your Customer Success Manager for guidance on syncing time from Mosaic into QuickBooks.
Troubleshooting & FAQ
Why aren't my project fees or budgets showing up in Mosaic?
Project fees, budgets, and billing terms are not synced from QuickBooks Online. Budget and fee data must be managed directly in Mosaic.
Can I rename field labels in Mosaic to match my QuickBooks custom labels?
No. Custom field name changes in Mosaic to match QuickBooks labeling is not supported as a standard integration feature.
Why aren't my QuickBooks Time entries syncing?
Time Entries from QuickBooks Time must be exported to QuickBooks Online following approval before they will sync to Mosaic. Unapproved/unexported time will not appear. For more detail, see QuickBooks Time.
Are cost rates or bill rates synced from QuickBooks?
No. Member cost rates, project bill rates, and standard rate tables are not synced from QuickBooks Online. Rates are managed in Mosaic.
Can I sync work plans or resource planning data?
No. Work plans and resource planning assignments are not available in the QuickBooks Online integration.
I need a data source or field that isn't listed here.
Any integration not listed in this documentation is considered a customization and is charged at an hourly rate. For more information, see Integration Requests.
QuickBooks Online Documentation Links
A consolidated reference of all QuickBooks Online documentation referenced in this guide:
| Topic | Link |
|---|---|
| API Reference | All Entities |
| Employee | Employee Entity |
| Customer | Customer Entity |
| Item | Item Entity |
| TimeActivity | TimeActivity Entity |
Related Documentation
Updated 25 days ago