First request with Postman

Postman is a powerful HTTP client for testing web services by displaying API requests and responses in manageable formats.

 
QuickBooks Online collection of individual resource endpoints
 
QuickBooks Online orchestrated collection
 
QuickBooks Payments resource endpoints and orchestrations collection

Usage

  1. Create an Intuit Developer account or sign on to your existing account.
  2. Create an app if you haven't already done so that configures the Accounting data source. As configured, requests in the collection access the sandbox development work environment. 
  3. Download and install Postman from here: https://www.getpostman.com.
  4. Click on the Run in Postman button corresponding to the desired collection from the list above. This sets up the Postman UI and downloads the corresponding collection.
  5. Configure the Postman Authorization header.
  6. Before each request is sent, refresh the authorization header:
    • For OAuth 2.0 headers: Select the desired token from the Existing Tokens list and click Use Token.
    • For OAuth 1.0a headers: Make sure Add params to header and Save helper data to request are checked. Click Update Request  to re-sign the authorization header.
  7. Select the desired endpoint from the collection. If not already defined in the active environment, replace the variables (and pairs of {}) in the request with the following:
    • baseurl: Use sandbox-quickbooks.api.intuit.com.
    • companyid: Get this value from the sandbox company information on the Manage Sandboxes page of your Intuit Developer account. Click on your user name and select Sandbox to display this page.
    • minorversion: Enter the minor version appropriate to the request.  See Minor Versions for complete details on choosing a minor version.

The request URL now looks something line this:

https://sandbox-quickbooks.api.intuit.com/v3/company/12323423524352543/customer/63?minorversion=10

You are now ready to issue the API request. Click Generate Code to select code generation type and then Send to issue the request.

For reference information about a specific endpoint in the collection, see the API reference guide for QuickBooks Online or Payments, as appropriate.

Note

Use this tool for testing and prototyping your API requests. For your production code use QuickBooks Online SDKs.

Configuring the Postman Authorization header

Information in this section provides configuration details for the OAuth authorization header, which is supplied with each request to the QuickBooks API. Click here to help you determine the version of OAuth your app uses.

OAuth 2.0

Follow the steps in this section if your app uses OAuth 2.0 authorization. Before submitting a request from the collection, you need to get an OAuth 2.0 access token via the Postman UI using information from your app's profile. 

  1. Sign in to developer.intuit.com and click My Apps.
  2. Find and open the app you want to use or create an app.
  3. Navigate to the Keys tab of the app's profile.

Now, from the Authorization tab on the Postman UI, for Type select OAuth 2.0 and click Get New Access Token. You need the following information when configuring this dialog:

Postman Authorization FieldInformation from your developer account
Callback URLDefined by Postman to be https://www.getpostman.com/oauth2/callback. Configure this as a Redirect URI on the Keys tab of the app profile via My Apps on the developer site.
Token NameA user defined name for this header instance. It appears in the Existing Tokens list to use in subsequent API Send requests.  
Auth URLhttps://appcenter.intuit.com/connect/oauth2
Access Token URLhttps://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
Client ID

Obtain these values from the Keys tab on the app profile via My Apps on the developer site. There are two versions of this key:

  • Development keys—use only in the sandbox environment.
  • Production keys—use only in the production environment. 
Client Secret
ScopeSpecify com.intuit.quickbooks.accounting openid email profile
Grant TypeThis must be set to Authorization Code.
Request access token locallyMake sure this is unchecked.

OAuth 1.0a

For apps using OAuth1.0a authorization, follow this workflow.

Before submitting a request from the collection, you configure authorization header details via the Postman Authorization dialog. You need the following keys when configuring this header:

  • Consumer Key and Consumer Secret—keys that identify your app
  • Token and Token Secret—keys that authorize your app to access your QuickBooks sandbox data.
Note

When you create an app, Intuit Developer creates API keys on your behalf. You are provided two sets:

  • Development keys for connecting to your QuickBooks Online sandbox company.
  • Production keys for connecting to a QuickBooks Online production company.

Below, we use development keys to connect to a QuickBooks Online sandbox company.

Follow these steps to to get the keys and to configure Postman. Click on each to expand.

1. Invoke the OAuth playground for your app.
  1. Sign in to developer.intuit.com and click My Apps.
  2. Find and open the app you want to use or create an app.
  3. Click the Dashboard tab and click the Test connect to app (OAuth)

  1. The OAuth Playground appears pre-populated with your app's Consumer Key and Consumer Secret.

  1. Set the Access Token Duration. The maximum value is 15552000 seconds (six months); pick a value large enough that tokens don't expire before you are finished with your Postman session. 
  2. Click the Connect to QuickBooks button to initiate the company connection workflow. This initiates the authorization dialog.
2. Connect to a company.
  1. Select the sandbox company to which you want a connection.
  1. Authorize the connection.

The OAuth Playground dialog displays once again, this time with Access Token, Access Token Secret, and RealmId. Your app and the QuickBooks Online sandbox company are now connected. 

3. Configure Postman Authorization dialog

In this step you leverage Postman environment variables in order to automatically create a OAuth authorization header for each request you send.

  • Map the keys from the Developer Playground to Postman environment variables. 
  • Configure the authorization dialog with the corresponding environment variables so keys are automatically populated into the header at request time.
  1. Open the Manage Environments dialog.

  1. Select the QBOV3-Env-Variables environment—the Edit Environment dialog is displayed. Transfer values from the Developer Playground to corresponding values in this dialog, including RealmId.

Note that Access Token Duration and  DataSource values from the playground are not used. Click Update when finished and close the Manage Environments window.

Now, you are ready to issue a request from the collection.

Using the collections in a production environment

To use the collections in a production environment you need the folllowing:

Then, alter the way you configure the Postman authorization header with the following:

  1. In the OAuth Playground enter your production keys (instead of development keys) and click the Connect to QuickBooks button to initiate the authorization to your production QuickBooks Online company (instead of your sandbox company).
  2. In the Postman QBOV3-Env-Variables environment:
  • Enter the full set of keys from the playground.
  • Set { {baseURL} } to quickbooks.api.intuit.com.

 Got Questions? Get Answers in our developer forums.