Configure and use a Postman mock server

Postman enables you to create mock servers to assist with API development and testing. A mock server simulates the behavior of a real API server by accepting requests and returning responses. By adding a mock server to your collection and adding examples to your requests, you can simulate the behavior of a real API.

When you send a request to a mock server, Postman matches the request to a saved example in your collection. Postman then responds with the data you added to the example. To view existing mock servers in your workspace, select Mock Servers in the sidebar.

You need to be signed in to a Postman account to create a mock server.

Mock server quick start

To test using a mock server, do the following:

1. In Postman, send a request to any API. Your request must be saved to a collection.
2. In the response pane, select Save as Example. Postman automatically populates the example with the response you received when you sent the request.
3. Select Collections in the sidebar. Select the more actions icon next to the collection where the request was saved and select Mock collection.
4. Give your mock a name and leave the other settings at their defaults. Select Create Mock Server.
5. Copy the mock URL and go back into your request. Replace the base part of the URL with the mock server URL (everything before the path, for example up to /customers).
6. Select Send. Postman returns the example response you saved for the request, this time from the mock server.
7. Open the example and change the response, then save the example and send the request again. Postman returns your edited mock response.

Creating mock servers

You can create mock servers from an existing collection, or Postman will create a new collection for your mock server. You can create a new mock from scratch, from a collection, or from your history.

Creating a mock from scratch

Select Mock Servers in the sidebar, then select +.

Select an existing collection, or create a new collection and add an initial request.

Configure your mock server details.

Creating a mock from a collection

Select Collections in the sidebar. Select the more actions icon next to the collection you want to mock and select Mock collection.

Configure your mock server details.

Creating a mock from history

You can build a mock server based on requests from your Postman history. Select History in the sidebar, then select the more actions icon next to a request and select Mock Request. (You can also mock all the requests for particular date.)

Configure your mock server details.

Configuring mock server details

To configure your new mock server, give it a name. You can select an optional environment to have your mock sever use environment variables. You can also configure a delay before the mock server sends responses to simulate network delays.

You can save the mock URL to an environment variable in a new environment. You can then reference the variable in your requests by making the new environment active before sending the request. Learn more about using variables with mock servers.

If you choose to make your mock server private, you need to add a Postman API key in the request header when sending requests to the mock server: x-api-key:<Your-Postman-API-key>. If you share the collection, others can use their Postman API keys to make calls to the mock server.

Not all configuration options will be available, depending on the method you used to create the mock server.

After you finish selecting configuration options, select Create Mock Server. Postman displays the details you need to use the mock server. (You can get these details at any time by selecting Mock Servers in the sidebar and selecting the mock server.)

Select Copy Mock URL to begin making requests to your mock server.

To delete a mock server, select Mock Servers in the sidebar. Select the more actions icon next to the mock server's name and select Delete.

Editing the mock server configuration

You can change the configuration for a mock server at any time. Select Mock Servers in the sidebar, select a mock server, and select Edit Configuration.

You can change the mock server's name, environment, network delay, and privacy setting. You can also specify options for response matching. When you are done changing the configuration settings, select Update Mock Server.

You can't change the mock server's collection. If you need to mock a different collection, create a new mock server.

Matching request body and headers

When you send a request to the mock server, Postman uses a matching algorithm to decide which example to return in a response.

By default, the matching algorithm doesn't consider the request's body or headers when selecting the best response to return. You can change this behavior in the mock server's configuration. Using body or header matching, you can specify the exact response you want the mock server to return by matching the body or headers of the saved example.

To use body or header matching with a mock server, do the following:

1. Select Mock Servers in the sidebar, select a mock server, and select Edit Configuration.

2. Under Response Matching, select the matching options you want to use:

   • Request body - The mock server will match the request's body to the body of the saved examples.
   • Headers - The mock server will match the request's headers to the headers of the saved examples. In the box, add the header keys that you want the mock server to match, using commas to separate the keys. Header matching isn't case-sensitive.

3. Select Update Mock Server.

Making requests to mock servers

Use the mock server's URL to make calls to the mock server. Select Mock Servers in the sidebar, select a mock server, and select Copy Mock URL.

Make sure the request you want to mock has at least one saved example. You can send a request and save the response as an example. You can also define a custom example. Learn more about adding examples to a request.

Open a new request tab (or edit the address in an existing tab) and add the mock URL:

https://<mock-id>.mock.pstmn.io/<request-path>

For example:

https://4bb57fc2-219e-421e-86b4-4ffda6bf1b3b.mock.pstmn.io/matches

The mock URL includes the mock server's ID and the path for the request you want to mock. Select Send to send the request to the mock server.

When you send a request to the mock server, the mock server sends back a response based on an example with the same path and method. You can provide multiple examples, and Postman will return the one that best matches your request.

If you configured a delay for your mock server, Postman waits the specified period of time before sending the response.

Your Postman account gives you a limited number of free mock server calls per month. Check your usage limits.

Using HTTP access control for a mock

In addition to using Postman to make requests to mock endpoints, you can also make those requests in a web browser.

A web browser makes a cross-origin HTTP request when it requests a resource from a domain, protocol, or port that's different from its own. Cross-Origin Resource Sharing (CORS) is a standard that defines a way in which a browser and server can interact securely. In this case, CORS refers to how a web browser interacts with the mock endpoints hosted on the Postman mock server.

CORS is enabled for Postman mock servers, so you can stub your web apps with mocked data using the mock endpoints. Development or production web apps can then make requests to your Postman mock endpoint and receive example responses.

Viewing mock calls

You can view and search the details of calls to your mock servers using the mock call log. To view the call log, select Mock Servers in the sidebar and select a mock server.

The call log displays a list of calls made to the mock server URL. Each entry shows the time the request was sent, the request method and path, and a response overview.

You can work with the mock server call log in the following ways:

• Enter text in the search box to find particular calls.
• Select Refresh Logs to view the most recent requests.
• Select an entry for more details about the request headers and body or the response headers and body.
• Select the delete icon to remove an entry from the call log.
• To get a link to the mock server you can share with others, select Copy URL.
• To view the documentation for the mocked collection, select View Collection Docs.

Troubleshooting mock calls

You can use the mock call log to troubleshoot your requests to mock servers.

If No matching requests displays in the Response column, this might mean there is a problem with your mock server configuration. Make sure there is an example saved for the request in the collection you are mocking.

In the case of a service outage, you will get a 502, 503, or 504 response. Check the Postman status page for updates.

Next steps

To learn more about mock servers, see the following resources:

• Mocking with examples
• Mocking with the Postman API
• Matching algorithm