Run collections using imported data

When you configure a manual or scheduled collection run, you can choose to use custom data for each iteration. Select a valid CSV or JSON file with data you want to use. When you run the collection, Postman uses data from the file to populate variables in the collection's requests.

You can add a local data file to a collection run when you configure it. You can also upload a data file to your workspace, and add the file to a manual collection run when you configure it. Uploaded data files are synced to the Postman cloud and can be reused with later manual collection runs in your workspace. Scheduled runs, monitors, the Postman CLI, and Newman don't support uploaded data files.

Make sure your data file follows the data file formatting guidelines. Otherwise, you may experience errors when Postman tries to read your data file. If you experience any issues, contact Postman support.

Use a local data file

You can add a local data file to a manual collection run or scheduled collection run. The local data file is only available in the collection run, and you can't reuse the data file with a later run.

Once a local data file is added to a manual collection run, you can choose to upload the file to your workspace. This enables you and your team members with access to the workspace to reuse the file in later manual collection runs.

Use a local data file with a manual run

To use a local data file with a manual collection run, do the following:

1. Under Test data file, select Select File.

2. Select Select from computer to choose a new data file from your computer.

3. Select a local file.

4. Preview the data file. You can make the following changes before adding the local data file:

   • Select the data type dropdown list for each column to ensure the desired data type is used.

   • Select the file type dropdown list in the top right to ensure the desired file type is used.

   If you don't want to add the data file, select Remove selected file and then select a different file.

5. Select Use locally.

6. Finish configuring the manual collection run.

Once the data file is added to the manual collection run, you can select Preview next to the file to view its data and make more changes. In the preview, you can select Upload to Workspace to upload the file to the Postman cloud and share it with team members who can access the workspace. From the collection run configuration, you can also select Upload to Workspace next to the data file to upload it.

Select Remove selected file next to a data file to remove it from the collection run.

Use a local data file with a scheduled run

To use a local data file with a scheduled collection run, do the following:

1. Under Data file, select Select file.
2. Select a local file.
3. Finish configuring the scheduled collection run.

Once the data file is added to the scheduled collection run, select the file type dropdown list to change the type if needed. Then you can select Preview to view the file's data before you run the collection.

Select next to a data file to remove it from the scheduled collection run.

Use an uploaded data file

You can upload a data file to a manual collection run in your workspace, syncing the file with the Postman cloud. You must have Editor permissions to upload a data file to a workspace. You and your team members who can access the workspace can reuse the uploaded data file with later manual collection runs in the workspace. Note that scheduled runs, monitors, the Postman CLI, and Newman don't support uploaded data files.

Data files are only available in the workspace they were uploaded to. To use the same data file in another workspace, you must upload the data file to the other workspace as well.

Data files must be smaller than 5 MB to upload to your workspace.

To upload a data file and add it to a manual collection run, do the following:

1. Under Test data file, select Select File.

2. Choose one of the following:

   • To upload a new data file, select Select from computer and select a data file from your computer. Note that Postman will rename your file if its name matches a file already uploaded.
   • Select a data file you or a team member uploaded to the workspace.

3. Preview the data file. You can make the following changes before uploading or adding the data file:

   • Select the data type dropdown list for each column to ensure the desired data type is used.

   • Select the file type dropdown list in the top right to ensure the desired file type is used.

   If you don't want to upload or add the data file, select Remove file from run and then select a different file.

4. Select Upload to Workspace or Continue. The new data file is uploaded to the Postman cloud, and the data file is added to the manual collection run.

5. Finish configuring the manual collection run.

If the data file fails to upload, it'll be added to the manual collection run as a local data file. Hover over next to the data file for more options. You can select Retry to try to upload the data file again. You can also select Ignore to ignore the warning.

Once a data file is added to the manual collection run, you can select Preview next to the file to view its data and make more changes. In the preview and next to the data file, you can hover over to view the file size, team member who uploaded the file, and the date it was uploaded.

Select Remove selected file next to a data file to remove it from the collection run.

Your Postman plan gives you a limited amount of storage space you can use for uploaded data files. Your plan also gives you a limited number of retrievals of uploaded files. Learn more about test data usage.

Format a data file

Before you upload or use a CSV or JSON file with a collection run, ensure the file follows the formatting guidelines. Learn how to format a CSV file and format a JSON file.

For example, you may have a collection with requests that accept both a serial number and a contact number as query parameters. The respective values must be variables like {{serial}} and {{contact_no}} in your request. Then you can format your file to use the same variable names according to the file's respective guidelines. Note that variable names are case sensitive, so the name and case must match between Postman and your data file.

Variables in data files resolve as local variables. You can write a test script that checks each value, such as confirming the values are valid. Learn more about how to use iteration data in scripts.

CSV file format

For a CSV file, the first row must have the variable names you want inside the requests. Then every row after will be used as a data row. Each line ending must be in Unix format, and each row must have the same number of columns.

Be aware of the following when formatting a CSV file:

• If the numbers in your data file are longer than 15 digits, you'll need to format them as text in your spreadsheet program, so they're not truncated when exporting to CSV format.
• If your CSV file has numbers longer than 16 digits, numbers with preceding zeroes (for example, 000000345), or phone numbers (for example, +12125556709), you'll need to preview the file and specify the data type for the column in Postman.

City,Ramen
Vancouver,100
San Francisco,84
Singapore,79
Austin,66
Los Angeles,65

JSON file format

For a JSON file, the data must be formatted as an array of key-value pairs. Each key is the variable name, and each value is the data that'll be used in the request.

[
  {
    "City": "Vancouver",
    "Ramen": 100
  },
  {
    "City": "San Francisco",
    "Ramen": 84
  },
  {
    "City": "Singapore",
    "Ramen": 79
  },
  {
    "City": "Austin",
    "Ramen": 66
  },
  {
    "City": "Los Angeles",
    "Ramen": 65
  }
]