Requests

You can send requests in Postman to connect to APIs you are working with. Your requests can retrieve, add, delete, and update data. Whether you are building or testing your own API, or integrating with a third-party API, you can try out your requests in Postman. Your requests can send parameters, authorization details, and any body data you require.

For example, if you're building a client application (e.g. a mobile or web app) for a store, you might send one request to retrieve the list of available products, another request to create a new order (including the selected product details), and a different request to log a customer in to their account.

When you send a request, Postman will display the response received from the API server in a way that lets you examine, visualize, and if necessary troubleshoot it.

Request Sent

If you have never sent a request before, check out sending your first request before you continue.

Contents

Creating requests

Your requests can include multiple details determining the data Postman will send to the API you are working with. At the very least you will need to enter a URL and choose a method, but you can optionally specify a variety of other details.

You can create a new request from the Postman launch screen, using New > Request, or by clicking the + button to open a new tab.

New Screen

When using the launch screen or New button, you can first give your request a name and description, and choose / create a collection to save it in. Save to create your request. It will open in a new tab.

Save Request

Once your new tab is open, you can specify the details you need for your request.

New Request

Adding request detail

If you have a request you want to run, you will need to know the URL, method, and other optional values such as auth and parameters.

If you are just trying out sending requests in Postman, you can set the URL to the Postman Echo sample API endpoint https://postman-echo.com/get and the method to GET, then click Send to see what happens.

Open the Bootcamp in the Postman app and follow Designing and mocking APIs to import some requests you can use for exploring Postman. You will find lots more sample request collections using New > Templates.

Setting request URLs

Each request you send in Postman requires a URL representing the API endpoint you are working with. Each operation you can perform using an API is typically associated with an endpoint. Each endpoint in an API is available at a particular URL—this is what you enter into Postman to access the API.

  • If you're building an API, the URL will typically be the base location plus path. For example, in the request https://api-test-fun.glitch.me/info, https://api-test-fun.glitch.me is the base URL, and /info is the endpoint path.
  • If you're using a third-party API, your API provider will supply the URLs you need, for example within their developer documentation.

When you start typing in the URL input field, Postman will present a drop-down of previously used locations you can use to autocomplete.

Enter https://postman-echo.com/get if you'd just like to try a request out.

Request URL

Postman will automatically add http:// to the start of your URL if you do not specify a protocol.

You can optionally type query parameters into the URL field, or can enter them in the Params tab. If your request uses path parameters, you can enter them directly into the URL field.

Selecting request methods

By default Postman will select the GET method for new request. GET methods are usually for retrieving data from an API. You can use a variety of other methods to send data to your APIs, including the following most common options:

  • POST—add new data
  • PUT—replace existing data
  • PATCH—update some existing data fields
  • DELETE—delete existing data
Request Methods

For example, if you're working with an API for a To Do list application, you might use a GET method to retrieve the current list of tasks, a POST method to create a new task, and a PUT or PATCH method to edit an existing task.

Postman supports a number of additional request methods by default, and you can use custom methods.

To try out the https://postman-echo.com/get endpoint, leave the GET method selected and click Send.

The same location (sometimes called "route") can provide more than one endpoint, by accepting different methods—for example, an API might have a POST /customer endpoint for adding a new customer, and a GET /customer endpoint for retrieving an existing customer.

  • If your request does not require parameters or authentication, you can go ahead and click Send to fetch a response.
  • Otherwise, specify your parameters and any body data you need to send to the API.
  • If you don't need to send data with your request, set up any required authentication and headers.

Sending parameters

You can send path and query parameters with your requests using the URL field and the Params tab.

  • Query parameters are appended to the end of the request URL, following ? and listed in key value pairs, separated by & using the following syntax: ?id=1&type=new
  • Path parameters form part of the request URL, and are referenced using placeholders preceded by : as in the following example: /customer/:id

To send a query parameter, add it directly to the URL or open Params and enter the name and value. When you enter a query parameter in one part of the Postman UI it will be reflected in the others.

Query Parameters

 Parameters will not automatically be URL-encoded. Right-click selected text, and choose EncodeURIComponent to manually encode a parameter value.

Encode Parameter

To send a path parameter, enter the parameter name into the URL field, after a colon, for example :id. When you enter a path parameter, Postman will populate it in the Params tab, where you can also edit it.

Path Parameter

