Your First XML API Calls

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 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 left of Postman, click the Workspaces drop-down and select Create Workspace.

    Postman add-workspace menu pick

  2. Give your new workspace a name, and select the appropriate Visibility for your project.

    Postman create-new-workspace dialog

  3. In the new workspace, click Environments and then click Globals to set global variables.

    Postman select-globals menu pick

  4. Create these global variables with your Web Services sender ID and password. Both values are case-sensitive.

    Postman select-globals menu pick

  5. Close the Globals tab and save your changes.

  6. Click Environments, then click + to add a new environment to your workspace.

    Postman create-new-environment

  7. Give your environment an intuitive name and set these environment variables:

    Postman set environment variables

  8. Close the environment tab and save your changes.

  9. Select the new environment from the drop down menu in the top right corner.

    Postman selecct environment

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.

  1. Click the button to load the tutorial collection into Postman:

    Run in Postman

  2. Choose how you want to open the collection, for example:

    Postman open-with form

  3. Select your new workspace to import into:

    Postman select workspace

    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. Open the File menu and click Import, then 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 send a getAPISession request 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 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 variable has been added and initialized.

    Postman eye icon displays new variables

  7. To view the code snippet for your request, click the code icon </> on the upper right.

    Postman code icon

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, but does not include field attributes, which is where object data is stored.

  3. Add details="1" to the request body to get the field attributes:

    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. Note the nested <create><CUSTOMER> elements that specify the function:

    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