How to connect to the QuickBooks API

Apideck enables you to build a native integration with QuickBooks. This guide explains how to configure the QuickBooks connector.

Before you start, you’ll need:

To create your Intuit Developer account, follow the steps below.

Navigate to developer.intuit.com
On the menu bar, click Sign up, which will open the "Create your account" form.
Fill out the form and click Create Account, which redirects you to the developer homepage.
Navigate to Account Profile, fill out your profile details, and click Submit.
Watch the email inbox you specified for a confirmation message and a second message that contains some introductory links to get you started.
To create a new app, navigate to the Apps dashboard and click Create an app. Copy the Client ID and Secret.
Add the Apideck Redirect URI:
https://unify.apideck.com/vault/callback
Go back to Apideck to configure the QuickBooks connector with your Client ID and Secret.

Apideck QuickBooks Client ID/Secret

Fill out the App Assessment and Compliance Questionnaire to get your app certified.

Before you can list your app on the QuickBooks App Store, it will be reviewed to ensure it meets the following security requirements and complies with the Intuit Developer Terms. This is in addition to meeting the technical and marketing requirements.

After logging into your developer account, you can find the questionnaire here or on your app dashboard. Select your app from the dashboard, navigate to the Production Settings tab, and click on App assessment questionnaire on the left-side navigation bar.

If you're building an integration through Apideck, you can use the following answers when submitting the questionnaire:

How often do you request refresh access tokens? Only when access tokens expire.
Did you use the Intuit discovery document to get the latest endpoints required in the OAuth2.0 flow? Yes
Does your app rely on the OAuth playground or other offline tools to get access or refresh tokens? No
Do you use the CDC operation for your app? No
Users often change versions of QuickBooks Online. This means they may get access to new features, or lose certain features, at any time. Can your app handle situations where users gain or lose access to version-specific features? Yes
Does your app capture the value of the intuit_tid field from response headers? Yes
Does your app retry authorization and authentication requests that have failed? No
Can you handle the following scenarios? Errors due to expired access tokens? Yes
Can you handle the following scenarios? Errors due to expired refresh tokens? Yes
Can you handle the following scenarios? Invalid grant errors? Yes
Can you handle the following scenarios? CSRF errors? Yes

The security review starts once your app passes the technical review.

Following the initial security review, developers must remediate any critical, high, or medium priority issues before they can be published on the app store. For ongoing compliance reviews, these issues should be fixed within 2 weeks of notification by Intuit.

Apps listed on the QuickBooks App Store must continue to meet these requirements after publication. All apps listed on the app store, and any app with over 500 connections, will be reviewed by Intuit on an annual basis, or more frequently at Intuit’s discretion, to ensure they continue to meet required technical and security standards.

You can also go to the Keys & OAuth subsection to update your app’s redirect URLs, host domain, launch URL, and disconnect URL. Some of these settings are important if you're implementing Intuit Single Sign-on.

Launch URL: Add a link to the page that implements single sign-on. This URL is the integration settings URL in your app, where you can connect with QuickBooks.

App assessment and compliance questionnaire FAQ

All developers with app(s) on the QuickBooks platform that are connected to one or more production QuickBooks Online companies need to submit this questionnaire. Intuit refreshes its app compliance criteria periodically to ensure an appropriate level of quality for all apps on the QuickBooks platform and to ensure all apps adhere to Intuit's Developer Terms of Service, including data security and compliance policies.

Do I still need to submit this questionnaire if I'm a private app and don't plan to list it on the app store?
Yes. If your app has any connections to production QuickBooks Online companies, you will need to submit this questionnaire even if your app is not listed on the QuickBooks App Store. The app assessment and compliance process applies to both private (i.e., unlisted) apps and apps that are, or want to be, listed on the QuickBooks App Store.

Source: https://help.developer.intuit.com/s/article/New-app-assessment-process-FAQ

Required Scopes for QuickBooks Integration

When setting up the QuickBooks connector in the Apideck dashboard, you’ll be asked to select the scopes your integration requires. Scopes define which parts of the QuickBooks API your app can access.

At a minimum, you should enable:

com.intuit.quickbooks.accounting — This grants access to QuickBooks accounting data (such as invoices, customers, and general ledger information).
This is the only required scope for most accounting use cases.

If your integration needs to access user-specific identity information (like name, email, phone number, or address), you must also select:

openid — Enables identity support via OpenID Connect.
This scope is required in order to use any of the following:
- profile — For the user’s first and last name
- email — For the user’s email address
- phone — For the user’s phone number
- address — For the user’s physical address

Important: Selecting profile, email, phone, or address without selecting openid will cause the connection to fail.

Do your first API call to the QuickBooks API

Connect your QuickBooks account through Vault with a test session.
To test the access token, make a query to get your Invoices endpoint using the Accounting API.


curl --location --request GET 'https://unify.apideck.com/accounting/invoices' \
--header 'x-apideck-consumer-id: test-consumer' \
--header 'x-apideck-app-id: {APIDECK_APP_ID}' \
--header 'x-apideck-service-id: quickbooks' \
--header 'Authorization: Bearer {APIDECK_API_KEY}' \
--header 'Content-Type: application/json'

