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:
    baseurlUse sandbox-quickbooks.api.intuit.com
    companidGet 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. 
    minorversionEnter the minor version appropriate to the request.
    UserAgentSpecify QBOV3-OAuth2-Postman-Collection

Make calls

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

    1. For each request, refresh the authorization header:
      OAuth 2.0OAuth 1.0a
      O2Setup.jpgO1Setup.jpg
      • For OAuth 2.0 headers: Select the desired token from the Available Tokens list and click Get New Access Token.
      • For OAuth 1.0a headers: Make sure Add authorization data to is set to Request Headers. Click Preview Request  to regenerate the authorization signature.
    2. Select the appropriate environment, configured earlier, Postman uses for endpoint variable substitution. 
      SelectEnv.jpg
    3. Select the desired endpoint from the collection.
    4. Click Send to issue the API request. Response payload is returned in the Body tab.
      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 FieldInformation from your developer account
    Token NameA user defined name for this token. It appears in the Postman Existing Tokens list to use in Send requests.  
    Grant TypeThis must be set to Authorization Code.
    Callback URLEnter: 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 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. Make sure you get them development keys section on this tab.

    Client Secret
    ScopeSpecify: com.intuit.quickbooks.accounting openid email profile
    StateThis 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 AuthenticationSet 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. Click on each to expand.

    1. 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 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 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:

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


    Did you find this page helpful?
    Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

     Got Questions? Get Answers in our developer forums.