Rest API features

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.

• 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 realmIdparameter 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 realmIdparameter 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.

Character encoding

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.

Request header fields

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

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"
   }
}

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

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.