Learn about basic REST API features

The QuickBooks Online Accounting API is based on the REST framework. Here’s a quick guide for relevant REST features, operations, formats, and attributes.

Tip: We highly recommend you develop your app using one of our SDKs. They automate many processes and steps you’d otherwise have to code manually.
General REST API info
Base URLs for QuickBooks the Online Accounting API
Working environment URL
For sandbox company and testing (development) https://sandbox-quickbooks.api.intuit.com
For production apps https://quickbooks.api.intuit.com
Tip: Replace the baseURL placeholder with one of these base urls when you see them in sample queries or examples in our documentation.
URI formats for operations
Operation URI
Create and update POST baseURL/v3/company/realmId/resourceName
Read (single-entity) GET baseURL/v3/company/realmId/resourceName/entityID
Read (multi-entity) GET baseURL/v3/company/realmId/query?query=selectStmt
Delete POST baseURL/v3/company/realmId/resourceName?operation=delete
Common request header fields

These are common HTTP header fields for requests.

Field name Description Required
Accept The acceptable content-type for server responses. Used for operations that return a response body. Use application/json fo most API interactions. In a few cases, you can also use application/pdf to return some transaction entities in PDF format. Individual entity references in the API Explorer notes the supported content types. Optional
Accept-Encoding The The desired content-coding in the response. This is set by the request library in use if that library supports compression. In most cases, you should set a parameter in your network library indicating you want responses to be compressed, rather than setting the header manually. This can significantly improve the perceived performance of your app. It dramatically reduces the size of response data. Optional
Authorization The authentication credentials for HTTP authentication. This header is required for all requests. It represents the end-user’s permission to let your app share access to their QuickBooks Online company data. Learn how to implement OAuth 2.0 and create this value. Required
Content-Length Length of the message (without the headers) according to RFC 2616. This header is used for POST operations. Optional
Content-Type The MIME type of the request body. This header is used for POST operations. Use application/json for all API interactions. Required for POST operations
Host The domain name of the server for the request. This is set by the request library in use. See Base URLs for valid values. Optional

See an example POST request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
POST /v3/company/12345678/invoice HTTP/1.1
Host: quickbooks.api.intuit.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJlbmMiOiJ**************xPfzFFw
Host: quickbooks.api.intuit.com

​{
   "Line": [
      {
         "Amount": 100.00,
         "DetailType": "SalesItemLineDetail",
         "SalesItemLineDetail": {
            "ItemRef": {
               "value": "1",
               "name": "Services"
            }
         }
      }
   ],
   "CustomerRef": {
      "value": "1"
   }
}

This example masks the access token.

Common server response header fields

These are common HTTP header fields for responses from our servers.

Field name Description
Cache-Control Specifies directives that must be obeyed by all caching mechanisms along the request-response chain.
Connection Control options for the current connection and list of hop-by-hop response fields.
Content-Type Defines the MIME type of the response.
Date Gives the date and time for service responses. Defined by RFC 7131 date/time format.
Expires Gives the date/time when the response is considered stale.
intuit_tid Indicates errors or issues. Tip: If you see this value in the response, log it. It will help our support team quickly identify the issue.
Keep-Alive Indicates of the HTTPS channel can be kept “alive” (open) to improve performance on subsequent requests. This is managed by the underlying networking library of the language.
QBO-Version Specifies the version of our services that processed the request.
Server Specifies the server handling the request. Tip: If there’s ever an issue, our support staff can quickly determine whether there are issues with a specific server.
Strict-Transport-Security A HSTS Policy informing the HTTP client how long to cache the HTTPS only policy, and whether this policy applies to subdomains.
Transfer-Encoding Specifies the encoding used to safely transfer the API response data to the app making the API call for the given entity. Current methods: chunked, compress, deflate, gzip, identity.
Vary Tells downstream proxies how to match future request headers. This decides if the cached response can be used, rather than requesting a fresh one from the origin server.
Via Informs the client if the response was sent through any proxies.

See an example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Date: Thu, 07 Jan 2016 17:19:22 GMT
Expires: 0
intuit_tid: gw-756b01cf-3fe0-4414-a2a2-321dd2287b7b
Keep-Alive: timeout=5
QBO-Version: 1512.462
Server: nginx/1.8.0
Strict-Transport-Security: max-age=15552000
Transfer-Encoding: chunked
Vary: Accept-Encoding
Via: 1.1 ipp-gateway-ap05

