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.

You must have a Postman account to start using our collection. To learn more about using Postman, check out the Postman documentation.

How to Use Postman

  1. Download and install Postman. You can also use the web version that runs in your browser without any installation.
  2. Click the Run in Postman button above to fork or import the collection.
  3. Register an app for Postman on the BQE CORE Developer Portal.
  4. Set up your environment and authorize Postman.
  5. Try out the pre-built requests from the collection.

Make sure the redirect URI you set in the Developer Portal and the callback URL set in Postman are an exact match.

For the desktop version of Postman, you can use any valid redirect URI when registering the app on the Developer Portal. You can also use one of the Postman-hosted callback URLs as the redirect URI for a quick setup:

https://oauth.pstmn.io/v1/browser-callback or https://oauth.pstmn.io/v1/callback

For the web version, the callback URL cannot be modified and is always set to https://oauth.pstmn.io/v1/browser-callback. So, you must use this as the redirect URI in the Developer Portal.

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.

manage_environments

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.

Variable Value

baseUrl

redirectUri

Redirect URI that you have set for your Postman app on the BQE CORE Developer Portal

authorizeUrl

tokenUrl

clientId

Client Id of your app on the BQE CORE Developer Portal

clientSecret

Client Secret of your app on the BQE CORE Developer Portal

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 the redirectURI environment variable

    Auth URL

    Use the authorizeUrl environment variable

    Access Token URL

    Use the tokenUrl environment variable

    Client ID and Secret

    Use the clientId and clientSecret environment variables

    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

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

collections

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.

post

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.

get

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.

send