Basic ID and field definitions for the QuickBooks Online Accounting API

Here are common IDs and data fields you may see during development. These appear frequently for various features and implementations.

• appID (also known as App ID) : The unique identifier for an app you created on the Intuit Developer Portal. To find an app’s ID, sign in to the developer portal. Then select the Dashboard link in the toolbar.
• clientID (also known as client ID) : A unique string that publically identifies an app using OAuth2.0. It’s used by clients (i.e. users) connecting to apps.
• clientSecret (also known as client secret) : A randomized string that privately identifies an app using OAuth2.0. The value is only known by the app, it’s developer, and our authorization services.
• realmID (also known as companyID) : An ID that identifies an individual QuickBooks Online company. Users commonly have multiple QuickBooks Online companies. The realmID identifies each one. Many users know this as a “company ID.” It’s this same value as the realm ID.
• Permalink : The URL for your app’s page on the QuickBooks App Store. For example: https://apps.intuit.com/AccountingApp.

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

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:

• From the ID token generated when users sign in with OpenID Connect. Learn more about verifying the ID token.
• From the realmId parameter on the redirect URL passed during the OAuth 2.0 authorization request. Learn more about authorization requests.

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.

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:

• The request ID your app specifies must be unique for all requests for a given QuickBooks Online company file (as specified by the realm ID).
• The request ID can have a maximum of 50 characters for all operations, except for batch operations.
• For batch operations, the requestid can have a maximum of 36 characters. For each batch ID, only 10 characters are allowed when the request ID is also specified.
• For a batch request, both the request ID and batch ID must be the same as the original request ID and batch ID in order for the request to be unique. If you pass the same request ID but different batch IDs, they will be considered to be different requests when retried.
• To avoid duplication, your app is responsible for generating unique request IDs. We recommend using a library such as java.util.UUID or .NET System.GUID to generate these values.

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.

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.

Every transaction entity in the QuickBooks Online v3 API — Invoice, Payment, SalesReceipt, CreditMemo, Estimate, and others — includes a DocNumber field. This is the document number visible in the QuickBooks UI, for example “Invoice #1042”.

DocNumber is:

• A string of up to 21 characters
• Scoped per realm (company) and transaction type — the same value can exist on an Invoice and a Payment without conflict, but two Invoices in the same company cannot share one (depending on settings)
• Optional on create — if omitted, QuickBooks auto-assigns the next sequential number

If you do not include DocNumber in a Create request, the platform follows this logic:

1. Company has “Automatic Transaction Numbers” enabled (default for most companies): QuickBooks Online auto-assigns the next sequential number from that company’s counter. For example, if the last invoice was 1041, the new one gets 1042. Every Create request — including retried ones — gets a new unique number and creates a new transaction. There is no deduplication.
2. Company has “Custom Transaction Numbers” enabled: DocNumber is left null. Every Create request creates a new transaction. No deduplication occurs.

Generate a meaningful, stable DocNumber in your system before making the API call — for example, your internal order ID or invoice number.

1
2
3
4
5

POST /v3/company/{realmId}/invoice
{
  "DocNumber": "ORD-2024-98765",
  "Line": [...]
}

• If the request succeeds: the invoice is created with DocNumber = "ORD-2024-98765".
• If the request fails with a network error or 5xx: before retrying, query first (see Pattern 2).
• If the request fails with a 4xx validation error: the transaction was not created — you can retry after fixing the payload.

Before retrying a failed Create, check whether the transaction already exists using a query:

1

GET /v3/company/{realmId}/query?query=SELECT * FROM Invoice WHERE DocNumber = 'ORD-2024-98765'

• If the query returns a result: the first attempt succeeded. Use the returned Id — do not create again.
• If the query returns empty: the first attempt failed before saving. Safe to retry the Create.

This is the most reliable way to implement idempotent behavior on top of the QuickBooks Online API.

Use a prefix that identifies your integration (for example, APP- or your app’s short name). This makes it easy to:

• Query for transactions created by your app
• Avoid conflicts with numbers the company owner manually creates in the QuickBooks UI
• Debug duplicate issues quickly

1

"DocNumber": "MYAPP-INV-20240315-001"