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.

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

Download


Prerequisites


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.

    Postman sign-up form

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

    Postman manage-environments menu pick

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

    Postman add-environments field

  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 UI, 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.

    Postman Globals button

  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.

    Postman environments 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:

Postman open-with form

The Web Services Tutorial collection loads:

Postman with tutorial collection loaded

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.

    Postman import button


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.

    Generate API Session call in Postman

  2. Click Body to view the request.

    Postman tab for for request body

  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.

      Contents of request body

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

    Contents of test tab

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

    Postman send button

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

    XML response with session ID and endpoint

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

    Postman eye icon displays new variables


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.

      readByQuery in Postman body tab

  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.

    XML response showing vendors found

  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:

    example query on vendor name

  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:

    example limiting query to return name and recordno fields

  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:

    inspect function on customer object

  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:

    detail="1" attribute added to inspect function

  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:

    create function for customer object

  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.

    example response with customer record number


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:

    delete function on customer objects with the given keys

  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.

Postman pre-request-script tab showing temp_slide_in


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