Using variables

Variables enable 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. 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.

Contents

• Variables quick start
• Understanding variables
• Variable scopes
• Variable types
• Defining variables
• Accessing variables
• Sharing and persisting data
• Logging variables
• Using data variables
• Using dynamic variables
• Next steps

Variables quick start

To try out a variable:

1. Select the Environment quick look in the top right of Postman and select Edit next to Globals.
2. Add a variable named my_variable and give it an initial value of Hello.
3. Select Save and close the environment dialog.
4. 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.
5. Select Send and send the request. In the response, you'll see that Postman sent the variable value to the API.
6. 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.

Understanding variables

A variable is a symbolic representation of data that enables 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 the detail away.

For example, if you have the same URL in multiple requests, but the URL might change later, you can store the URL 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, in Newman, and in 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, and JSON.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 is https://httpbin.org, and is listed as part of the request URL using {{base_url}}/get?customers=new, Postman will send the request to https://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. See 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 variable scope

Variable scopes are suited to different tasks in Postman:

• Global variables enable 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, use a global variable to test something or when your project is at an early prototyping stage.

• Collection variables are available throughout the requests in a collection and are independent of environments, and don't change based on the selected environment.

  Collection variables are suitable if you are only using a single environment, for example for auth or URL details.

• Environment variables enable you to tailor your processing to different environments, for example local development versus testing or production. Only one environment can be active at a time.

  If you have only one environment, using collection variables can be more efficient. However environments enable 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 don't 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 with Newman or the Collection Runner.

Variable types

Beyond scope, global and environment variables can be defined by type. The two variable types that you can configure for environment and global variables are:

• Default type is the default type that is automatically assigned to variables. This type is shown as plain text and has no additional properties.
• Secret type masks the initial and current values for all workspace members and can be used to prevent unintentional disclosure of sensitive data, including API secrets, passwords, tokens, and keys.

Users with editor access on a workspace (for global variables) or environment (for environment variables) can opt to change these variables from default to secret type.

Postman will store environment and global variables as default regardless of type.

To set the variable type, select the Environment quick look in the top right of Postman. Select Edit to the right of environment or global variables to open the editor.

You can also edit an environment by navigating to the workspace it resides in and selecting Environments from the left sidebar, then selecting your environment.

You must have editor access on a workspace (for global variables) or environment (for environment variables) to control variable type.

Select default next to the variable you'd like to change to open the dropdown menu, then select secret to update the variable type and save your changes to confirm.

All workspace members can view a secret variable's initial and current values by selecting the eye symbol to the right of the variable.

Editors can change a variable's initial values, which are shared with collaborators, by selecting the eye symbol to the right of the variable, then selecting the initial value. All collaborators can change a variable's current values by selecting the eye symbol to the right of the variable, then selecting the current value.

Editors can change the variable type from secret to default at any time, and vice versa. When you change a variable's type from secret back to default, you must confirm by selecting Change type.

Defining variables

You can define variables in a variety of ways, depending on if you need global, environment, or collection scope.

To create a variable at any scope from the request builder:

1. Select the data you need, for example in the address, parameters, headers, or body.

   

2. Choose Set as variable > Set as a new variable.

   

3. Enter a Name, verify the Value, and select a scope from the drop-down list. Select 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 choose an environment in the drop-down list at the top right:

You can also activate an environment in the left sidebar, by selecting the check-mark button to make the environment active.

The environment quick look shows the selected environment along with global variables in your workspace. You can edit the current value for an existing variable inline, by selecting the value. To add a variable, select Edit next to the environment or global section.

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 Collections in the left sidebar. Select a collection, and then select the Variables tab.

If you don't have edit access to a collection, you will see a Request Access button. You won't 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 the left of a variable 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 or Control-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 access but not edit access to an environment, your script code will only affect the current value, and won't 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 don't 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 the 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 select to persist individual values). These enable 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 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 aren't 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. When you create a new variable in the UI, if you leave the current value empty, it will autofill with 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 won't 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 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 don't 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 can't set a data variable inside Postman because it's 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, use pm.variables.replaceIn(), for example 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.