--- language: "en" --- # References ## 1. Official API Reference | Resource | Link | |-------------------------------------|------------------------------------------------------------------------------------------------------| | **All Entities (Full Reference)** | | | **Most Commonly Used Entities** | | | **Developer Overview** | | | **Create a Request (Basics)** | | | **REST API Features \& Formats** | | | **Authentication \& OAuth 2.0 FAQ** | | | **Error Codes Reference** | | | **Handling Common Errors** | | | **Webhooks** | | | **Postman Setup** | | *** ** * ** *** ## 2. Request Examples All API requests require three standard headers: Authorization: Bearer {access_token} Accept: application/json Content-Type: application/jso > **Base URLs** > > * Production: `https://quickbooks.api.intuit.com` > > * Sandbox: `https://sandbox-quickbooks.api.intuit.com` > > All endpoints use **Minor Version 75** (`?minorversion=75`) *** ** * ** *** ### 2.1 Create Account POST /v3/company/{companyId}/account?minorversion=75 { "Name": "Operating Checking Account", "AccountType": "Bank", "AccountSubType": "Checking", "CurrencyRef": { "value": "USD", "name": "United States Dollar" } } **Required fields:** `Name` + either `AccountType` or `AccountSubType` **Common** `AccountType`**values:** | AccountType | Classification | |---------------------------|----------------| | `Bank` | Asset | | `Accounts Receivable` | Asset | | `Other Current Asset` | Asset | | `Fixed Asset` | Asset | | `Accounts Payable` | Liability | | `Credit Card` | Liability | | `Other Current Liability` | Liability | | `Long Term Liability` | Liability | | `Equity` | Equity | | `Income` | Revenue | | `Cost of Goods Sold` | Expense | | `Expense` | Expense | | `Other Expense` | Expense | | `Other Income` | Revenue | *** ** * ** *** ### 2.2 Create Customer POST /v3/company/{companyId}/customer?minorversion=75 { "DisplayName": "Acme Corporation", "CompanyName": "Acme Corp", "PrimaryEmailAddr": { "Address": "acme@example.com" }, "PrimaryPhone": { "FreeFormNumber": "555-555-5555" }, "BillAddr": { "Line1": "123 Main Street", "City": "Mountain View", "CountrySubDivisionCode": "CA", "PostalCode": "94043", "Country": "US" } } **Required field:** `DisplayName` (must be unique within QBO) *** ** * ** *** ### 2.3 Create Invoice POST /v3/company/{companyId}/invoice?minorversion=75 { "CustomerRef": { "value": "59" }, "Line": [ { "Amount": 500.00, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" }, "Qty": 5, "UnitPrice": 100.00 } } ], "DueDate": "2025-06-30", "DocNumber": "INV-1001" } *** ** * ** *** ### 2.4 Create Payment POST /v3/company/{companyId}/payment?minorversion=75 { "CustomerRef": { "value": "59" }, "TotalAmt": 500.00, "Line": [ { "Amount": 500.00, "LinkedTxn": [ { "TxnId": "142", "TxnType": "Invoice" } ] } ] } *** ** * ** *** ### 2.5 Query (SQL-like) GET /v3/company/{companyId}/query?query=SELECT * FROM Account WHERE AccountType='Bank'&minorversion=75 The QBO query language supports `SELECT`, `FROM`, `WHERE`, `ORDERBY`, `STARTPOSITION`, and `MAXRESULTS`. SELECT * FROM Account WHERE Active = true ORDERBY Name STARTPOSITION 1 MAXRESULTS 100 *** ** * ** *** ### 2.6 Refresh Access Token POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer Authorization: Basic Base64({clientId}:{clientSecret}) Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token={storedRefreshToken} *** ** * ** *** ## 3. Response Examples ### 3.1 Successful Create Response --- Account { "Account": { "Id": "36", "SyncToken": "0", "Name": "Operating Checking Account", "FullyQualifiedName": "Operating Checking Account", "SubAccount": false, "Active": true, "Classification": "Asset", "AccountType": "Bank", "AccountSubType": "Checking", "CurrentBalance": 0.00, "CurrentBalanceWithSubAccounts": 0.00, "CurrencyRef": { "value": "USD", "name": "United States Dollar" }, "domain": "QBO", "sparse": false, "MetaData": { "CreateTime": "2025-05-01T10:00:00-07:00", "LastUpdatedTime": "2025-05-01T10:00:00-07:00" } }, "time": "2025-05-01T10:00:00.000-07:00" } *** ** * ** *** ### 3.2 Successful Query Response { "QueryResponse": { "Account": [ { "Id": "36", "Name": "Operating Checking Account", "AccountType": "Bank", "AccountSubType": "Checking", "Active": true, "CurrentBalance": 1500.00, "CurrencyRef": { "value": "USD", "name": "United States Dollar" } } ], "startPosition": 1, "maxResults": 1, "totalCount": 1 }, "time": "2025-05-01T10:05:00.000-07:00" } *** ** * ** *** ### 3.3 Error Response Structure All errors are wrapped in a `Fault` object: { "Fault": { "type": "ValidationFault", "Error": [ { "code": "6240", "element": "Name", "Message": "Duplicate Name Exists Error", "Detail": "The name supplied already exists : " } ] }, "time": "2025-05-01T10:10:00.000-07:00" } **Fault Types:** | Fault Type | Description | |-----------------------|-------------------------------------------------------------------------------| | `ValidationFault` | Business rule violation (missing fields, duplicate names, invalid references) | | `SystemFault` | Internal QBO server error | | `AuthenticationFault` | Invalid, expired, or missing OAuth token | *** ** * ** *** ### 3.4 Token Exchange Response { "token_type": "bearer", "expires_in": 3600, "refresh_token": "AB11...", "x_refresh_token_expires_in": 8726400, "access_token": "eyJlbmMiOiJBMTI4Q0..." } > * **Access Token:** Expires in **1 hour** (3,600 seconds) > > * **Refresh Token:** Rotates every 24--26 hours; maximum lifetime **100 days** *** ** * ** *** ## 4. Error Codes ### 4.1 HTTP Status Codes | HTTP Status | Meaning | Action | |-----------------------------|--------------------------------------------|--------------------------------------| | `200 OK` | Request succeeded | Process response normally | | `400 Bad Request` | Malformed payload or non-UTF-8 characters | Validate and fix request body | | `401 Unauthorized` | Missing or expired access token | Refresh the access token | | `403 Forbidden` | Insufficient OAuth scopes | Re-authorize with correct scopes | | `429 Too Many Requests` | Rate limit exceeded (40 req/min per realm) | Implement exponential back-off | | `500 Internal Server Error` | QBO server error | Retry with back-off; log for support | | `503 Service Unavailable` | QBO temporarily unavailable | Retry after delay | *** ** * ** *** ### 4.2 QBO Application Error Codes These appear in the `Fault.Error[].code` field of the response body: | Error Code | Error Name | Fault Type | Description | |------------|-----------------------------|---------------------|-----------------------------------------------------------------------------| | `120` | Authorization Failure | AuthenticationFault | User lacks admin status or required permissions in QBO | | `500` | Unsupported Operation | ValidationFault | Request payload contains non-UTF-8 characters or unsupported operation | | `610` | Object Not Found | ValidationFault | Referenced object is inactive, deleted, or does not exist | | `2020` | Required Param Missing | ValidationFault | A required field is absent from the request body | | `2170` | Invalid Enumeration | ValidationFault | Field value is not in the allowed enumeration set | | `2500` | Invalid Reference ID | ValidationFault | Reference points to an inactive name-list object (`Active=false`) | | `5010` | Stale Object Error | ValidationFault | Concurrent update conflict --- `SyncToken` mismatch; re-fetch the record | | `6000` | Business Validation Error | ValidationFault | Transaction amount not set or other business rule violated | | `6140` | Duplicate Doc Num Error | ValidationFault | `DocNumber` already exists in QBO | | `6190` | Invalid Company Status | ValidationFault | Subscription period ended, canceled, or billing issue | | `6210` | Account Period Closed | ValidationFault | Accounting period is closed; books cannot be updated | | `6240` | Duplicate Name Exists Error | ValidationFault | `DisplayName` or `Name` already used for a customer/vendor/employee/account | | `6540` | Deposited Transaction Error | ValidationFault | Transaction has been deposited and cannot be modified | > **Full up-to-date list:** *** ** * ** *** ### 4.3 Common Handling Patterns | Scenario | Recommended Action | |----------------------------|-----------------------------------------------------------------------------| | `401` returned on any call | Call `refreshAccessToken()`; if refresh also fails, prompt re-authorization | | `5010` Stale Object | Re-fetch the record to get the latest `SyncToken`, then retry the update | | `6240` Duplicate Name | Query for the existing record by name and use upsert instead of create | | `6210` Period Closed | Surface error to the user; do not auto-retry | | `429` Rate Limit | Wait at least 60 seconds before retrying; implement jitter in batch jobs | *** ** * ** *** ## 5. Webhooks Webhooks allow QBO to push real-time notifications to your application whenever data changes in a connected company file. Your endpoint **must not** call back into QBO synchronously during the notification --- store the event and process it asynchronously. > **Migration Notice:** Intuit is migrating webhooks to the **CloudEvents 1.0** format. Migration deadline: **July 31, 2026**. All new integrations should use the CloudEvents format. *** ** * ** *** ### 5.1 Supported Entities \& Operations | Entity | Create | Update | Delete | Void | Merge | |----------------|--------|--------|--------|------|-------| | Account | ✓ | ✓ | ✓ | --- | --- | | Bill | ✓ | ✓ | ✓ | ✓ | --- | | Customer | ✓ | ✓ | ✓ | --- | ✓ | | Invoice | ✓ | ✓ | ✓ | ✓ | --- | | Item | ✓ | ✓ | ✓ | --- | --- | | Payment | ✓ | ✓ | ✓ | ✓ | --- | | Vendor | ✓ | ✓ | ✓ | --- | ✓ | | Sales Receipt | ✓ | ✓ | ✓ | --- | --- | | Payment Method | ✓ | ✓ | ✓ | --- | --- | > Refer to for the complete entity list. *** ** * ** *** ### 5.2 Legacy Payload Format { "eventNotifications": [ { "realmId": "1185883450", "dataChangeEvent": { "entities": [ { "name": "Customer", "id": "1", "operation": "Create", "lastUpdated": "2025-01-15T15:00:00-0700" }, { "name": "Invoice", "id": "142", "operation": "Update", "lastUpdated": "2025-01-15T15:05:00-0700" } ] } } ] } *** ** * ** *** ### 5.3 Webhook Setup (Developer Portal) 1. Log in to the Intuit Developer Portal → navigate to your app → **Webhooks** section. 2. Enter a publicly accessible **HTTPS** notification endpoint URL. 3. Select the entities and operations to subscribe to. 4. Copy the **Verifier Token** shown after saving (used for signature validation). 5. Click **Send Test Notification** to confirm your endpoint is reachable. 6. Repeat steps 2--5 separately for **Sandbox** and **Production** environments. **Endpoint requirements:** * Must use HTTPS (TLS 1.2 or higher) * Must be publicly accessible (no localhost) * Must return HTTP `200 OK` within the timeout window * Must handle duplicate delivery (implement idempotency using `id` field) *** ** * ** *** ## 6. Postman Collection Intuit maintains an official Postman collection covering all QBO Accounting API endpoints. | Resource | Link | |----------------------------------|------------------------------------------------------------------------------------------------| | **Postman Setup Guide** | | | **Intuit Postman Case Study** | | | **Help: Using Postman with QBO** | | *** ** * ** *** ### 6.1 Setup Steps **Step 1 --- Import the Collection** 1. Open the Postman Setup Guide linked above. 2. Click the **Run in Postman** button to fork the collection into your Postman workspace. **Step 2 --- Configure Environment Variables** Create a Postman Environment with the following variables: | Variable | Value | |-----------------|-----------------------------------------------------------------------------------------------------------| | `base_url` | `https://sandbox-quickbooks.api.intuit.com` (sandbox) or `https://quickbooks.api.intuit.com` (production) | | `company_id` | Your QBO Company Realm ID (realmId) | | `client_id` | App Client ID from Intuit Developer Portal | | `client_secret` | App Client Secret from Intuit Developer Portal | | `redirect_uri` | `https://cloudmaveninc.my.salesforce-sites.com/sms/QB_AuthVFPage` | | `access_token` | Populated after OAuth flow | | `refresh_token` | Populated after OAuth flow | | `minor_version` | `75` | **Step 3 --- Get an Access Token** The quickest method is to use the **Intuit OAuth 2.0 Playground** to generate an initial access token and refresh token, then paste them into your environment variables. Alternatively, configure OAuth 2.0 directly in Postman: 1. Open any request → **Authorization** tab → Type: **OAuth 2.0** 2. Set **Grant Type** to `Authorization Code` 3. Set **Auth URL** to `https://appcenter.intuit.com/connect/oauth2` 4. Set **Access Token URL** to `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` 5. Enter `client_id`, `client_secret`, `redirect_uri`, and `scope` (`com.intuit.quickbooks.accounting`) 6. Click **Get New Access Token** **Step 4 --- Make Your First Call** With the environment active and tokens set, open any request in the collection (e.g., `Get Company Info`) and click **Send** . The collection pre-populates `company_id` and `minor_version` from your environment. *** ** * ** *** ### 6.2 Quick-Test: Get Company Info GET {{base_url}}/v3/company/{{company_id}}/companyinfo/{{company_id}}?minorversion={{minor_version}} Authorization: Bearer {{access_token}} Accept: application/json A successful response confirms your token, `company_id`, and base URL are all correct before proceeding to write operations. *** ** * ** *** *This page is maintained by the Cloud Maven QuickBooks Connector team. For questions or corrections, contact* [*support@cloudmaveninc.com*](mailto:support@cloudmaveninc.com)*.*