- Introduction
- Installing and updating
- Navigating Postman
- Sending your first request
- Managing your account
- Syncing your work
- Discovering templates
- Creating your first collection
- Creating a workspace
- Setting up Postman
- Importing and exporting data
- Troubleshooting app issues
- Building requests
- Authorizing requests
- Receiving responses
- Grouping requests in collections
- Using variables
- Managing environments
- Visualizing responses
- Specifying examples
- Using cookies
- Working with certificates
- Generating client code
- Troubleshooting requests
- Using the Collection Runner
- Scheduling runs with monitors
- Building request workflows
- Importing data files
- Working with your team
- Defining roles
- Requesting access
- Sharing your work
- Your Private API Network
- Commenting on collections
- Versioning APIs
- Using version control
- Using the API Builder
- Managing and sharing APIs
- Validating APIs
- Monitoring your APIs
- Setting up a monitor
- Viewing monitor results
- Monitoring APIs and websites
- Set up integrations to receive alerts
- Running Postman monitors using static IPs
- Troubleshooting monitors
- Monitoring FAQs
- Analyzing with reports
- Documenting your API
- Authoring your docs
- Publishing your docs
- Viewing documentation
- Using custom domains
- Publishing templates
- Publishing to the API Network
- Submission guidelines
- Managing your team
- Purchasing Postman
- Billing
- Configuring team settings
- Utilizing audit logs
- Onboarding checklist
- Migrating data between teams
- Intro to SSO
- Configuring SSO for a team
- Logging in to an SSO team
- Microsoft AD FS
- Custom SAML in Azure AD
- Custom SAML in Duo
- Custom SAML in GSuite
- Custom SAML in Okta
- Custom SAML in Onelogin
- Custom SAML in Ping Identity
- Migrating to the current version of Postman
Using variables
Variables allow you to store and reuse values in your requests and scripts. By storing a value in a variable, you can reference it throughout your collections, environments, and requests—and if you need to update the value, you only have to change it in one place. Using variables increases your ability to work efficiently and minimizes the likelihood of error.
Variables quick start
To try out a variable, use the following steps:
- Click the Environment quick look (eye button) in the top right of Postman and click Edit next to Globals.
- Add a variable named
my_variable
and give it an initial value ofHello
—click Save and close the environment modal. - Open a new request tab and enter
https://postman-echo.com/get?var={{my_variable}}
as the URL. Hover over the variable name and you'll see the value. - Send the request. In the response, you'll see that Postman sent the variable value to the API. Try changing the value in the Environment quick look and sending the request again.
Read on for more detail on how you can use variables in Postman.
Contents
- Understanding variables
- Variable scopes
- Defining variables
- Accessing variables
- Sharing and persisting data
- Logging variables
- Using data variables
- Using dynamic variables
- Next steps
Understanding variables
A variable is a symbolic representation of data that allows you to access a value without having to enter it manually wherever you need it. This can be useful especially if you are using the same values in multiple places. Variables make your requests more flexible and readable, by abstracting some of the detail away.
For example, if you have the same URL in multiple requests—but the URL might change—you can store it in a variable. If the URL changes, you only need to change the variable value and it will be reflected throughout your collection, wherever you've used the variable name. The same principle applies to any part of your request where data is repeated.

Postman supports variables at different scopes, allowing you to tailor your processing to a variety of development, testing, and collaboration tasks. Scopes in Postman relate to the different contexts that your requests run in—within Postman, in collections, in environments, and in Newman / the Collection Runner. You can use variables to pass data between requests and tests, for example if you are chaining requests using a collection.
Postman will store environment and global variables as strings. If you’re storing objects or arrays, remember to
JSON.stringify()
them before storing, andJSON.parse()
them when you retrieve them.
Variables in Postman are key-value pairs. Each variable name represents its key, so referencing the variable name allows you to access its value.
For example, if you have a base URL for requests stored in a variable named
base_url
, you can reference it in your requests using{{base_url}}
. Whatever value is stored in the variable will be included wherever you've referenced the variable when your requests run. If the base URL value ishttps://httpbin.org
, and is listed as part of the request URL using{{base_url}}/get?customers=new
, Postman will send the request tohttps://httpbin.org/get?customers=new
.
You can use environments to group sets of variables together and share them with collaborators, for example if you use one set of config details for your production server and another for testing. Check out Managing environments for more on how you can incorporate environments into your team workflows.
Variable scopes
Postman supports the following variable scopes:
- Global
- Collection
- Environment
- Data
- Local