You can use the Bulk Edit option if you prefer to enter your parameters in text instead of using the UI. Bulk Edit

If your request does not require body data, auth, or headers, go ahead and click Send to try it out. Otherwise, set up your body, auth, and headers.

Sending body data

You will need to send body data with requests whenever you need to add or update structured data. For example, if you're sending a request to add a new customer to a database, you might include the customer details in JSON. Typically you will use body data with PUT, POST, and PATCH requests.

The Body tab in Postman allows you to specify the data you need to send with a request. You can send various different types of body data to suit your API.

If you're sending body data, make sure you have the correct headers selected to indicate the content type your API may need to process the received data correctly.

  • For form-data and urlencoded body types, Postman will automatically attach the correct Content-Type header.
  • If you use raw mode for your body data, Postman will set a header based on the type you select (e.g. text, json).
  • If you manually select a Content-Type header, that value will take precedence over what Postman sets.
  • Postman does not set any header type for the binary body type.

By default, Postman will select None—leave it selected if you do not need to send a body with your request.

Choose the data type you need for your request body—form data, URL-encoded, raw, binary, or GraphQL.

Form data

Website forms often send data to APIs as multipart/form-data. You can replicate this in Postman using the form-data Body tab. Form data allows you to send key-value pairs, and specify the content type.

Form File

You can attach files using form data. When you repeatedly make API calls that send the same files, Postman will persist your file paths for subsequent use. This also helps you run collections that contain requests requiring file upload. Uploading multiple files each with their own content type is not supported yet.

URL-encoded

URL-encoded data uses the same encoding as URL parameters. If your API requires url-encoded data, select x-www-form-urlencoded in the Body tab of your request. Enter your key-value pairs to send with the request and Postman will encode them before sending.

URL Encoded Body

There is sometimes confusion between form data and url-encoded. If you are unsure which one you need, check with your API provider.

Raw data

You can use raw body data to send anything you can enter as text. Use the raw tab, and the type drop-down list to indicate the format of your data (Text, JavaScript, JSON, HTML, or XML) and Postman will enable syntax-highlighting as well as appending the relevant headers to your request.

Body JSON

You can set a content type header manually if you need to override the one Postman sends automatically.

You can use variables in your body data and Postman will populate their current values when sending your request.

Select text in the editor and press CMD/CTRL + B to beautify your XML/JSON.

Binary data

You can use binary data to send information you can't enter manually in the Postman editor with your request body, such as image, audio, and video files (you can also send text files).

Binary Data

GraphQL

You can send GraphQL queries with your Postman requests by selecting the GraphQL tab in the request Body. Enter your code in the Query area and any variables in the GraphQL Variables section.

GraphQL Body

Check out Using GraphQL section for more information on GraphQL, including how to enable Autocomplete powered by Postman API schemas.

Authenticating requests

Some APIs require auth details you can send in Postman. Authentication involves verifying the identity of the client sending a request, and authorization involves verifying that the client has permission to carry out the endpoint operation. Open the Authorization tab to configure your access details.

Request Auth

Postman will automatically include your auth details in the relevant part of the request, for example in Headers.

For more detail on implementing different types of auth in your Postman requests, check out Authorizing requests.

Once your auth and other request details are set up, you can click Send to run your request.

Configuring request headers

Some APIs require you to send particular headers along with requests, typically to provide additional metadata about the operation you are performing. You can set these up in the Headers tab. Enter any key-value pairs you need and Postman will send them along with your request. As you type, Postman will prompt you with common options you can use to autocomplete your setup, such as Content-Type.

Header Types

You can save commonly used headers together in a header preset. In the Headers tab, click the Presets drop-down, and choose Manage Presets. Add each preset by providing a name, and entering the key plus value. Click Add and your preset will be available in the Presets drop-down. Selecting the preset will auto-populate the fields in your request headers. Header Preset Select Preset

Once your headers and other request details are set up, you can click Send to run your request.

Using cookies

You can manage Cookies for your domains from Postman. Click Cookies under the Send button. For more information, see Managing cookies.

manage cookies modal

Choosing custom settings

You can configure a variety of settings for Postman requests using the Settings tab. These allow you to apply non-standard logic to your requests.

Request Settings

Next steps

Once you have your request set up, click Send and examine the Response. If your request does not work as expected, check out some troubleshooting tips.