Making calls with the REST API

Here is a quick reference of REST API essentials that will help you get going with the QuickBooks Online API.  

Note

This information will help you construct requests and parse responses using our API. We recommend that you develop using our SDKs, which orchestrate these low level details into methods that will save you development time.

Base URLs

Working environmentURL
Sandbox (development) https://sandbox-quickbooks.api.intuit.com
Productionhttps://quickbooks.api.intuit.com

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

Identifiers

Here are some identifiers commonly used in the QuickBooks Online REST API. 

Realm ID

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

baseURL/company/1234/account

The realm ID is assigned to a company 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:

  • For OAuth 1.0a/OpenID 2.0:
    • From the realmId parameter returned on the callback URL passed in during the OAuth 1.0a connect begin sequence. For details, see Access Token Code.
    • From the authentication response when the user signs in with OpenID. For more information, see Requesting Authentication.
  • For OAuth 2.0/OpenID Connect:
    • From the ID token when the user signs in with OpenID Connect. For more information, see Verifying the ID token.
    • From the realmId parameter returned on the redirect URL passed in during the OAuth 2.0 authorization request. For details, see Authorization request.

Entity ID

An entity is a QuickBooks Online 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:

baseURL/company/<realmID>/entityName/entityID

The following URL requests the Customer object with ID 2123:

baseURL/company/1234/customer/2123

In a response, the ID is represented by the Id 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. The Request ID is specified as the query parameter, requestid, in the URI.

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.
  • 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 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:
    baseURL/company/1234/invoice?requestid=4957
  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.

URI format

URIs are case sensitive. 

OperationURI
Create and updatePOST baseURL/v3/company/realmID/resourceName
Single-object readGET baseURL/v3/company/realmID/resourceName/entityID
Multi-object readGET baseURL/v3/company/realmID/query?query=selectStmt
DeletePOST baseURL/v3/company/realmID/resourceName?operation=delete

where:

ComponentDescription
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.
resourceNameThe name of the object upon which the operation is performed, such as account, customer, payments, or invoice.
entityIDThe ID identifying the specific instance of the object. For more information, see EntityID.
 

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 QuickBooks Online API Reference clearly notes read-only attributes. 

Time stamps and time zones

Time stamps returned in QuickBooks Online 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.

Example

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. 

Request header fields

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

Click here for a 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
Host: quickbooks.api.intuit.com
User-Agent: APIExplorer

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

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 QuickBooks Online 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. This header is required for all requests. Represents 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.
Content-Length:Length of the message (without the headers) according to RFC 2616. This header is used for POST operations. 
Content-Type:

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.

Response header fields

The following table lists common HTTP header fields returned in QuickBooks Online 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"
}
NameDescription
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.
Content-Type:

The MIME type of this response. Use application/json for most API interactions with Intuit services. Some QuickBooks Online 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. 
intuit_tid:

Log this value if returned in with the response, as it enables Intuit Developer support staff to trace requests from your app through our systems to help resolve issues. Returned with QuickBooks Online API responses.

Keep-Alive:

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 QuickBooks Online API responses.
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.
Vary:

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.

Operations

This section describes some basic operations supported by the QuickBooks Online API.

Batch operations

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.

Updating an object

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 specified 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>
"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" : [ ] 

Deleting an object

The QuickBooks Online 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.

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.
  • All other QuickBooks Online API endpoints—Throttled to 500 requests per minute per realm ID.

Sandbox servers

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:

 Got Questions? Get Answers in our developer forums.