References

1. Official API Reference

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:

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 : <Account Name>"
      }
    ]
  },
  "time": "2025-05-01T10:10:00.000-07:00"
}

Fault Types:

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

4.2 QBO Application Error Codes

These appear in the Fault.Error[].code field of the response body:

Full up-to-date list: https://developer.intuit.com/app/developer/qbo/docs/develop/troubleshooting/error-codes

4.3 Common Handling Patterns

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

Refer to https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks 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.

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:

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.