Building 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.

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

Contents

• Creating requests

• Adding request detail

  • Setting request URLs
  • Selecting request methods
  • Sending parameters
  • Sending body data
  • Authenticating requests

  • Configuring request headers

    • Auto-generated headers
  • Using cookies

• Choosing custom settings

  • Encoding your request URLs
• Troubleshooting your requests
• Next steps

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.

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.

Once your new tab is open, you can specify the details you need for your 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 Postman 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.

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.

You can use next generation URL encoding in your requests.

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

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. Click the method drop-down, edit the method name text, and save your new method. To delete a method, hover over it in the list and select the trash icon.

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.

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

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.

You can add descriptions to your parameters and they'll appear for anyone sharing the request (for example in your workspace) or viewing your API documentation.

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

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.

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.

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.

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).

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.

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.

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.

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.

Auto-generated headers

Postman will automatically add certain headers to your requests based on your request selections and settings. Click the hidden button at the top of the headers tab to see what Postman will send with your request.

Hover over a header to see its detail.

Postman will indicate why the header has been added.

The detail will indicate how to disable or override a header value if you need to.

Disabling or overriding recommended headers may make your request behave unexpectedly.

If you need to change a header, you can do so in the relevant part of Postman, for example the Authorization tab, the request Body, Cookies for the request domain, the Settings, and in some cases directly in the Headers tab itself.

If you need to navigate to a different part of the app, Postman will show a link on the right-hand side.

If a header has been added based on your auth setup, navigate to the Authorization tab to change it.

To alter cookie headers, amend the cookie setup for the domain you're sending the request to.

To disable an auto-generated header directly in Headers, uncheck its checkbox. To override an auto-generated header value, uncheck the auto-generated entry and add a separate entry for the header, listing its name in the Key field and specifying your value in the Value field.

If you have more than one entry for the same header, Postman will indicate which one will be overridden, prioritizing headers you have either explicitly added directly in Headers or indirectly via selections you made in the other parts of your request such as Authorization.

For Content-Length and Content-Type headers, Postman will automatically calculate values when you send your request, based on the data in the Body tab. However, you can override both values.

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.

Choosing custom settings

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

Encoding your request URLs

Postman parses and encodes your request URL in order to maximize the chances of a successful API call. Postman encodes the characters in your URL and maps them to a representation that your API is most likely to accept. The Postman URL processor is shifting towards a new standard that optimizes the chance of your request being effectively processed by the wide range of server implementations in use.

The next generation processor will encode characters depending on where they occur in the URL:

The next generation processor will be turned on by default in your Postman app, however you can turn if off and revert to legacy processing if you prefer. You can also turn off encoding if you are working with an unusual server implementation.

To configure URL encoding, first open your Postman Settings (at the top right) and toggle the Use next generation URL processing option.

You can then toggle the setting on or off in your request Settings.

Click Restore default to use your app-wide setting in a specific request.

You can selectively encode parts of your URL by highlighting the text and right-clicking, then choosing EncodeURIComponent.

Troubleshooting your requests

Postman will indicate any whitespace / potentially invalid characters in parts of your request that may not function as expected so that you can rectify your values. You will see characters highlighted in the request method, URL (including the path), parameters, headers (including your key names), and body.

If Postman is not able to send your request or does not receive a response, you will see details outlining the error.

Click View in Console to see an overview of your request and identify the source of the issue.

If your request does not work as expected, check out some troubleshooting tips.

Next steps

Once you have your request set up, click Send and examine the Response.