Working with Postman collections

Postman is a popular API test tool that lets you send HTTP requests to a server and review the responses. This tutorial shows you how to send REST API calls to the Sage Intacct Web Services gateway using the Postman application.

Already familiar with Postman and Web Services? Skip the tutorial and download the REST API collection for Postman.

About Postman

Postman lets you create a workspace where you can add environment variables and store frequently used settings for your requests. You can then create a collection of commonly used requests that rely on these variables.

This tutorial will show you how to set up your Web Services credentials as variables. You will then import a collection of requests and run them.

To install Postman, download the Postman installer for your platform and run it.

Open the application and create an account, or sign in if you already have one.

If you plan on modifying any collection in Postman, make sure you log in first or you might lose your work. Also, If you change any of the calls in the collection, rename them if you don’t want them overwritten when re-importing the collection at a later time.

Prerequisites

  • You must have an active Web Services developer license, which includes a Web Services sender ID and password. If you need a developer license, contact your account manager.
  • In the Sage App Registry, you must add an application and obtain a client ID and client secret for that application. See the Quick start topic for details.
  • The Intacct company that will be using your API client application must authorize your application:
    • If your application is using the OAuth authorization code grant type you can use either of these methods:
    • If your application is using the OAuth client credentials grant type:
      1. Add a Web Services user that has the permissions needed by your application. You cannot use a regular user with the client credentials grant type.
      2. Add an Authorized client application to the Security tab on the Company information page. Set the Client ID to the name of your application and enter the Web Services user ID from the previous step.

      pmt authorized client apps

Download the Sage Intacct REST API collection

Download the Sage Intacct REST API collection for Postman, which includes:

  • Intacct.postman_collection.json - a file which contains a set of API operations that you can run and modify. The collection is organized by application area, such as Accounts Payable, Accounts Receivable, Cash Management, and so forth.
  • Intacct.postman_environment.json an environment file that sets variables used by the operations.

Unzip the file to a folder on your local system.

Create your workspace

  1. On the top left of Postman, click the Workspaces drop-down and select Create Workspace .

    pmt create workspace

  2. Select Blank workspace and click Next . Give your new workspace a name and click Next .
  3. Select the appropriate access permission for the workspace, then click Create .

    pmt create workspace2

  4. In the new workspace, click Import and select the folder where you unzipped the downloaded file.
  5. Click Environments and then select the Intact environment. You should see the following variables. Replace clientId and clientSecret with the values you obtained from the Sage App Registry (see the Prerequisites section). Values are case-sensitive.

    pmt global variables

  6. Save your changes.
  7. In the top right corner, select the Intacct environment.

Authorize your session

Your session must be authorized by an Intacct user in order to get an access token, which must then be included in every API request. The Intacct REST API supports the OAuth authorization code grant type and the client credentials grant type.

Authorization code grant type

  1. Click on Collections , then click on Sage Intacct REST API which is the top level of the collection.
  2. Select the Authorization tab. Verify that Type is set to OAuth 2.0 , Add auth data to to Request Headers , and Header Prefix to Bearer .

    pmt auth

  3. Scroll down and verify your token is configured as follows:
    • Token Name : your desired name, for example Intacct token
    • Grant type : Authorization Code
    • Check the Authorize using browser box.
    • Auth URL : {{baseUrl}}/oauth2/authorize
    • Access Token URL : {{baseUrl}}/oauth2/token
    • Client ID : {{clientId}}
    • Client Secret : {{clientSecret}}
    • Scope : offline_access
    • State : a code of your choice, for example 1234
    • Client Authentication : Send as Basic Auth header

    pmt auth token

  4. Scroll to the bottom and click Get New Access Token . Postman will open the Sage Intacct log in screen in your browser.
  5. On the Sage Intacct log in screen, provide your company credentials, then click Log in . Log in as an admin user to add your Web Services sender ID to the list of authorized web services for the company.

    pmt sage authorize

  6. Click Accept to grant access.

    pmt sage grant access

  7. Click Use Token to save the access token which can now be used to send requests to the REST API.

    pmt use token

  8. In Postman, scroll up to the Current Token section and confirm that you can now see your new token.

Client credentials grant type

  1. Click on Collections , then click on Sage Intacct REST API which is the top level of the collection.
  2. Select the Authorization tab. Verify that Type is set to OAuth 2.0 , Add auth data to to Request Headers , and Header Prefix to Bearer .

    pmt auth

  3. Scroll down and set or verify these fields under Configure New Token :
    • Token Name : your desired name, for example Intacct token
    • Grant type : Client Credentials
    • Access Token URL : {{baseUrl}}/oauth2/token
    • Client ID : {{clientId}}
    • Client Secret : {{clientSecret}}
    • Scope : offline_access
    • Client Authentication : Send client credentials in body
  4. In the Token Request table create a new entry with these values:
    • Key : username
    • Value : the web services user ID and the company ID, in the form userID@companyID
    • Send In : Request Body

    pmt auth token cc

  5. Scroll to the bottom and click Get New Access Token . Postman will send the credentials to Intacct and you should soon see an "Authentication complete" message.
  6. Click Use Token to save the access token which can now be used to send requests to the REST API.
  7. In Postman, scroll up to the Current Token section and confirm that you can now see your new token.

Send a request

You are now ready to get some information about objects in your company.

  1. Select Accounts Payable > Vendors , then List vendors from the collection.

    pmt collection vendor

  2. Click the </> icon on the right to preview the code snippet for your request.

    pmt code snippet

  3. Click Send to post the request.

    Assuming there are vendor objects in your company, you will see up to 100 vendor objects listed in the response.

    pmt list vendors response

You can now send other requests for any Accounts Payable objects, or get a token and send requests in other application area collections.