QuickBooks Online
This document outlines the integration with the QuickBooks Online connector, enabling the OvalEdge application to connect to QuickBooks Online cloud services through the Intuit v3 REST API using OAuth2 authentication. The integration supports secure communication, automatic token refresh, and API-based request execution.
The integration enables structured metadata extraction through entity discovery, report discovery, and data preview. It provides access to both business entities and financial reports, supporting efficient metadata exploration and data retrieval.
Overview
Connector Details
Connector Category
Application
OE Application Version
R8.0
QuickBooks Online API Version
Intuit v3
Connectivity [How the connection is established with QuickBooks Online]
REST APIs (Intuit v3)
Supported Environments
Production, Sandbox
API Base URL
https://quickbooks.api.intuit.com
(Production)
https://sandbox-quickbooks.api.intuit.com
(Sandbox)
Production is the live environment for real business data, while Sandbox is a non-production environment used for testing and development without affecting live records.
The QuickBooks Online connector has been validated with the mentioned "QuickBooks Online API Versions" and is expected to be compatible with other supported QuickBooks Online API Versions. If there are any issues with validation or metadata crawling, please submit a support ticket for investigation and feedback.
Connector Features
Crawling
✅
Profiling
❌
Query Sheet
❌
Data Preview
✅
Auto Lineage
❌
Manual Lineage
❌
Secure Authentication via (OAuth2)
✅
Metadata Mapping
The following objects are crawled from QuickBooks Online and mapped to the corresponding UI assets.
QuickBooks company (Realm ID)
Container
Database for Tables
Domain for Reports
QuickBooks entity type
Entity
Table
QuickBooks report name
Report
Report
Entity/Report column
Field
Table Column/ Report Column
Set up a Connection
Prerequisites
The following are the prerequisites to establish a connection:
Before configuring the connector, the QuickBooks Online environment must be prepared with the required Intuit application credentials, company identification details, environment selection, and authorization tokens. These prerequisites are essential for securely authorizing access to QuickBooks Online accounting data and maintaining uninterrupted connectivity. For detailed instructions on setting up these prerequisites, click here.
System & Software Requirements
QuickBooks Online Account
Must be active and accessible
OAuth2 Application
Client ID and Client Secret must be generated
Company Realm ID
Required to identify the QuickBooks Online company
External Supporting Services
Intuit OAuth Platform
Used for secure authentication and token issuance
QuickBooks Online REST API
Used for metadata discovery and data queries
QuickBooks Online connectivity is performed entirely through the Intuit v3 REST API
OAuth2 authentication is mandatory for secure access
Ensure outbound connectivity to quickbooks.api.intuit.com and oauth.platform.intuit.com
Connection Configuration Steps
Users are required to have the Connector Creator role in order to configure a new connection.
Log into OvalEdge, go to Administration > Connectors, click + (New Connector), search for QuickBooks Online, and complete the required parameters.
Fields marked with an asterisk (*) are mandatory for establishing a connection.
Connector Type
By default, "QuickBooks Online" is displayed as the selected connector type.
Connector Name*
Enter a unique name for the QuickBooks Online connection
(Example: "QuickBooks Online_Prod").
Connector description
Enter a brief description of the connector.
Client ID*
Enter the QuickBooks OAuth2 Client ID. This identifier is required to authenticate the OvalEdge application with Intuit’s authorization platform.
Client Secret*
Enter the OAuth2 Client Secret associated with the Client ID. This secret is used to securely authenticate API requests and authorize access to the QuickBooks Online environment.
Company ID*
Enter the QuickBooks Online Realm ID (QuickBooks Company/Realm ID) that uniquely identifies the target QuickBooks Online company from which metadata and data will be retrieved.
Environment*
Select the target environment where the QuickBooks Online company resides, either Production or Sandbox, to ensure API calls are routed to the correct Intuit endpoint.
Access Token
Displays the OAuth2 Access Token used to authorize API requests to QuickBooks Online. This token is automatically refreshed by the system when expired and does not require manual updates.
Refresh Token
Displays the OAuth2 Refresh Token, which is used to automatically renew the Access Token when it expires, ensuring uninterrupted connectivity and secure API communication.
Default Governance Roles
Default Governance Roles*
Select the appropriate users or teams for each governance role from the drop-down list. All users and teams configured in OvalEdge Security are displayed for selection.
Admin Roles
Admin Roles*
Select one or more users from the dropdown list for Integration Admin and Security & Governance Admin. All users configured in OvalEdge Security are available for selection.
After entering all connection details, the following actions can be performed:
Click Validate to confirm API access and company authorization.
Click Save to store the connection for future use.
Click Save & Configure to apply additional settings before saving.
The saved connection will appear on the Connectors home page.
Manage Connector Operations
Crawl
To perform crawl operations, users must be assigned the Integration Admin role.
The Crawl/Profile button allows users to select one or more schemas for crawling.
Navigate to the Connectors page and click Crawl/Profile.
Select the schemas to crawl.
The Crawl option is selected by default.
Click Run to collect metadata from the connected source and load it into the OvalEdge Data Catalog.
After a successful crawl, the information appears in the Data Catalog > Databases/Reports/Tables tab.
The Schedule checkbox allows automated crawling at defined intervals, from a minute to a year.
Click the Schedule checkbox to enable the Select Period drop-down.
Select a time period for the operation from the drop-down menu.
Click Schedule to initiate metadata collection from the connected source.
The system will automatically execute the Crawl operation at the scheduled time.
Other Operations
The Connectors page in OvalEdge provides a centralized view of all configured connectors, including their health status.
Managing connectors includes:
Connectors Health: Displays the current status of each connector using a green icon for active connections and a red icon for inactive connections, helping to monitor the connectivity with data sources.
Viewing: Click the Eye icon next to the connector name to view connector details, including databases, tables, columns, and codes.
Nine Dots Menu Options:
To view, edit, validate, configure, or delete connectors, click on the Nine Dots menu.
Edit Connector: Update and revalidate the data source.
Validate Connector: Check the integrity of the connection.
Settings: Modify connector settings.
Crawler: Configure data extraction.
Business Glossary Settings: Manage term associations at the connector level.
Others: Configure notification recipients for metadata changes.
Delete Connector: Remove a connector with confirmation.
Connectivity Troubleshooting
If incorrect parameters are entered, error messages may appear. Ensure all inputs are accurate to resolve these issues. If issues persist, contact the assigned support team.
1
401 Unauthorized
Error Description:
The access token or refresh token is invalid, expired, revoked, or not authorized for the specified QuickBooks Online company. This may occur if OAuth2 credentials were regenerated, revoked, or incorrectly configured.
Resolution:
Verify that the Client ID and Client Secret are correct.
Reauthorize the QuickBooks Online connection to regenerate valid Access and Refresh Tokens.
Ensure that the OAuth2 application remains active in the Intuit Portal.
2
Invalid Company ID (Realm ID)
Error Description:
The specified Company ID (Realm ID) does not exist, is incorrect, or the authenticated user does not have permission to access the associated QuickBooks Online company.
Resolution:
Confirm that the Company ID is correctly entered.
Ensure that the authenticated Intuit user has appropriate access to the QuickBooks Online company.
Reauthorize the connection if access permissions were recently changed.
3
Sandbox / Production Environment Mismatch
Error Description: The selected environment (Sandbox or Production) does not match the QuickBooks Online company environment, resulting in failed API calls or validation errors.
Resolution:
Verify whether the Company ID belongs to a Sandbox or Production environment.
Update the Environment field to match the correct environment and retry validation.
4
Entity Not Available
Error Description: Certain QuickBooks Online entity types may not be enabled for the company, leading to skipped or unavailable entities during metadata discovery.
Resolution:
This behavior is expected when entities are not supported by the company configuration. Review the enabled features in QuickBooks Online and proceed with supported entities.
Copyright © 2026, OvalEdge LLC, Peachtree Corners GA USA
Was this helpful?