REST API quick reference

Here is a quick reference of REST API essentials that will help you get going with the QuickBooks Online API.  The QuickBooks API includes two domains: Accounting API and Payments API. The topics listed below are presented for both of these domains.


This information assumes you are familiar with REST API principles and the mechanics of constructing requests and parsing responses. However, we recommend using our SDKs for app development, which orchestrate these low level details into methods that do the heavy lifting for you.

Base URLs

Working environmentAccounting APIPayments API
Sandbox (development)

In the sections below, substitute the appropriate URL where noted with the baseURL placeholder.

URI format

Accounting APIPayments API
Create and update
POST baseURL/v3/company/realmID/resourceNamePOST baseURL/quickbooks/v4/resourceName
Single-object read
GET baseURL/v3/company/realmID/resourceName/entityIDGET baseURL/quickbooks/v4/resourceName
Multi-object read
GET baseURL/v3/company/realmID/query?query=selectStmtGET baseURL/quickbooks/v4/resourceName
POST baseURL/v3/company/realmID/resourceName?operation=deleteDELETE baseURL/quickbooks/v4/resourceName


baseURLInitial path to the URI. The Base URL section contains the list of available paths.
realmIDThe Intuit assigned unique Id of the QuickBooks company, also referred to as the companyID.  For more information, see Realm ID. For use with Accounting API, only.
resourceNameThe name of the object upon which the operation is performed, such as account, customer, payments, or invoice.
entityIDThe ID identifying the specfic instance of the object. For more information, see EntityID. For use with Accounting API, only.

URIs are case sensitive. 

Character encoding

Apps for US editions of QuickBooks Online support ISO-8859-1 (extended ASCII) character encoding. Apps for non-US editions of QuickBooks Online support UTF-8 character encoding.

Read-only attributes

Any value supplied in a read-only attribute is transient and is silently overwritten by QuickBooks data services, as appropriate to the attribute. No error is returned. The API Reference Guide for both Accounting and Payments clearly notes read-only attributes. 

Time stamps and time zones

Time stamps returned in QuickBooks API response payloads and webhooks notifications are in DateTime format and conform to the iCal date/time format, as defined in RFC 2445. The basic format is <date>T<time><UTC offset>, where

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


2015-07-24T10:33:39-07:00This DateTime time stamp represents 03:33:39 on 24 July 2015 in a time zone west of UTC by 07:00 hours, such as Pacific Daylight Time. The authorization header

The authorization header

This section provides details for the OAuth authorization header, which you supply with each call to the QuickBooks API. Click here to help you determine the version of OAuth your app uses.

OAuth 2.0

Here is a sample HTTP authorization header for OAuth 2.0 that is included with QuickBooks API requests. It has been shortened and formatted for legibility.  


These details are provided for information, only.  Details for calculating the authorization Bearer access token can be found here. We strongly recommend that you not attempt to generate the access token manually, but rather use a sample implementation as appropriate to your language. 

Authorization=Bearer eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..eF2J3XEDnGBjpO469rw9Dw.Gi3Oc
  ... s-rQb2D_PX8dIYb5g

Sample Value

AuthorizationRepresents the user's permission to share access to their company data with your app. See Implementing OAuth 2.0 for information on creating this value.Bearer eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoi
ZGlyIn0..eF2J3XEDnGBjpO469rw9Dw.Gi3Oc ... s-rQb

OAuth 1.0a

For apps using OAuth 1.0a authorization click here to see header details.

Here is a sample HTTP authorization header for OAuth 1.0a that is included with QuickBooks API requests. Normally, all fields of the header need to be on one line, but it has been formatted for legibility.  


These details are provided for information, only.  The value of the oauth_signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. If you miscalculate the signature base string, the signature generated by your app and our servers differs and your request is rejected.  We strongly recommend that you not attempt to generate the signature base string and signature manually, but rather use one of several OAuth community resources as appropriate to your language. 

Authorization :   OAuth   oauth_token="************",

The header contains key/value pairs, where each key begins with the string oauth_.   

Of note:

  • All keys and values are URL encoded when building up the authorization header. Click here for more information about URL encoding.
  • The parameter order must be as shown in the text above to generate a valid matching signature.

Sample Value

oauth_tokenRepresents the user's permission to share access to their company data with your app. See Access Token Code for information on creating this value.


oauth_nonceA unique token your app generates for each request.8cc14a18-...cc785172c

Identifies which app is making the request. Obtain this value from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key:

  • Development key—use only in the sandbox environment.
  • Production key—use only in the production environment. 