If a variable with the same name is declared in two different scopes, the value stored in the variable with narrowest scope will be used—for example if there is a global and a local variable both named
username
, the local value will be used when the request runs.
Choosing variables
Variable scopes are suited to different tasks in Postman:
-
Global variables allow you to access data between collections, requests, test scripts, and environments. Global variables are available throughout a workspace.
- Since global variables can create confusion, you should only use them sparingly—for example to quickly test something or when your project is at a very early prototyping stage.
-
Collection variables are available throughout the requests in a collection and are independent of environments, so do not change based on the selected environment.
- Collection variables are suitable if you are only using a single environment, for example for auth / URL details.
-
Environment variables allow you to tailor your processing to different environments, for example local development vs testing or production. Only one environment can be active at a time.
- If you only have one environment, using collection variables can be more efficient, however environments allow you to specify role-based access levels.
-
Local variables are temporary, and only accessible in your request scripts. Local variable values are scoped to a single request or collection run, and are no longer available when the run is complete.
- Local variables are suitable if you need a value to override all other variable scopes but do not want the value to persist once execution has ended.
- Data variables come from external CSV and JSON files to define data sets you can use when running collections via Newman or the Collection Runner.
Defining variables
You can define variables in a variety of ways, depending on whether you need global / environment, or collection scope.
To create a variable at any scope from the request builder, select the data you need, for example in the address, parameters, headers, or body.

Choose Set as variable > Set as a new variable.

Enter a Name, verify the Value and select a scope from the drop-down list. Click Set variable.

Remember to delete variables you are no longer using.
Defining global and environment variables
You can create and edit environment variables by selecting Environments on the left of Postman, or using the Environment quick look at the top right.
You can select an environment in the drop-down at the top right, or in the left sidebar, by clicking the check-mark button to make the environment active.
In the environment quick look you will see the selected environment along with global variables in your workspace. You can edit the current value for an existing variable inline, by clicking the value. To add a variable, click Edit next to the environment or global section.
You can also access the quick look using the keyboard shortcut
CMD/CTRL + ALT + E
.
You can only add and edit variables in environments if you have edit access to the environment as a whole. If you have view access, you can update the current value of existing variables only. Any variables you edit will only be accessible to you, and not available to collaborators in your workspace.
See Managing environments for more on working with environments in your team.
Once you have your scope selected, you can specify the variable detail.
You can also define global and environment variables in scripts.
Defining collection variables
You can add collection variables when you create the collection or at any time after that. To create or edit a variable for an existing collection, select the collection in Collections sidebar on the left of Postman and choose Variables.
If you do not have edit access to a collection, you will see a Request Access button.
Without edit access you will not be able to add new collection variables, update initial values, or persist values.
You can edit the current value for local use, override the collection variable by using an environment variable with the same name, or request access to the collection for Editor role.
You can also define collection variables in scripts.
Specifying variable detail
You can add and edit variables at any time. All you need to include for a new variable is a name—you can choose to supply an initial value but can alternatively set it later, including from scripts. Use the checkbox to enable or disable a variable.
Initial values are shared when you share a collection or environment. Current values are local and not synced or shared. See Sharing and persisting data for more on local vs synced variables.
You can download global variables as JSON from Manage Environments.
You can set response body values to variables by selecting text, right-clicking / CTRL + clicking, and choosing the relevant variable by name.

