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 ENVIRONMENT | URL |
Sandbox (development) | https://sandbox-quickbooks.api.intuit.com |
Production | https://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
:
1 | baseURL/company/1234/account
|
The realm ID is assigned to a company by Intuit when a QuickBooks Online user creates a company.
At runtime, an app can retrieve the realm ID in the following ways:
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.
java.util.UUID
or .NET System.GUID
.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:
baseURL/company/1234/invoice?requestid=4957
requestid
as the first request.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.)URI format
URIs are case sensitive.
OPERATION | URI |
Create and update | POST baseURL/v3/company/realmId/resourceName |
Single-object read | GET baseURL/v3/company/realmId/resourceName/entityID |
Multi-object read | GET baseURL/v3/company/realmId/query?query=selectStmt |
Delete | POST baseURL/v3/company/realmId/resourceName?operation=delete |
where:
COMPONENT | DESCRIPTION |
baseURL |
Initial path to the URI. The Base URL section contains the list of available paths. |
realmId |
The Intuit assigned unique Id of the QuickBooks company, also referred to as the companyID. For more information, see Realm ID. |
resourceName |
The name of the object upon which the operation is performed, such as account, customer, payments, or invoice. |
entityID |
The 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
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. |
Example
2015-07-24T10:33:39-07:00 |
This 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 QuickBooksOnline API REST requests.
Here is a sample POST request (the access token is masked).
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"
}
}
|
NAME | DESCRIPTION |
Accept: |
Optional. 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: |
Optional. 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: |
Required. 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: |
Optional. Length of the message (without the headers) according to RFC 2616. This header is used for POST operations. |
Content-Type: |
Required 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: |
Optional. 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 table below lists common HTTP header fields returned in QuickBooks Online API REST responses.
Here is the sample POST 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"
}
|
NAME | DESRIPTION |
Cache-Control: |
Used to specify directives that mustbe 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:
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 TYPE | REPRESENTATION | XML EXAMPLE | JSON EXAMPLE | NOTES |
Complex Type | Empty Node /Empty Object | <ShippAddr/> | “ShippAddr” : { } | |
Enum | Enum value | <EmailStatus>NotSet </EmailStatus> | “EmailStatus”:”NotSet” | Null or Empty not allowed. |
Boolean | Boolean: true/false | <Active>false<Active> | “Active”:”false” | Null or Empty not allowed. |
Date | Empty string: “” | <DueDate>”“</DueDate> | “DueDate”:”“ | |
Numeric types | 0 | <Amount>0</Amount> | “Amount”: 0 | |
String | Empty string: “” | <Description>”“</Description> | “Description”:”“ | |
Collection | Empty collection | <Line/> | “Line” : [ ] |
Deleting an object
The QuickBooks Online API implements two types of delete based on the type of entity.
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:
Id
and SyncToken
in the request body.Limits and throttles
QuickBooks Online API endpoints | Batch endpoint | |
---|---|---|
Sandbox servers |
|
|
Production servers |
|
|
If your app is accessing endpoints other than for the QuickBooks Online API, there is a combined limit of 800 requests per minute, per realm ID and app.
HTTP Status Code 429 will be returned when throttling occurs. Wait 60 seconds before retrying the request.
Any request taking longer than 120 seconds to execute will time out. This is especially important when determining how many payloads to include in a single batch request.
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.
Note
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 here.