Postman

Postman is a powerful HTTP client for testing the QuickBooks Online API by displaying requests and responses in manageable formats.

QuickBooks Online collection of individual resource endpoints, using OAuth 2.0 authorization.
QuickBooks Online collection of individual resource endpoints, using OAuth 1.0a authorization.
QuickBooks Online orchestrated collection, using OAuth 1.0a authorization.

The steps on this page use Postman for Mac, v 5.4.1.

Using Postman

Setup

  1. Create an app.
  2. Download and install Postman: https://www.getpostman.com.
  3. Click the Run in Postman button corresponding to the desired collection from the list above. This sets up the Postman UI and downloads the collection.
  4. Configure the Postman Authorization header.
  5. Configure an environment that defines variables used in endpoints. An environment template is provided for you in the collection and accessed via Manage Environments in Postman settings. Define these variables:
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.
UserAgent Specify QBOV3-OAuth2-Postman-Collection

Make calls

Once you configure Postman authorization header, requests in the Postman collections here will access your sandbox.

For each request, refresh the authorization header:

  • Oauth 2.0: For OAuth 2.0 headers, select the desired token from the Available Tokens list and click Get New Access Token.
qbo/docs/develop/O2Setup.jpg
  • OAuth 1.0a: For OAuth 1.0a headers, make sure Add authorization data to is set to Request Headers. Click Preview Request to regenerate the authorization signature.
qbo/docs/develop/O1Setup.jpg

For either authorization type:

  1. Select the appropriate environment, configured earlier, Postman uses for endpoint variable substitution.

    qbo/docs/develop/SelectEnv.jpg
  2. Select the desired endpoint from the collection.

  3. Click Send to issue the API request. Response payload is returned in the Body tab.

    qbo/docs/develop/PostmanSend.jpg

For reference information about a specific endpoint in the collection, see the QuickBooks Online API reference.

Note

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

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 Online API. Based on the version of OAuth your app implements, configure either an OAuth 2.0 header or an OAuth 1.0a header. To help you determine the version of OAuth your app uses click here.

OAuth 2.0

Before submitting a request from the collection, Postman must generate an OAuth 2.0 access token based on OAuth 2.0 keys from your app’s dashboard on developer.intuit.com.

  1. Sign-on to your developer account on developer.intuit.com and click My Apps.
  2. Find and open the app you want to use.
  3. Navigate to the Keys tab on your app’s dashboard. You use the development keys for this configuration.

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 Field Information from your developer account
Token Name A user defined name for this token. It appears in the Postman Existing Tokens list to use in Send requests.
Grant Type This must be set to Authorization Code.
Callback URL Enter: https://www.getpostman.com/oauth2/callback. This must also be configured as a Redirect URI on the app’s Keys tab of the app profile via My Apps on the developer site. Make sure to configure this in the development keys section on this tab.
Auth URL https://appcenter.intuit.com/connect/oauth2
Access Token URL https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
Client ID and Client Secret Obtain these values from the Keys tab on the app profile via My Apps on the developer site. Make sure you get them development keys section on this tab.
Scope Specify: com.intuit.quickbooks.accounting openid email profile
State This can be any string. It provides information that might be useful to your application upon receipt of the response. The Intuit Authorization Server roundtrips this parameter, so your application receives the same value it sent.
Client Authentication Set to Send client credentials in body

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 sandbox company.
  • Production keys for connecting to a QuickBooks production company.

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

Follow these steps to to get the keys and to configure Postman.

Invoke the OAuth playground for your app.

  1. Click My Apps.
  2. Find and open the app you want to use.
  3. Click the Dashboard tab and then the Test in production link in the Resources section.
qbo/docs/develop/Dashboard.jpg
  1. The OAuth Playground appears pre-populated with your app’s Consumer Key and Consumer Secret.
qbo/docs/develop/OAuthPlayground.jpg
  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.

Connect to a company.

  1. Select the sandbox company to which you want a connection.
  2. 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 sandbox company are now connected.

qbo/docs/develop/OAuthPlaygroundFull.jpg

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.
qbo/docs/develop/ManageEnv.jpg
  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.
qbo/docs/develop/PostmanMapping.jpg

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:

  • Access to your production keys
  • A paid or trial subscription to QuickBooks Online. Your production keys will not authorize a sandbox company.
  • Set { {baseURL} } to quickbooks.api.intuit.com.