Start building with the QuickBooks API

Learn what else you can build with the QuickBooks API.

Interested in a personalized demo? Let us know.

QuickBooks API Call Limit & Partnership Fee

QuickBooks' partnership terms state that if a customer exceeds 500,000 CorePlus API calls per month, they must pay a partnership fee to QuickBooks.
Since you are using your own app, you are responsible for this fee if you reach the QBO API call limit.
More details can be found here: Intuit App Partner Program

Recent API Changes and Limitations

Throttling Limits (Effective 2025)

Sandbox Environment: API calls are throttled at 10 requests per second per realm ID and app (effective September 15, 2025), matching Production limits.
Batch Endpoint: API calls to the Batch endpoint are throttled at 120 requests per minute per realm ID:
- Sandbox: Effective August 15, 2025
- Production: Effective October 31, 2025

Address Field Changes (Effective 2025)

Country Fields: Starting September 15, 2025 (Sandbox) / October 31, 2025 (Production), the Country field in CompanyAddr, CustomerCommunicationAddr, and LegalAddr will always return ISO 3-letter country codes (e.g., "USA" instead of "United States"). You can still send any string values, but responses will be normalized.
Deprecated Lat/Long Fields: Starting August 15, 2025 (Sandbox) / September 15, 2025 (Production), Lat and Long fields under address objects will no longer be returned in API responses.
Deprecated Source Fields: Starting August 15, 2025 (Sandbox) / September 15, 2025 (Production), the "Source" field in Customer and Vendor entities will no longer be returned in API responses.

Usage Limits (Effective September 15, 2025)

QuickBooks Online subscription tiers have usage limits that are now enforced via API:

Accounts: QuickBooks Online Plus allows up to 250 accounts
Classes and Departments: QuickBooks Online Plus allows up to 40 combined classes and locations
Attempting to exceed these limits will return error code 6570 with usage limit guidance

Account Validation (Effective September 15, 2025 Sandbox / October 31, 2025 Production)

Fixed Asset accounts with subtypes AccumulatedDepreciation, AccumulatedAmortization, or AccumulatedDepletion can only be created as child accounts, not parent accounts
Violations will return error code 6000 with validation details

Query Filtering Changes (Effective September 15, 2025 Sandbox / October 31, 2025 Production)

ID field filtering no longer supports operators >, !=, <
Supported: ID = '40' or ID in ('10', '15', '20')
Unsupported: ID != '250' or ID > '250' (filters will be ignored and all values returned)

Using Departments/Locations and Classes in QuickBooks Online

QuickBooks Online supports two powerful categorization features for tracking where your business activity happens: Departments and Classes. In the QuickBooks API, business units (departments) are represented by the Department entity.

Enable Locations and Classes in QBO

In QuickBooks Online, go to the gear icon → Account and settings → Advanced → Categories.
Toggle on Track classes and/or Track departments.
Optionally choose whether to assign classes/departments per transaction or per line.
Save your changes.

Departments and Classes are best used for high‑level categories such as offices, regions, or departments. They are available on QuickBooks Online Plus and Advanced editions.

References:

Using Classes and Departments in QBO: Using Classes And Locations in QuickBooks Online
Business units in the API: Manage business units (Departments) workflow

How Apideck maps QBO Departments

The Apideck Accounting API departments resource maps to the QuickBooks Department entity.
If your product or domain uses the term “departments”, treat these QBO Departments as departments—they are the same underlying entity in QBO and are exposed via Apideck’s departments endpoints. See: Manage business units (Departments).
Supported operations (QBO endpoints):
- List: GET /query?query=select * from Department (offset/limit via query)
- Create: POST /department
- Get by ID: GET /department/{id}
- Update: POST /department/{id} (sparse update)
Field mappings (examples):
- name → Name
- status → Active (Apideck normalizes to active/inactive)
- row_version → SyncToken
- created_at/updated_at → MetaData.CreateTime/MetaData.LastUpdatedTime (normalized to ISO 8601)

Practical examples (Apideck Accounting API)

Create a department:


curl --request POST \
  https://unify.apideck.com/accounting/departments \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-service-id: quickbooks' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New York Office",
    "status": "active"
  }'

List departments:


curl --request GET \
  'https://unify.apideck.com/accounting/departments?limit=20&offset=0' \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-service-id: quickbooks' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}'

Get a department by ID:


curl --request GET \
  https://unify.apideck.com/accounting/departments/{id} \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-service-id: quickbooks' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}'

Update a department:


curl --request PATCH \
  https://unify.apideck.com/accounting/departments/{id} \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-service-id: quickbooks' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "NYC Office - Updated",
    "status": "inactive"
  }'

Notes and requirements

Ensure Departments/Classes are enabled in the QBO company; otherwise department fields may be ignored or operations may fail validation in the UI.
Required scope remains com.intuit.quickbooks.accounting.
QBO represents business units as Department in the API; Apideck’s departments abstracts this for consistency across accounting connectors.