What is Postman?

Postman is a free-to-use visual editing tool for building and testing the API requests. As opposed to other methods for interacting with APIs (e.g., using cURL), Postman allows you to easily edit API requests, view header information, and much more. To make it easy for our clients to get up and running with our REST APIs, we created a collection of our API endpoints with examples.

How to Use Postman

1. Add an app for Postman on the Developer Portal.
2. Download and install Postman: https://www.getpostman.com.
3. Click the Run in Postman button as shown above.
4. Set up your environment and authorize Postman.
5. Try out the pre-built requests from the collection.

Configuring the Postman environment

You are provided with an environment template in the collection accessed via Manage Environments of the Postman setting. You can also add a new environment by clicking Manage Environments at the top-right corner of Postman.

When configuring your environment, enter the variable name and specify Initial and Current values for it – by default, the current value will copy the initial value.

Postman Authorization

Postman must generate an OAuth 2.0 access token based on OAuth 2.0 keys from your app’s dashboard in the Developer Portal. To generate the access token, follow these steps:

1. Go to the Authorization tab in the Postman collection.
2. Select OAuth 2.0 for Type and use the below information when configuring the Authorization tab:

   Postman Field	Developer Portal Information
   Token Name	A user defined name for the token
   Grant Type	Authorization Code
   Callback URL	Use https://www.getpostman.com/oauth2/callback. This must also be configured as a Redirect URI in your app on the Developer Portal
   Auth URL	/connect/authorize
   Access Token URL	/connect/token
   Client ID and Secret	Obtain these values from your app via Developer Portal
   Scope	readwrite:core offline_access openid email profile
   State	Authorization protocols provide a state parameter. During authentication, the application sends this parameter in the authorization request and the Authorization Server will return this parameter unchanged in the response.
   Client Authentication	Send as Basic Auth Header

   
3. Click Get New Access Token. You are redirected to the login page where you need to enter your CORE credentials. When logged in, CORE displays a consent dialog with the name of your application and CORE Company name, requesting permission to access with your authorization credentials.
   
4. Click Grant Permission to give access to Postman and acquire an access token.
5. On the Manage Access Tokens dialog, click Use Token.

This completes the authorization process and you can start using the Postman collection.

Using the pre-built requests from the collection

After you have configured your environment, you can use any of the pre-built requests from our collection. To start using the pre-built requests, simply click on any of the CORE API module within the ‘Collection’ menu on the left side of Postman. This will open the request as a new tab in the main window of the Postman app.

In general, there are two types of requests that CORE API endpoints accept - GET and POST. Depending on which HTTP method the endpoint uses, you’ll need to edit the pre-built request differently.

Edit a POST request

When editing a POST request, you’ll need to open the request and navigate to the Body section in the request editor. For readability, select the raw tab to format the JSON request body.

Edit a GET request

When editing a GET request, you will need to edit the parameters passed in the request URL. To edit these easily, select the Params tab next to the Auth tab and edit the key-value pairs in the fields that will appear below the URL bar.

Send Your Request

When your API request is ready, click the ‘Send’ button next to the URL bar. The request is sent and the response data is populated in a section underneath the request editor. From here, you can view the raw data returned from CORE API, see the HTTP response code, see how long the request took to process, and view header information.