Using Postman

🚧

Prerequisites

Before using Postman to test out the StackOne Unified API you should have already configured an integration and linked your account following the instructions in the Getting Started with StackOne guide.

Installing Postman

Postman comes in two versions: an installed version and a browser-based version. Our Postman collection works equally well with both. We recommend setting up a Postman account to store all your configurations, which is quick and easy to do by following the instructions on the Postman website.

To install the desktop version of Postman, visit this link: https://www.postman.com/downloads/.

Setting up the StackOne collection

A Postman collection is a group of pre-configured requests that you can use to test an API. At StackOne, we've put together a collection for our Unified API, including all the configurations you need to quickly get started and connect using Postman. This collection lets you easily try out various aspects of our API.

📘

To learn more about Postman collections including how to create your own see here

To download the StackOne Postman Collection go here:

You will be shown a message to fork the collection into your workspace. Forking is the process of creating a copy of the collection in your workspace while maintaining a link back to the original version making it easier to receive updates in future. Click the Fork Collection button to continue.

You will now be presented with a final confirmation page for forking the collection. You can provide your own Fork label and Workspace name if you wish, but generally the defaults should suffice. Click the Fork Collection button to continue.

When the fork process is complete the StackOne Unified API configuration will be displayed in the main Postman window as shown:

You have successfully copied the StackOne Unified API collection into your Postman workspace.

Calling the StackOne Unified API

Now that the Postman collection is configured you are ready to make calls to the StackOne API.

Select an Environment

First select a StackOne environment to send your requests to. This must be the same environment that you have previously created your Project in as described in the Getting Started with StackOne guide.

In this example we will use the Production environment.

Configuring your API key and Account ID

Before we make any calls to the Unified API we need to configure the collection with both the API Key and the Account ID. The API key is the StackOne API key that you created in the Getting Started with StackOne guide.

Click on the Environments section in the left hand navigation and then select the environment that you wish to configure; this will normally be Production. On the right side set the value for API_KEY to the value of your StackOne API key and save the change.

Now that the API_KEY is configured we can retrieve the Account ID for our targeted endpoint. To retrieve all the Account IDs for the Project click on GET for Accounts and then Send. Look through the response for the Account ID needed for the particular endpoint you wish to make queries to. In this example we will be using Salesforce CRM so we will use the value returned in the id field for the provider salesforce as our ACCOUNT_ID.

Again, click on the Environments section on the left hand and select the environment and on the right side set the value for ACCOUNT_ID to the value of the Account ID you just retrieved and save the change.

Note: These values are stored against the environment so that they can be reused for all API calls made from Postman for that particular environment. As Projects and Account IDs are specific to each environment if you change the environment you should configure the correct values for that particular environment.

Calling the API

You are now ready to make calls to the StackOne Unified API. Start by expanding the StackOne section and explore the various parts of the Unified API. In this example our Project has been integrated with a CRM endpoint provided by Salesforce so we will make some test calls against the CRM part of the Unified API.

Click on List Contacts and you should see the URL update to read:

    {{API_BASE_URL}}/unified/crm/contacts?raw=true&page=1&page_size=3

Clicking on the Send button will send the request to the StackOne endpoint and the results will be displayed in the response panel at the bottom of the screen.

Congratulations, you have successfully made a call to the StackOne Unified API.

Troubleshooting

This section includes some common errors the you may encounter and steps to fix them.

{"error":"Invalid authentication token"}

If you see this error it is likely that you have not configured your API_KEY properly. Ensure that the steps above have been followed and that you are using the correct environment.