Configure and use a Postman mock server

Create mock servers in Postman to help with API development and testing. A mock server simulates a real API server by accepting requests and returning responses. By configuring a mock server for 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 in the example. To view existing mock servers in your workspace, select Mock servers in the sidebar.

Mock servers can be private or public. Private mock servers require a Postman API key in the request header. Public mock servers can receive requests from anyone and anywhere (such as a browser, application code, or a curl command). New mock servers are set to private by default. Super Admins and Team Admins can enable or prohibit users from creating public mock servers. See Manage mock server privacy to learn more.

Postman mock servers support HTTP collections. You can't use mock servers with multi-protocol collections.

Mock server quick start

To create a mock server for an API, do the following:

1. In Postman, send an HTTP request to any API (for example, https://postman-echo.com/get).
2. Select Save and save the request to a collection.
3. In the response pane, select Save Response. Postman automatically populates the example with the response you received when you sent the request.
4. Select Collections in the sidebar. Select View more actions next to the collection where the request was saved and select Mock collection.
5. Give your mock a name and leave the other settings at their defaults. Select Create Mock Server.
6. Select Copy URL to copy the mock URL, then go back to your request. Replace the base part of the URL with the mock server URL (everything before the path, for example, up to /get).
7. Add your Postman API key to the request as an x-api-key header in the Headers tab.
8. Select Send. Postman returns the example response you saved for the request, this time from the mock server.
9. Open the example and change the response, then save the example and send the request again. Postman returns your edited mock response.

Create mock servers

You can create a new mock server from scratch, from a collection, or from your history.

Create a mock server from scratch

1. Select Mock servers in the sidebar, then select Create mock server.

   If Mock servers isn't available in the sidebar, you can add it by selecting Configure workspace sidebar.

   

2. Select an existing collection. You can also create a new collection, add one or more requests, and select Next.

   

3. Configure your mock server details.

Create a mock server from a collection

1. Select Collections in the sidebar.

2. Select View more actions next to the collection you want to mock and select Mock collection.

   

3. Configure your mock server details.

Create a mock server from history

You can build a mock server based on requests from your Postman history.

1. Select History in the sidebar.

2. Select View more actions next to a request and select Mock Request. You can also mock all the requests for a particular date. Postman will create a new collection for the mocked request or requests.

   

3. Configure your mock server details.

Configure mock server details

Some configuration options may be different, depending on the method you used to create the mock server.

1. To finish creating your mock server, specify the following details:

   • Mock Server Name - Enter a name for your mock server.

   • Collection - The collection used for the mock server. To choose a different collection, select Back.

   • Environment - (Optional) Select an environment to use environment variables with your mock server.

   • Save the mock server URL as a new environment variable - Select this option to save the mock server URL as a variable in a new environment. You can then reference the variable in your requests. Learn more about using variables with mock servers.

   • Simulate a fixed network delay - Select a response delay or enter a custom delay. The mock server waits the specified time before sending the response.

   • Make mock server private - Select this option to make your mock server private. You must specify an API key in the request header when sending requests to a private mock server. Learn more about making calls to a private mock server.

     If the Make mock server private option is unavailable, it may be turned off in Team resources. A Team Admin or Super Admin can turn it back on.

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

   

3. Select Copy URL to begin making calls to your mock server.

   

Edit the mock server configuration

You can change the configuration for a mock server at any time.

1. Select Mock servers in the sidebar.

2. Select a mock server and select Edit Configuration.

   

3. Make any changes to the mock server configuration. You can change the mock server's name, environment, network delay, and privacy setting. You can also specify options for response matching.

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

4. When you are done making configuration changes, select Update Mock Server.

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

Delete a mock server

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

Make calls to mock servers

Use a mock server's URL to make calls to the mock server.

1. Select Mock servers in the sidebar, select a mock server, and select Select Copy URL.

2. Open a new request (or edit the address in an existing request) and add the mock server URL. The URL includes the mock server's ID and the path for the request you want to mock. For example:

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

3. If your mock server is private, add your Postman API key to the request as an x-api-key header. See Make calls to a private mock server to learn more.

4. Select Send to send the request to the mock server.

   Make sure the request you want to mock has at least one saved example. Learn more about adding examples to a request.

When you send a request to a 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 plan gives you a limited number of free mock server calls per month. Learn more about resource usage in Postman.

Make calls to a private mock server

By default, new Postman mock servers are private. You can make your mock server public by editing the configuration.

To make calls to a private mock server, 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.

Use HTTP access control for a mock server

In addition to using Postman to call mock endpoints, you can also make requests to a mock server using 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.

View the mock server call log

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 requests.
• 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 Delete to remove an entry from the call log.
• To copy the mock server's URL, select Copy URL. You can use the URL to make calls to the mock server.
• To view the documentation for the mocked collection, select View Collection Docs.

Troubleshoot 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's a problem with your mock server configuration. Make sure there's an example saved for the request in the collection you're 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:

• Mock your API using saved response examples
• Create and use a mock server using the Postman API
• How a Postman mock server matches requests to saved examples