Postman Sandbox API reference

Postman Sandbox API Reference (pm.*)

Global Type
require Function

require(moduleName:String) → *

The require function allows you to use the sandbox built-in library modules. The list of available libraries are listed below. The list links to their corresponding documentation.

      1. atob→ v2.0.3
      2. btoa→ v1.1.2
      3. chai→ v3.5.0
      4. cheerio→ v0.22.0
      5. crypto-js→ v3.1.9-1
      6. lodash→ v4.17.2
      7. postman-collection→ v1.2.0
      8. tv4→ v1.2.7
      9. uuid→ (the module loaded is a shim for original module)
      10. xml2js→ 0.4.17

A number of NodeJS modules are also available:

      1. path
      2. assert
      3. buffer
      4. util

In order to use a library, you would need to simply call the require function and pass the module name as a parameter and assign the return of the function to a variable.

var atob = require('atob'),
    _ = require('lodash'),
arrayOfStrings = ['string1''string2'];
base64Strings =, atob);

pm Object


The pm object encloses all information pertaining to the script being executed and allows one to access a copy of the request being sent or the response received. It also allows one to get and set environment and global variables. Object

The object contains information pertaining to the script being executed. Useful information such as the request name, request Id, iteration count, etc are stored inside of this.

      contains information whether the script being executed is a "prerequest" or a "test" script.
      is the value of the current iteration being run.
      is the total number of iterations that are scheduled to run.
    • :String

pm.globals VariableScope


pm.globals.has Function

pm.globals.has(variableName:String) → Boolean

pm.globals.get Function

pm.globals.get(variableName:String) → *

pm.globals.set Function

pm.globals.set(variableName:String, variableValue:String)

pm.globals.unset Function


pm.globals.clear Function


pm.globals.variables Function

pm.globals.variables() → Object

pm.environment VariableScope


pm.environment.has Function

pm.environment.has(variableName:String) → Boolean

pm.environment.get Function

pm.environment.get(variableName:String) → *

pm.environment.set Function

pm.environment.set(variableName:String, variableValue:String)

pm.environment.unset Function


pm.environment.clear Function


pm.environment.variables Function

pm.environment.variables() → Object

pm.request Request


The request object inside pm is a representation of the request for which this script is being run. For a pre-request script, this is the request that is about to be sent and when in test script, this is the representation of the request that was sent.

Request contains information stored in the following structure:

    • pm.request.url:Url
    • pm.request.headers:HeaderList


The data object would contain data from the data file provided during a collection run




Inside the test scripts, the pm.response object contains all information pertaining to the response that was received.

The response details are stored in the following format

    • pm.response.code:Number
    • pm.response.reason:Function → String
    • pm.response.headers:HeaderList
    • pm.response.responseTime:Number
    • pm.response.text:Function → String
    • pm.response.json:Function → Object




The cookies object contain a list of cookies that are associated with the domain to which the request was made.

pm.cookies.has Function

pm.cookies.has(cookieName:String):Function → Boolean

Check whether a particular cookie (addressed by it's name,) exists for the requested domain or not.

pm.cookies.get Function

pm.cookies.get(cookieName:String):Function → String

Get the value of a particular cookie.

pm.cookies.toObject Function

pm.cookies.toObject:Function → Object

Get a copy of all cookies and their values in form of an object. The cookies returned are the ones defined for the requested domain and path.



pm.test(testName:String, specFunction:Function)

This function is used to write test specifications inside the sandbox. Writing tests inside this function allows one to name the test accurately as well as ensure that in case of any error inside this function, the rest of the script is not blocked.

The following code block is a sample test where we are checking to ensure that everything about a fictitious response is valid for us to proceed next.

pm.test("response should be okay to process", function () {;'');'error');



pm.expect(assertion:*) → Assertion

pm.expect is a generic assertion function. Underlying this is the ChaiJS expect bdd library. Using this, it is easy to write tests where the syntax becomes readable and verbose.

Read more on the usage of pm.expect at

This function is useful to deal with assertions of data from response or variables.

pm.test('environment to be production', function () {

Response Assertions API



Description Function Function, optionalValue:String) Function Function, optionalValue:*)* Object

The properties inside object allows you to easily assert a set of pre-defined rules