{
 "Invoice": {
...

 },
 "time": "2016-01-07T09:19:21.923-08:00"
}
Common QuickBooks Online Accounting API terminology
Realm ID

This identifies a unique, individual QuickBooks Online company file. We assign realm IDs when QuickBooks Online users create their company file.

Tip: Realm IDs and company IDs are the same number.

Realm IDs are specified in the URI of every API request. Here’s an example:

1
baseURL/company/1234/account

In this case, the realm ID is 1234.

At runtime, apps can retrieve realm IDs in the few ways:


Entity ID

This identifies individual instances of API entities such as an account, charge, or estimate. We assign this value to the entityID field.

To call entities by their entity ID, use the read operation and specify the entity ID in the URL. Use the following format and treat entity IDs as strings: baseURL/company/<realmId>/entityName/entityID.

Here’s an example:

1
baseURL/company/1234/customer/2123

In this case, the entity ID for this customer entity is 2123.


Request ID

This identifies specific HTTP requests sent from apps to our servers. Request IDs let apps correlate requests and responses.

Request IDs are especially useful in cases where apps need to resend requests due to a dropped connection, or didn’t receive a response from the server. We strongly recommend you use request IDs for requests that write, modify, or delete data. This guarantees idempotence. If our service receives another request with the same request ID, instead of performing the operation again or returning an error, it can recognize and send the same response for the original request. This prevents duplication.

Use query parameter requestid in the URI of requests to specify request IDs.

Here are a few things to keep in mind:

This example scenario demonstrates why request IDs are important:

  1. An app sends a request to create an invoice. It specifies “4957” for the request ID like this: baseURL/company/1234/invoice?requestid=4957
  2. Our service processes the request and sends a response.
  3. The app loses its connection and doesn’t receive a response.
  4. The app sends the same request again, specifying the same content and request ID.
  5. Our server already has the requestid. It can determine that the subsequent request is the same.
  6. Our server sends the same response as in step 2.
  7. The app receives the response and verifies it contains no errors.

If the app hadn’t specified a request ID, the server would create a duplicate invoice with a new entity ID.


Resource name

This is the name of the API entity, such as the account, customer, payments, or invoice entities.

Learn more about QuickBooks Online Accounting API resources and entities.

Updating on read-only attributes

Any value supplied in a read-only attribute is transient and silently overwritten by QuickBooks data services, as appropriate to the attribute. No error is returned.

Learn more about updating read only attributes.

Character encoding

US versions of QuickBooks Online support ISO-8859-1 (extended ASCII) character encoding.

Non-US versions of QuickBooks Online support UTF-8 character encoding.

Timestamps and time zones

Timestamps returned in QuickBooks Online Accounting API response payloads and webhooks notifications are in DateTime format. This conforms to the iCal date/time format, as defined in RFC 2445.

The basic format is <date>T<time><UTC offset>

date The UTC date in the format YYYY-MM-DD.
time The UTC time in the format HH:MM:SS.
UTC offset The UTC offset to apply for time zone correction in the format +/-HH:MM.

Here’s an example timestamp: 2015-07-24T10:33:39-07:00.

This represents 03:33:39 on 24 July 2015, in a time zone west of UTC by 07:00 hours.

API call limits and throttles
Server QuickBooks Online API endpoints Batch endpoint
Sandbox servers
  • 500 requests per minute, per realm ID.
  • Recommended maximum number of payloads in a single batch request is 30.
  • Throttled at 40 requests per minute, per realm ID.
Production servers
  • 500 requests per minute, per realm ID.
  • 10 concurrent requests per realm ID and app.
  • Recommended maximum number of payloads in a single batch request is 30.
  • Throttled at 40 requests per minute, per realm ID.
Note: Requests are performed in a mutli-threaded environment. They may experience timing issues leading to unexpected results.
QuickBooks Online API XML schema definitions (XSDs)

The current version of the QuickBooks Online Accounting API supports minor versions. This lets you access incremental changes and continue using specific versions of API entities so you don’t break existing apps.

Here’s how to access minor versions.