The Postman JavaScript API functionality enables you to programmatically access and alter request and response data and variables using the pm
object. You can also dynamically alter run order to build request workflows for the Collection Runner.
You can access and manipulate variables at each scope in Postman using the pm
API.
You can use dynamic variables to generate values when your requests run.
Postman supports a variety of variable scopes. The pm
object provides methods for accessing global, collection, and environment variables specifically, and pm.variables
methods for accessing variables at different scopes and setting local variables.
Variable scope determines the precedence Postman gives to variables when you reference them, in order of increasing precedence:
The variable with the closest scope overrides any others. For example, if you have a score
variable in both the current collection and the active environment, and you call pm.variables.get('score')
, Postman returns the current value of the environment variable. When you set a variable value using pm.variables.set
, the value is local and only persists for the current request or collection run.
// collection var 'score' = 1
// environment var 'score' = 2
// first request run
console.log(pm.variables.get('score')); // outputs 2
console.log(pm.collectionVariables.get('score')); // outputs 1
console.log(pm.environment.get('score')); // outputs 2
// second request run
pm.variables.set('score', 3);// local var
console.log(pm.variables.get('score')); // outputs 3
// third request run
console.log(pm.variables.get('score')); // outputs 2
See the Postman Collection SDK Variables reference for more information.
You can also access variables defined in the individual scopes with pm.environment, pm.collectionVariables, and pm.globals. You can access vault secrets in your Postman Vault with pm.vault.
Postman doesn't support using
pm.variables
to access and manipulate vault secrets.
You can use variables in your scripts to:
Check if there is a Postman variable in the current scope:
pm.variables.has(variableName:String):function // Boolean
Get the value of the Postman variable with the specified name:
pm.variables.get(variableName:String):function
Postman supports getting the value of variables without a scope.
Append a string to the value of the Postman variable using the +
operator:
String + pm.variables.get(variableName:String):function
Set a local variable with the specified name and value:
pm.variables.set(variableName:String, variableValue:*):function
Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}
:
pm.variables.replaceIn(variableName:String):function:
For example:
const stringWithVars = pm.variables.replaceIn("Hi, my name is {{$randomFirstName}}");
console.log(stringWithVars);
Return an object containing all variables with their values in the current scope. Based on the order of precedence, this will contain variables from multiple scopes.
pm.variables.toObject():function // Object
You need Editor access for the environment to edit environment variables.
You can use the pm.environment
method in your scripts to access and manipulate variables in the active (selected) environment:
Get the name of the active environment:
pm.environment.name:String
Check if the environment has a variable with the specified name:
pm.environment.has(variableName:String):function // Boolean
Get the variable with the specified name in the active environment:
pm.environment.get(variableName:String):function
Append a string to the value of the variable in the active environment using the +
operator:
String + pm.environment.get(variableName:String):function
Set the variable with the specified name and value in the active environment:
pm.environment.set(variableName:String, variableValue:*):function
Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}
:
pm.environment.replaceIn(variableName:String):function
For example:
//environment has vars firstName and city
const stringWithVars = pm.environment.replaceIn("Hi, my name is {{firstName}} and I live in {{city}}.");
console.log(stringWithVars);
Return all variables with their values in the active environment in a single object:
pm.environment.toObject():function // Object
Remove a variable from the active environment, specifying the variable by name:
pm.environment.unset(variableName:String):function
Clear all variables in the active environment:
pm.environment.clear():function
You need Editor access for the collection to edit collection variables.
Use the pm.collectionVariables
methods in your scripts to access and manipulate variables in the collection.
Check if there is a variable in the collection with the specified name:
pm.collectionVariables.has(variableName:String):function // Boolean
Return the value of the collection variable with the specified name:
pm.collectionVariables.get(variableName:String):function
Append a string to the value of the collection variable using the +
operator:
String + pm.collectionVariables.get(variableName:String):function
Set a collection variable with the specified name and value:
pm.collectionVariables.set(variableName:String, variableValue:*):function
Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}
:
pm.collectionVariables.replaceIn(variableName:String):function
For example:
//collection has vars firstName and age
const stringWithVars = pm.collectionVariables.replaceIn("Hi, my name is {{firstName}} and I am {{age}}.");
console.log(stringWithVars);
Return all variables with their values in the collection in an object:
pm.collectionVariables.toObject():function // Object
Remove the specified variable from the collection:
pm.collectionVariables.unset(variableName:String):function
Clear all variables from the collection:
pm.collectionVariables.clear():function
You need the Workspace Editor role to edit its global variables.
Use the pm.globals
methods in your scripts to access and manipulate variables at the global scope within the workspace:
Check if there is a global variable with the specified name:
pm.globals.has(variableName:String):function // Boolean
Return the value of the global variable with the specified name:
pm.globals.get(variableName:String):function
Append a string to the value of the global variable using the +
operator:
String + pm.globals.get(variableName:String):function
Set a global variable with the specified name and value:
pm.globals.set(variableName:String, variableValue:*):function
Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}
:
pm.globals.replaceIn(variableName:String):function // String
For example:
//globals include vars firstName and city
const stringWithVars = pm.globals.replaceIn("Hi, my name is {{firstName}} and I am from {{city}}.");
console.log(stringWithVars);
Return all global variables and their values in an object:
pm.globals.toObject():function // Object
Remove the specified global variable:
pm.globals.unset(variableName:String):function
Clear all global variables in the workspace:
pm.globals.clear():function
You can use the pm.iterationData
methods in your scripts to access and manipulate variables from data files during a collection run:
Check if a variable with the specified name exists in the current iteration data:
pm.iterationData.has(variableName:String):function // Boolean
Return a variable from the iteration data with the specified name:
pm.iterationData.get(variableName:String):function
Append a string to the value of the iteration data using the +
operator:
String + pm.iterationData.get(variableName:String):function
Return the iteration data variables in an object:
pm.iterationData.toObject():function // Object
Convert the iterationData object to JSON format:
pm.iterationData.toJSON():function
Remove the specified variable:
pm.iterationData.unset(key:String):function
You can use the pm.vault
methods in your scripts to access and manipulate your vault secrets in your Postman Vault. Your scripts can also use the methods to access your vault secrets linked to external vaults from the Postman desktop app. Only you can access and use values associated with your vault secrets in scripts.
You can use the pm.vault
methods in your HTTP collections and requests. You can also use the Collection Runner to manually run collections with scripts that use the pm.vault
methods. Scheduled collection runs, monitors, the Postman CLI, and Newman don't support the pm.vault
methods. The pm.vault
methods also aren't supported for non-HTTP requests, such as GraphQL and gRPC.
To access and manipulate vault secrets in scripts, you must first enable this option in your Postman Vault. Open your Postman Vault, select Settings, turn the toggle on next to Enable support in scripts, then select Enable confirm. Once enabled, you must open your Postman Vault each time you sign in to Postman to use scripts with vault secrets.
If you try to access and manipulate vault secrets in scripts without enabling support for it, you'll receive an error in the Postman Console. Also, any code that comes after the
pm.vault
method won't run when you send the request.
If you're using the Postman web app to access and manipulate vault secrets from scripts, you must use the Postman Desktop Agent.
The pm.vault
methods run asynchronously in your scripts. Each method also returns a Promise object that represents the completion or failure of the method. Add the await
operator before each pm.vault
method to wait for the Promise and its resulting value. Note that a method without the await
operator may run in your script, but it may not behave as expected. For example:
console.log(await pm.vault.get("secretKey"));
await pm.vault.set("secretKey", "newValue");
await pm.vault.unset("secretKey");
To return the value of the vault secret with the specified name:
await pm.vault.get(secretKey:String):function
To append a string to the value of the vault secret using the +
operator:
String + await pm.vault.get(secretKey:String):function
To set a vault secret with the specified name and value:
await pm.vault.set(secretKey:String, secretValue:*):function
Postman doesn't support setting the value of vault secrets linked with external vaults.
To remove the specified vault secret:
await pm.vault.unset(secretKey:String):function
If you log the value of a vault secret using
console.log
, the value will be masked in the Postman Console by default. To unmask the value of vault secrets in the console, open your Postman Vault, select Settings, then turn the toggle off next to Mask vault secrets.
You can use pm.request, pm.response, pm.info, and pm.cookies to access request and response data in Postman. You can also send requests using pm.sendRequest.
The pm.request
object provides access to the data for the request the script is running within. For a Pre-request, this is the request that's about to run. For a Post-response script, this is the request that has already run.
You can use the pm.request
object pre-request scripts to alter various parts of the request configuration before it runs.
The pm.request
object provides the following properties and methods:
The request URL:
pm.request.url:Url
The list of headers for the current request:
pm.request.headers:HeaderList
The HTTP request method:
pm.request.method:String
The data in the request body. This object is immutable and can't be modified from scripts:
pm.request.body:RequestBody
Add a header with the specified name and value for the current request:
pm.request.headers.add(header:Header):function
For example:
pm.request.headers.add({
key: "client-id",
value: "abcdef"
});
Delete the request header with the specified name:
pm.request.headers.remove(headerName:String):function
Insert the specified header name and value (if the header doesn't exist, otherwise the already existing header will update to the new value):
pm.request.headers.upsert({key: headerName:String, value: headerValue:String}):function)
See the Postman Collection SDK Request reference for more information.
The pm.response
object provides access to the data returned in the response for the current request in scripts added to the Post-response tab. This object provides the following properties and methods:
The response status code:
pm.response.code:Number
The status text string:
pm.response.status:String
pm.response.headers:HeaderList
The time the response took to receive in milliseconds:
pm.response.responseTime:Number
The size of the response received:
pm.response.responseSize:Number
The response text:
pm.response.text():Function // String
The response JSON, which you can use to drill down into the properties received:
pm.response.json():Function // Object
See the Postman Collection SDK Response reference for more information.
The pm.info
object provides data related to the request and the script itself, including name, request ID, and iteration count. This object provides the following properties and methods:
The event, which will be either prerequest
or test
depending on where the script is executing within the request:
pm.info.eventName:String
The value of the current iteration:
pm.info.iteration:Number
The total number of iterations that are scheduled to run:
pm.info.iterationCount:Number
The saved name of the request running:
pm.info.requestName:String
A unique GUID that identifies the running request:
pm.info.requestId:String
The pm.cookies
object provides access to the list of cookies associated with the request. This object provides the following properties and methods:
Check whether a particular cookie (specified by name) exists for the requested domain:
pm.cookies.has(cookieName:String):Function // Boolean
Get the value of the specified cookie:
pm.cookies.get(cookieName:String):Function // String
Append a string to the value of the specified cookie using the +
operator:
String + pm.cookies.get(variableName:String):function
Get a copy of all cookies and their values in an object, returning any cookies that are defined for the request domain and path:
pm.cookies.toObject():Function // Object
See the Postman Collection SDK Cookie List reference for more information.
You can use pm.cookies.jar
to specify a domain for access to request cookies. To enable programmatic access using the pm.cookies.jar
methods, first add a domain to the allowlist.
Access the cookie jar object:
pm.cookies.jar():Function // Object
For example:
const jar = pm.cookies.jar();
//cookie methods...
Set a cookie using name and value:
jar.set(URL:String, cookieName:String, cookieValue:String, callback(error, cookie)):Function // Object
Set a cookie using PostmanCookie or a compatible object:
jar.set(URL:String, { name:String, value:String, httpOnly:Bool }, callback(error, cookie)):Function // Object
For example:
const jar = pm.cookies.jar();
jar.set("httpbin.org", "session-id", "abc123", (error, cookie) => {
if (error) {
console.error(`An error occurred: ${error}`);
} else {
console.log(`Cookie saved: ${cookie}`);
}
});
Set a cookie from the cookie jar for a particular URL:
jar.get(URL:String, cookieName:String, callback(error, value)):Function // Object
Get all the cookies from the cookie jar for a particular URL, which are available in the callback function:
jar.getAll(URL:String, callback(error, cookies)):Function
Remove a cookie for a particular URL:
jar.unset(URL:String, cookieName:String, callback(error)):Function // Object
Clear all cookies from the cookie jar for a particular URL:
jar.clear(URL:String, callback(error)):Function // Object
Clear and then set a cookie in sequence for a particular URL:
jar.clear(URL:String, callback(error) => {
jar.set(URL:String, cookieName:String, cookieValue:String, callback(error, cookie)):Function → Object
}):Function → Object
Function calls run asynchronously. Use a callback function to ensure functions execute in sequence.
See the Postman Collection SDK Cookie reference for more information.
Use the pm.sendRequest
methods to send a request asynchronously from a Pre-request or Post-response script. This enables you to run logic in the background if you are carrying out computation or sending multiple requests at the same time without waiting for each to complete. You can avoid blocking issues by adding a callback function so that your code can respond when Postman receives a response. You can then carry out any more processing you need on the response data.
You can pass the pm.sendRequest
method a URL string, or can provide a complete request configuration in JSON including headers, method, body, and more.
// Example with a plain string URL
pm.sendRequest('https://postman-echo.com/get', (error, response) => {
if (error) {
console.log(error);
} else {
console.log(response);
}
});
// Example with a full-fledged request
const postRequest = {
url: 'https://postman-echo.com/post',
method: 'POST',
header: {
'Content-Type': 'application/json',
'X-Foo': 'bar'
},
body: {
mode: 'raw',
raw: JSON.stringify({ key: 'this is json' })
}
};
pm.sendRequest(postRequest, (error, response) => {
console.log(error ? error : response.json());
});
// Example containing a test
pm.sendRequest('https://postman-echo.com/get', (error, response) => {
if (error) {
console.log(error);
}
pm.test('response should be okay to process', () => {
pm.expect(error).to.equal(null);
pm.expect(response).to.have.property('code', 200);
pm.expect(response).to.have.property('status', 'OK');
});
});
See the Request definition and Response structure reference docs for more information.
The pm.execution.location
property enables you to get the complete path of a request, including the folder and collection, in array format. For example, for a request named R1 in folder F1 in the C1 collection, the following post-response script code returns ["C1", "F1", "R1"]
:
console.log(pm.execution.location);
// Returns the full path of a request in array format, for example:
// ["C1", "F1", "R1"]
To get the name of the current element, use the pm.execution.location.current
property. For example, if you add the following code to the pre-request script of a folder named F1, it returns F1
:
console.log(pm.execution.location.current);
// Returns the name of the current element, for example:
// F1
You can use the pm.execution.location
and pm.execution.location.current
properties in your scripts to understand what items are run when a request is sent. This information enables you to implement logic and actions in your scripts tailored to the current location within your API testing or collection structure.
The pm.execution.skipRequest
method enables you to stop the run of a request from a pre-request script:
pm.execution.skipRequest()
You can use the pm.execution.skipRequest
method in the Pre-request tab of a request, collection, or folder. When pm.execution.skipRequest()
is encountered, the request isn't sent. Any remaining scripts in the Pre-request tab are skipped, and no tests are run. For example:
//Skip this request if an authentication token isn't present
if (!pm.environment.get('token')) {
pm.execution.skipRequest()
}
In the Collection Runner, when pm.execution.skipRequest()
is encountered, Postman skips running the current request (including its post-response scripts) and moves to the next request in order. The run results will show no response and no tests found for the request. This same behavior also applies to Postman Flows, Newman, and the Postman CLI.
Using the
pm.execution.skipRequest
method isn't supported in the Post-response tab of a request, collection, or folder and will have no effect there. You will also get aTypeError: pm.execution.skipRequest isn't a function
Console error.
The jsonSchema
method enables you to write a test assertion that validates the response data with a JSON Schema. Postman uses version 6.12.5 of the Ajv JSON Schema validator to validate response data with a JSON Schema.
To write your test assertion, use the pm.response
object and Chai Assertion Library BDD syntax to access the data returned in the response.
The jsonSchema
method accepts a JSON Schema as an object in the first argument. It also accepts an object of optional Ajv options in the second argument:
pm.response.<bdd-syntax>.jsonSchema(schema, options);
You can define a JSON Schema in Postman, such as in the Tests tab of a request. Then you can write a test that validates the properties in your response data against the defined JSON Schema.
In the following example, the JSON Schema requires the response data to contain an alpha
property that's a Boolean data type. If the response data is missing this property or it's a different data type, the test fails. This example uses BDD syntax to.have
to express the assertion:
const schema = {
"type": "object",
"properties": {
"alpha": {
"type": "boolean"
}
},
"required": ["alpha"]
};
pm.test('Response is valid', function() {
pm.response.to.have.jsonSchema(schema);
});
You can use the pm.execution.setNextRequest
method for building request workflows when you use the Collection Runner or Newman.
setNextRequest
has no effect when you run requests using Send. It only has an effect when you run a collection.
When you run a collection with the Collection Runner or Newman, Postman runs your requests in a default order or an order you specify when you set up the run. However, you can override this run order using pm.execution.setNextRequest
to specify which request to run next. For example:
Run the specified request after this one (where requestName
is the name of the collection's request, for example "Get customers"):
pm.execution.setNextRequest(requestName:String):Function
Run the specified request after this one (where requestId
is the request ID returned by pm.info.requestId
):
pm.execution.setNextRequest(requestId:String):Function
For example:
//script in another request calls:
//pm.environment.set('next', pm.info.requestId)
pm.execution.setNextRequest(pm.environment.get('next'));
Use pm.visualizer.set
to specify a template to display response data in the Postman Visualizer:
pm.visualizer.set(layout:String, data:Object, options:Object):Function
layout
required
data
optional
options
optional
Handlebars.compile()
Example usage:
var template = `<p>{{res.info}}</p>`;
pm.visualizer.set(template, {
res: pm.response.json()
});
Use pm.getData
to retrieve response data inside a Postman Visualizer template string. For example:
pm.getData(callback):Function
The callback function accepts two parameters:
error
data
pm.visualizer.set
Example usage:
pm.getData(function (error, data) {
var value = data.res.info;
});
You can use pm.test
to write test specifications inside either the Pre-request or Post-response scripts. Tests include a name and assertion:
pm.test(testName:String, specFunction:Function):Function
Postman will output test results as part of the response. The pm.test
method returns the pm
object, making the call chainable.
The following sample test checks that a response is valid to proceed:
pm.test("response should be okay to process", function () {
pm.response.to.not.be.error;
pm.response.to.have.jsonBody('');
pm.response.to.not.have.jsonBody('error');
});
An optional done
callback can be passed to pm.test
to test asynchronous functions:
pm.test('async test', function (done) {
setTimeout(() => {
pm.expect(pm.response.code).to.equal(200);
done();
}, 1500);
});
For example, to get the total number of tests run from a specific location in code:
pm.test.index():Function // Number
The pm.expect
method enables you to write assertions on your response data, using ChaiJS expect BDD syntax:
pm.expect(assertion:*):Function // Assertion
You can also use pm.response.to.have.*
and pm.response.to.be.*
to build your assertions.
See Postman test script examples for more assertions.
You can use the pm.require
method to import packages from your team's Package Library inside pre-request and post-response scripts in HTTP requests, collections, and folders. The contents of packages will only run from personal, private, and team workspaces. The Package Library enables you to reuse scripts and tests in your workspaces. Learn how to reuse scripts and tests with the Package Library.
The pm.require
method accepts the name of the package in the Package Library. Declare the method as a variable if the package has functions or objects you want to call. If the package only has code or instances of the pm
object, you don't need to declare the method as a variable:
const variableName = pm.require('@team-domain/package-name');
variableName.functionName()
The require
method enables you to use the sandbox built-in library modules. To use a library, call the require
method, pass the module name as a parameter, and assign the return object from the method to a variable:
require(moduleName:String):function
The supported libraries available for use in the sandbox include:
The following NodeJS modules are also available:
You can use tests to build Postman into your development projects in a variety of ways using Postman utilities.
Last modified: 2024/09/27
Additional resources
Videos
Blog posts