Overview

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

You must have a Web Services developer license in order to complete the exercises in this tutorial. If you need a license, contact your account manager.

If you haven’t already done some preliminary reading, consider looking at the Web Services overview before continuing.

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

Download


Learn About Postman

Before getting started, it’s helpful to understand some of the capabilities of Postman.

Postman lets you create environments to store frequently used settings for your requests. You can also create global variables that apply across all your environments. Finally, you can a create a collection of commonly-used requests that rely on these variables.

This tutorial will show you how to store your Web Services credentials and the gateway endpoint as global variables, then create an environment for your company that stores your login credentials and other information. You will then import a collection of requests and modify/run them.


Install Postman

Postman is available as a Chrome app or a full packaged application—using the full application is recommended.

  1. Download the installer for your platform and run it.

    The sign-in dialog appears.

  2. You can simply open the application, but it is strongly recommended that you either sign in or create an account if you don’t already have one.

    Warning: If you update a collection and sign up/log in after that point, you run the risk of losing your work.


Create an environment and define global variables

  1. On the top right of Postman, choose Manage Environments from the settings menu (gear icon).

  2. In the Manage Environments dialog, click Add and give your environment an intuitive name.

  3. Provide the following information as key/value pairs for your company’s environment:

    Variable name Value
    company_id myCompanyId or
    myConsoleId|clientCompanyId|entityId (for console slide in)
    user_id myUserId (preferable a Web Services only user ID)
    user_password *****

    It is strongly recommended that you set up a Web Services only user account in the Sage Intacct System, especially when you move beyond the learning phase and begin doing real work. (See the topic about user information in the Sage Intacct product help for instructions.)

  4. Still in the Manage Environments dialog, click Add, then click Globals.

  5. Add the following key/value pairs for the endpoint and for your Web Services credentials:

    Variable name Value
    endpoint_url https://api.intacct.com/ia/xml/xmlgw.phtml
    sender_id myWebSenderId
    sender_password *****
  6. Click Save, then close the dialog.

  7. Select the new environment from the drop down menu.

Note: See the Postman docs for more usage information.


Get the tutorial collection

The requests used in this tutorial are available as a Postman collection. Click the button to load the tutorial collection into Postman:

Run in Postman

You will be asked to choose how to open the collection, for example:

The Web Services Tutorial collection loads:

Alternatively, you can manually import the collection (the end result is the same):

  1. Download the collection, which is in a JSON file.

    Note: If you have trouble downloading, try a browser other than Chrome.

  2. Click Import on the upper left of Postman choose the your-first-api-calls.json file you downloaded.


Get an API session

When working with production code, you should always use getAPISession to get a session ID and unique endpoint for your interaction. The tutorial collection includes a request that does this.

  1. Click Generate API Session from the collection.

  2. Click Body to view the request.

  3. Examine the request and consider the following:

    • Instances of company environment variables are used in the request (highlighted in yellow).

    • The request uses a POST command with the endpoint_url variable as the target endpoint.

    • Instances of Postman dynamic variables are used for control IDs (highlighted in blue).

    • The dtdversion is set to 3.0, which is the recommended version. This version provides a set of generic API functions for basic operations like create, read, delete and provides object-specific functions.

    • You can ignore temp_slide_in for now—this optional variable is described below.

    See XML Requests for more details about the parts of a request.

  4. Click Tests to show the post-request scripts that will gather information from the gateway response.

    The script captures the session ID and endpoint from the response and adds these variables to the company environment.

  5. Click Send on the upper right to post the request.

    The XML response from the gateway displays at the bottom of the window. Note the session ID and endpoint returned in the result.

  6. Open your company environment again and confirm that the following variables shown have been added and initialized.


Get information about objects

Now that everything is set up, let’s get some information about objects in our company.

  1. Click List VENDOR from the collection, then click Body and examine the request.

    • The authentification element for the request will use the captured session ID.

    • The content element includes a readByQuery call on VENDOR.

  2. Click Send to post the request.

    Assuming there are VENDOR objects in your company, you will see a maximum of 100 vendor objects listed in the response. Note the name of one of the returned vendors.

  3. Add a query to the function in the request body (at the top) to seek a VENDOR object based on its name, for example:

  4. Click Send and examine the response.

  5. Limit the query response to include only specific fields by changing the request body and resending, for example:

  6. Click Send and examine the response.

    Tip: Do you want to save your changes to the request? Use Save > Save As in the upper right.


Get all fields for an object type

  1. Click Inspect CUSTOMER from the collection, then click Body to view the request:

  2. Click Send and examine the results.

    The response shows all the available fields for the object type. Attributes for the fields are not included though.

  3. Modify the function in the request body as shown:

  4. Send the request to see each field with its attributes.


Create an object

Let’s create a test CUSTOMER object.

  1. Click create CUSTOMER from the collection, then click Body to view the request:

  2. Click Send and view the response.

    Note the RECORDNO value for the new customer. This is the record number that is assigned by the system to uniquely identify the object.


Delete an object

Now let’s delete the test CUSTOMER. In order to delete a standard object, you use its record number as the key.

  1. Click delete CUSTOMER from the collection, then click Body to view the request:

  2. Modify the request by providing the record number that was assigned for your CUSTOMER object as the keys value.

  3. Click Send and view the response.


Configure slide in (passthrough) authentication

You can provide separate client_id and entity_id variables in your Postman environment. The Generate API Session command includes code in its pre-request script to handle these variables for you. The script uses the client_id and entity_id from the company environment to create the temp_slide_in value, which is then used when getting the session.


Sage Intacct API collection for Postman (DOWNLOAD)

You can download the Sage Intacct API collection, which provides a set of API functions (by application) that you can modify and use.

Download

Extract the zip file and import the collection into Postman.

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.

Provide feedback