Postman Instructions & Collections

The Postman client lets you test API requests and create collections of frequently-used requests.

We've created several Postman collections that let you test out GBDX and Vector Services requests and see the results.


One Postman Environment for all collections

To use Postman, you'll download one environment file where you can run all collections. You'll enter your GBDX username and passwords environment variables.

1. Get the Postman Files from Github

GBDX Postman Environment and Collection

This collection covers GBDX Authentication, Catalog, Ordering,Task and Workflow APIs, and more. If you don't need the GBDX Collection, you can skip this step.

  1. Download GBDX Postman files from GBDX Github location

  2. Click "Download zip". You'll find it above the file list. It will save a zip file called Postman_Master to your local machine.

  3. Find the zip file on your local machine and unzip it.

  4. Open the Postman_Master file and check to make sure the following files are there. You'll need them when you set up Postman.

  • Environment file: GBDX.postman_environment
  • Collection file: GBDX.json.postman_collection

GBDX Vector Postman Collection

The GBDX Vector Postman Collection is in a separate Github location. If you don't need the GBDX Vector Collection, you can skip this step.

  1. Download GBDX Vector Postman files from GBDX Vector Github location

  2. Click "Download zip". It will save a zip file called Postman_Master to your local machine.


Depending on your download settings

You may either automatically download files or you may need to choose the file name and file location each time.

  • If you automatically download files to a location, downloading both collections will result in a file name iteration (ie and postman-master (1).zip)
  • If your download settings require you to choose file name and location each time, you will need to rename one of the zip files if you download both collections. For example, call rename the file to Postman_Vector_Master.
  1. Save the file to your local drive and unzip it.

  2. Open the master file. You may have to open additional folders to get to the collection file. For example,

Check to make sure this collection file is there:

  • Collection file: GBDXVector.postman_collection.json

Note: If you did not download the GBDX environment file from the GBDX Github location, you can download it from here.

2. Install Postman

These instructions apply to the free version of Postman for Chrome. If you install a desktop version or Postman Pro, the setup may be different.

Get postman: Get Postman

Choose the application you want to install, such as Postman for Chrome. If you need help installing Postman, see Postman User Documentation

3. Set up the GBDX Environment

  • Import the GBDX environment variables file.

To do this, select the environment pull down menu, and choose "manage environments".

Environment setup uses the controls in the top right corner of the application.

From the "settings" menu, choose "Manage Environments".

  • From the "manage environments menu, select "import".
  • Select "choose files".

Navigate to the file location where you saved the Postman files and select the file "GBDX.postman_environment" and open it. You'll get an "import successful" message.

  • Add environment variables
    Once you've imported the GBDX environment, it will show up in the "manage environments" list. Click on the name "GBDX" to add your environment variables.

To edit these variables later, choose the settings icon, and then "manage environments" again.

  • Choose GBDX from the dropdown menu

Make sure the dropdown menu in the top right corner shows "GBDX". If it says "no environment" or shows a different name, choose GBDX from the dropdown menu.

4. Import the Postman Collections

To import the Collections, choose "import" from the top of the screen.

  1. To import the GBDX collection, select "Choose Files", then navigate to the file location where you saved the file "GBDX.json.postman_collection" and select it.

  2. To import the GBDX Vector collection, repeat the process, navigating to the file location where you saved the "GBDXVector.postman_collection.json" and select it.

5. Get a Token

Before you can start making API requests using Postman, you need to get your Bearer Token (also referred to as an OAuth2 Token). If you've filled in your environment variables, you can use Postman to get your token.

  • On the left hand side under Collections, click "GBDX" or "GBDX Vector." You'll see a list of files. Under "Auth" select the Post "Get User Token".

Since you've already added your environment variables, you don't need to fill in the values here. Click Send.

The response body to the request will include the token. This token is valid for seven days. You can either add your token to the environment variables, or use it in each request by adding to the Headers section. Remove {{AccessToken}}, and replace it with your token.

Note: If you get an authorization error when trying to run requests in Postman, your token may have expired. Request a new token and update it in the environment variables.