oauth_signature_methodThe OAuth signature method used by QuickBooks Data Services is HMAC-SHA1.HMAC-SHA1

This value is the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages.


oauth_versionThe OAuth version and is always set to
oauth_signatureA unique string your app generates for each request. Do not attempt to generate this value manually, but rather use one of several OAuth community resources as appropriate to your language.

URL encoded: QsbJk%2BAtr...5NuiDY%3D

Request header fields

The following table lists common HTTP header fields used in various types of QuickBooks API REST requests.

Click here for sample POST request.
POST /v3/company/1029354210/invoice HTTP/1.1
Authorization: OAuth oauth_consumer_key="qyprdrr*************nnYtp", oauth_nonce="nOE7oSycsIAYjkJq7G4F7ASedKc4yIPd", oauth_signature="cJnrSEG*********OkhbQG4%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1452102114", oauth_token="qyprdI4XnaU3*********Rnj9978w1H8GLmb99DtU6qv", oauth_version="1.0"
Accept: application/json
Content-Type: application/json
Content-Length: 278
User-Agent: APIExplorer

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

Content-Type that is acceptable for the response.  Used for operations that return a response body. Use application/json for most API interactions with Intuit services. Some Accounting API transaction objects can be returned in PDF format by using application/pdf. The API Reference Guide notes the supported content type for a given endpoint.

Accept-Encoding:The desired content-coding in the response. This is set by the request library in use if that library supports compression.  At most you should have to set a parameter in your network library to indicate you want responses to be compressed, rather than setting the header manually.  This can significantly improve the perceived performance of your application when interacting with Intuit APIs as it dramatically reduces the size of response data.
Authorization:Authentication credentials for HTTP authentication. The information required for request OAuth authentication. For more information see The authorization header. This header is required for all requests.
Content-Length:Length of the message (without the headers) according to RFC 2616. This header is used for POST operations. 

The MIME type of the request body. This header is used for POST operations. Use application/json for all API interactions with Intuit services.

Host:The domain name of the server to use for the request. See Base URLs for valid values. This is set by the request library in use.
Request-ID:App-supplied integer to support idempotency for Payments API requests that process POST and DELETE operations. Not applicable for Accounting API Requests.

Response header fields

The following table lists common HTTP header fields returned in QuickBooks API REST responses.

Click here for sample POST response.
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"
Cache-Control:Used to specify 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.

The MIME type of this response. Use application/json for most API interactions with Intuit services. Some Accounting API transaction objects are returned in PDF format by using application/pdf.

Date:The date and time QuickBooks Online services responses as defined by RFC 7131 Date/Time format.
Expires:Gives the date/time after which the response is considered stale. 

Log this value if returned in with the respone, as it enables Intuit Developer support staff to trace requests from your app through our systems to help resolve issues. Returned with Accounting API responses. Not applicable for Payment API.


Indicates 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:The version of QuickBooks Online services that processed the request. Returned with Accounting API responses. Not applicable for Payment API.
Server:The server handling the request. In the event of a problem, Intuit Developer support staff can identify quickly if issues are occurring on specific servers, etc. to help troubleshoot.
Strict-Transport-Security:A HSTS Policy informing the HTTP client how long to cache the HTTPS only policy and whether this applies to subdomains.
Transfer-Encoding:The form of encoding used to safely transfer the entity to the user. Currently defined methods are: chunked, compress, deflate, gzip, identity.

Tells downstream proxies how to match future request headers to decide whether the cached response can be used rather than requesting a fresh one from the origin server.

Via:Informs the client of proxies through which the response was sent.

Error handling

As best practice in the event of an error, log the request that generated the error and the response received. Potentially sensitive info (like a credit card number) should be masked when logged. 

Accounting API

Find information about error handling and error codes here.

Payments API

Find information about error handling and error codes here.

Batch operations

Accounting API

The batch operation enables an application to perform multiple operations in a single request.  For example, in a single batch request an application can create a customer, update an invoice, and read an account.  Compared to multiple requests, a single batch request can improve an application's performance by decreasing network roundtrips and increasing throughput. See the Batch API reference for complete details.

Payments API

The Payments API does not support batch operations.

Multi-object read

Accounting API

Retrieve multiple objects with one request via the query endpoint.

  • Query support is available with most resources.  Refer to individual resource documentation in the the Accounting API Reference Guide for further information about query support.
  • See Querying data for general information about forming a guided queries. 

Payments API