Defining variables in scripts
You can set variables programmatically in your request scripts.
Use pm.globals
to define a global variable:
pm.globals.set("variable_key", "variable_value");
Use pm.collectionVariables
to define a collection variable:
pm.collectionVariables.set("variable_key", "variable_value");
Use pm.environment
to define an environment variable (in the currently selected environment):
pm.environment.set("variable_key", "variable_value");
If you have view but not edit access to an environment, your script code will only affect the current value, and will not be synced or shared with your team.
You can use unset
to remove a variable:
pm.environment.unset("variable_key");
Check out the Sandbox Reference for more on scripting with variables.
Defining local variables
Local variables are temporary values you set in your request scripts using the following syntax:
pm.variables.set("variable_key", "variable_value");
Local variables do not persist between sessions, but allow you to override all other scopes temporarily, during the execution of a request or collection / monitor run. For example, if you need to process a temporary test value for a single request or collection run locally, and don't want the value to sync with your team or remain available when the request / collection has finished running, you can use a local variable.
Accessing variables
You can use double curly braces to reference variables throughout the Postman user interface. For example, to reference a variable named "username" in your request auth settings, you could use the following syntax with double curly braces around the name:
{{username}}
When you run a request, Postman will resolve the variable and replace it with its current value.
For example, you could have a request URL referencing a variable as follows:
http://pricey-trilby.glitch.me/customer?id={{cust_id}}
Postman will send whatever value you currently have stored for the cust_id
variable when the request runs. If cust_id
is currently 3
, the request will be sent to the following URL including query parameter:
http://pricey-trilby.glitch.me/customer?id=3
Alternatively, you could have a request body that accesses a variable by wrapping its reference in double-quotes:
{ "customer_id" : "{{cust_id}}" }
You can use variables in request URLs, parameters, headers, authorization, body, and header presets.
When you hover over a variable you can see an overview of its current status. As you type variables into your requests, Postman will prompt you with any that are currently defined.
The prompt will indicate current value, scope (highlighted by color), and overridden status where relevant.
If a variable is unresolved, Postman will highlight it in red.

Using variables in scripts
You can retrieve the current value of a variable in your scripts using the object representing the scope level and the .get
method:
//access a variable at any scope including local
pm.variables.get("variable_key");
//access a global variable
pm.globals.get("variable_key");
//access a collection variable
pm.collectionVariables.get("variable_key");
//access an environment variable
pm.environment.get("variable_key");
Using
pm.variables.get()
to access variables in your scripts gives you the option to change variable scope without affecting your script functionality. This method will return whatever variable currently has highest precedence (or narrowest scope).
Sharing and persisting data
When you edit global, collection, and environment variables in Postman, you will see Current Value, Persist, and Reset options for individual variables and for all variables (hover over a variable and use ... to persist individual values). These allow you to control what happens within your local instance of Postman, independently of how the data is synced with anyone sharing your workspace, requests, collections, and environments.
Your local session in Postman can use values that are transient and only visible to you. This lets you develop and test using private credentials or experimental values, without risk of exposing these details or affecting others on your team.
For example, your team could have a shared API key and individual API keys—you could do more experimental development work locally using your personal key, but use the shared key for team collaboration. Similarly, you could have a variable that represents exploratory work you're doing locally but are not ready to share with the team—you can later choose to persist the local data so that others on your team can also access it.
When you create or edit a variable, you can enter both an initial and a current value. You can choose to leave the current value empty, in which case it will default to the initial value. If you specify a current value, it will be local only to your instance—the Persist option lets you push your current value to the shared data, updating the initial value to match the current value.
You can only edit the initial value of an environment variable if you have edit access to the environment itself. Without edit access to the environment, you can only edit the current value and your edit will not be visible to anyone sharing your workspace.
Using Persist will make your current value sync with Postman's servers and be reflected for anyone sharing your collection or environment. To reset your current local values to reflect the initial (shared) values, use Reset.
You can set Postman to automatically persist your variable values.
You can edit a current value inline from the environment quick look:

See Managing environments for more on working with variables as a team.
Local and data variables only have current values, which do not persist beyond request or collection runs.
Logging variables
You can log variable values to the Postman Console while your requests run. Open the console from the button on the bottom left of Postman, or from the View menu. To log the value of a variable, use the following syntax in your script:
console.log(pm.variables.get("variable_key"));
Using data variables
The Collection Runner lets you import a CSV or a JSON file, and use the values from the data file inside requests and scripts. You cannot set a data variable inside Postman because it is pulled from the data file, but you can access data variables inside scripts, for example using pm.iterationData.get("variable_name")
.
See working with data files and the Sandbox API reference for more.
Using dynamic variables
Postman provides dynamic variables that you can use in your requests.
Examples of dynamic variables are as follows:
{{$guid}}
: A v4 style guid{{$timestamp}}
: The current timestamp (Unix timestamp in seconds){{$randomInt}}
: A random integer between 0 and 1000
See the Dynamic Variables section for a full list.
To use dynamic variables in pre-request or test scripts, you need to use
pm.variables.replaceIn()
, e.g.pm.variables.replaceIn('{{$randomFirstName}}')
.
Next steps
For an overview of how you can manage and share variable data sets, see Managing environments. Check out Intro to scripts for more on using variables in your request scripting, and Grouping requests in collections for more on how you can use data between requests.