Multi-object query support varies based on the resource.  When supported, it is provided as an orchestrated request rather than using the query endpoint explicitly.  See the Payments API Reference Guide for details.

Updating an object

Accounting API

Full update

The full update operation updates all writable attributes of an existing entity. If a writable attribute is omitted from the request body, then this operation sets the property's value to NULL.  The ID of the entity to update is specified in the request body with the Id attribute. Any value supplied in a read-only or input-only attribute is transient and is silently overwritten by QuickBooks data services, as appropriate to the attribute. 

In cases where it is desired to specify just a subset of properties in the update request, without clearing the omitted ones, consider the sparse update operation.

Sparse update

The sparse update operation provides the ability to update a subset of attributes for a given object; only those specified in the request are updated. Missing attributes are left untouched. This is in contrast to the full update operation, where elements missing from the request are cleared. Considerations for using sparse updating include:

  • Prevent unintended overwrites: A client application often does not use all the fields of an entity, so when it sends a full update request  with only fields they use, it results in an erroneous blanking out of fields that were not sent.
  • Reduce request payload: Always desired, but is more relevant when the client application is mobile because of lower speeds, spotty connections, and the fact that mobile users are sensitive to amount of data usage in each billing cycle.
  • Facilitate future field additions: New fields can be added to an entity without past versions of production applications clearing all other existing fields inadvertently, as would happen with a full update operation.

This operation updates the writable properties that are specifed in the request body.  The request body must include the sparse="true" attribute.

Using sparse update to clear a field

The table below shows how to explicitly clear a field with sparse update.  

Field TypeRepresentationXML ExampleJSON ExampleNotes
Complex TypeEmpty Node /Empty Object<ShippAddr/> "ShippAddr" : { } 
EnumEnum value<EmailStatus>NotSet
"EmailStatus":"NotSet"Null or Empty not allowed. 
BooleanBoolean: true/false<Active>false<Active>"Active":"false"Null or Empty not allowed. 
DateEmpty string: ""<DueDate>""</DueDate>"DueDate":"" 
Numeric types0<Amount>0</Amount>"Amount": 0 
StringEmpty string: ""<Description>""</Description>"Description":"" 
CollectionEmpty collection<Line/>"Line" : [ ] 

Payments API

The Payments API does not directly support the update operation. 

Deleting an object

Accounting API

The Accounting API implements two types of delete based on the type of entity.

  • Soft delete for name list objects—this has the effect of deactiving the object; it can be reactivated
  • Hard delete for transaction objects—this has the effect of deleting the object; it cannot be recovered.

The documentation for each entity clearly states the type of delete supported.

Soft delete

This operation marks the object as inactive and is available for name list entities, only. In this type of delete, the record is not permanently deleted, but it is hidden for display purposes. References to inactive objects are left intact. Soft delete is achieved by invoking the update operation for the object with the Active attribute set to false in the object update request; thus, making it inactive.

When an object is created, it is always in an active state. Additionally, an object whose state is inactive can be updated to make it active again. Generally, when you query entities with no filters, only active entities are returned.

Hard delete

This operation deletes the object specified in the request body and is available for transaction entities, only.  After the object is deleted it cannot be recovered. Based on the particular type of object, the request body is structured in one of two ways:

  • Simplified delete—For Bill, BillPayment, CreditMemo, Estimate, Invoice, JournalEntry, Payment, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TimeActivity, and VendorCredit simply supply the Id and SyncToken in the request  body. 
  • Traditional delete—For all other transaction entities, the request body must include the full payload of the object as returned in a read response.

Payments API

Where delete is supported for a given resource, use the REST operation, DELETE, on the object. This has the effect of voiding an unposted payment and refunding a posted payment. Consult the Payments API Reference guide for details about individual resource delete support.

Realm ID

Accounting API

The realm ID (formerly called company ID) uniquely identifies the data of a QuickBooks company and is specified in the URI of every Accounting API request.  For example, in the following URI the realm ID is 1234:


The realm ID is assigned by Intuit when a QuickBooks Online user creates a company.    

  • QuickBooks Online displays the realmID as the company ID on the Billing & Subscription page of Account and Settings for your company. 
  • At runtime, an app can retrieve the realm ID in the following ways:
    • From the realmId parameter returned on the callback URL passed in during the OAuth connect begin sequence. For details, see Access Token Code.
    • From the authentication response when the user signs in with OpenID. For more information, see Verify Authentication Response.

Payments API

The Payments API does not specify a realmID in endpoint URIs.

Customer ID

Accounting API

The Accounting API does not specify a customer ID in endpoint URIs.

Payments API

Some Payments API resources include a customer ID in their URI. This is an app-defined value based on its internal method for managing customers. For example, in the following URI the customer ID is 456456:


Entity ID

An entity is a QuickBooks object such as an Account, charges, or Estimate.  Assigned by Intuit, this ID uniquely identifies an instance of an object. Your code should treat this as a string.  To get an entity by ID, call the read operation and specify the entity ID in the URL as follows:


The following URL requests the Customer object with ID 2123:


In a response, the ID is represented by the Id (Accounting API) or id (Payment API) attribute.

Request ID

The request ID uniquely identifies the HTTP request sent from the app to the service. It enables the app to correlate requests and responses in case the app needs to resend a request because of a dropped connection or other situation in which a write, modify, or delete request has been sent, but no response received. Use of the request ID is strongly recommended for any request that writes, modifies, or deletes data as it guarantees idempotency of the request. 

  • Account API—Request ID is specified as the query parameter, requestid, in URI.
  • Payment API—Request ID is specified as the header field, Request-ID, in the HTTP request.

The app specifies the request ID as part of the request.  If the service receives another request with the same ID, instead of performing the operation again or returning an error, the service sends the same response as it did for the original request.

  • The request ID your app specifies must be unique for all requests for a given company.
  • The request ID can have a maximum of 50 characters for all operations except batch.
  • To avoid duplicate IDs, the app is responsible for generating a unique ID for each request. It is recommended to generate values with a library such as java.util.UUID or .NET System.GUID.

Additionally, for the Accounting API:

  • For batch operations, the requestid supports a maximum of 36 characters. For each batch ID, only 10 characters are allowed when request ID is also specified.  Use when the batch operation is limited to transaction requests. Results are undefined when name list resource requests (for examples. Customer, Item, and so on) are included.

The following scenario (with the Accounting API) shows how an app might use the request ID in a create operation:

  1. The app sends a request to create an invoice, specifying 4957 for the request ID:
  2. The service processes the request to create the invoice.
  3. The app loses its connection and does not receive the response.
  4. The app sends the request to create the invoice again, specifying the same content and requestid as the first request.
  5. The service determines that the requestid has been sent before, so it sends the same response as in step 2.  (If the app had not specified a request id, the service would create a duplicate invoice with a new entity ID.)
  6. The app receives the response and verifies that it contains no errors.

Object status

Accounting API

The object status is returned in the response body. The table below lists possible status values and their description.

DeletedObject has been deleted from database. Applicable only to transaction entities.
VoidedObject has been voided from an accounting perspective.

Payments API

Payments API object response bodies do not include status.

Limits and throttles

Below are limits and throttles currently in place for accessing QuickBooks Online data services.

Multi-threading limits

Updates and additions to name list entities must be performed serially. Updates and additions performed in a mutli-threaded enviroment may experience timing issues and lead to unexpected results.  

Throttle limits

Production servers

  • Reports API endpoints—Throttled to 200 requests per minute per realm ID.
  • Payments API endpoints—Throttled to 40 requests per minute per app.
  • All other Accounting API endpoints—Throttled to 500 requests per minute per realm ID.

Sandbox servers

  • Payments API endpoints—Throttled to 40 requests per minute per app.
  • All other Accounting API endpoints—Requests are throttled at 100 requests per minute per individual app. For complete information about sandbox environments, click here.

Request and response limits

  • The maximum number of batch items in a single request is 30.
  • The maximum number of entities returned in a query response is 1000. To handle more than 1000, fetch the entities in chunks, as described in Pagination.

QuickBooks API XSDs

QuickBooks Online V3 data services support minor versions in order to provide a way for you to access incremental changes without breaking existing apps. Based on the minor version of interest, access its corresponding XSD from the table below.

Click here for minor version information and corresponding XSDs.

Based on the minor version of interest, access its corresponding XSD from the table below, where:

  • Release Date:  The date on which features for the minor version are available by request.  Service requests must explicitly include the version number number in order to access that version's features; otherwise, access is limited to generally available features.
  • Minimum SDK Version: The version of the SDK that defaults to the given minor version.
Minor VersionRelease
Minimum SDK VersionNew Features
12June 30, 2017Java: 2.9.6

Includes all minor versions 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, and 11, plus the addition of the following:

  • Support for VendorCredit.Balance field.

-XSD: v3 minor version 12

11May 27, 2017

Java: 2.9.3
.NET: 3.1.0
PHP: 3.2.6

Includes all minor versions 1, 2, 3, 4, 5, 6, 7, 8, 9, and 10, plus the addition of the following:

  • Support for CompanyInfo sparse update.
  • Validation on CompanyInfo.CompanyAddr field.

-XSD: v3 minor version 11

10April 25, 2017

Java: 2.9.3
.NET: 3.1.0

Includes all minor versions 1, 2, 3, 4, 5, 6, 7, 8, and 9, plus the addition of the following:

-XSD: v3 minor version 10

9April 25, 2017

Java: 2.9.3
.NET: 3.1.0

Includes all minor versions 1, 2, 3, 4, 5, 6, 7 and 8, plus the addition of the following:

-XSD: v3 minor version 9

8November 15, 2016

Java: 2.7.1
.NET: 2.8.0
PHP: 3.2.4

Includes all minor versions 1, 2, 3, 4, 5, 6, and 7, plus the addition of the following:

  • Support for carbon copy and blind carbon copy email addresses in Invoice objects.

-XSD: v3 minor version 8

7Internal, only.  
6February 17, 2016Java: 2.5.0
.NET: 2.4.0
PHP:  2.2.0

Includes all minor versions 1, 2, 3, 4, and 5, plus the addition of the following:

-XSD: v3 minor version 6

5December 18,2015 Java: 2.4.0
.NET: 2.4.0
PHP:  2.5.0

Includes all minor version 1, minor version 2, minor version 3, and minor version 4 plus the addition of the following:

-XSD: V3 minor version 5

Phase 1—September 24, 2015


Java: 2.4.0
.NET: 2.4.0
PHP:  2.2.0 

Includes all minor version 1, minor version 2, and minor version 3 plus the addition of the following:

In support of enhanced inventory, the following are added to the Item resource:

  • Item.Sku attribute.
  • NonInventory to the list of valid Item.Type selections.
  • Support for line-level discounts with the DiscountAmt and DiscountRate attributes in a SalesLineDetail element for FR locales. 

Phase 2—November 19, 2015

Java: 2.4.0
.NET: 2.4.0
PHP:  2.2.0 

Includes all minor version 1, minor version 2, minor version 3, and phase 1 of minor version 4 plus the addition of the following:

  • Images with item objects, via the Attachable resource. See Adding attachments to an object for details.
  • Item hierarchies with the Category item type.
  • Support for transaction-level tax calculations with the TxnTaxDetail element in Deposit objects for non-US locales.

-XSD: V3 minor version 4

3  Phase 1—May 29, 2015Java: 2.4.0
.NET: 2.4.0
PHP:  2.2.0

Includes all minor version 1 and minor version 2 plus the addition of the following:

Reports APIs

  • Reports API response for General Ledger report hierarchy is broken in certain circumstances when there are sub accounts configured in the QuickBooks Online company.
Phase 2—August 11, 2015Java: 2.4.0
.NET: 2.4.0
PHP:  2.2.0

Includes all minor version 1, minor version 2, and phase 1 of minor version 3 plus the addition of the following:

Transaction entities:

Phase 3—August 27, 2015Java: 2.4.0
.NET: 2.4.0
PHP:  2.2.0

Includes all minor version 1, minor version 2, and phases 1 and 2 of minor version 3 plus the addition of the following:

Transaction entities:

  • Account.TaxCodeRef attribute to specify the default tax code used for the account—available for global locales, only.

-XSD: V3 minor version 3

2March 25 2015PHP: 2.1.0

Minor version 2 includes all minor version 1 items plus the addition of the following:

Reports APIs for detailed report types:

  • Addition of ColKey metadata in report header which provides sub-classification of ColType.
  • Date format of YYYY-MM-DD is used instead of that defined in company preferences. This will be generally available in QuickBooks Online services v85.

Transaction entities:

  • Transaction tax type as defined in company setting is now used instead of always defaulting to Exclusive. (international QBO only). Further information to be provided.

-XSD: V3 minor version 2

1March 7 2014Java: 2.1.2
.NET: 2.0.4
PHP:  2.0.4

-Addition of TaxInclusiveAmt attribute Line.SalesItemLineDetail, Line.ItemBasedExpenseLineDetail, and Line.AccountBasedExpenseLineDetail line types.  Available for international editions of QBO, only.

-Addition of TotalAmt and HomeTotalAmt (international QBO only) attributes to JournalEntry entity.

-XSD: V3 minor version 1

pre-1Legacy V3Java: <=2.1.0
.NET: 2.0.0
PHP:  2.0.0
Legacy V3

 Got Questions? Get Answers in our developer forums.