Reference requests and examples in local mock servers

The pm.mock object provides structured, Postman-aware functions for matching incoming requests and sending responses with a local mock server. The pm.mock API can serve responses from your existing saved Postman examples rather than hard-coding everything.

pm.mock

Use the pm.mock methods to match incoming requests and send responses, including responses from your existing saved Postman examples.

pm.mock.matchRequest()

Matches an incoming request against a Postman request by its method and path. Returns true if the incoming request matches the specified criteria.

Example:

1
if (pm.mock.matchRequest('<request-id>', req)) {
2
  res.status(200).json([{ id: 1, name: 'Alice' }]);
3
  return;
4
}

You can also pass a Postman request ID (the unique ID of a saved request in your collection) instead of specifying the method and path. This matches using the saved request’s method and URL.

pm.mock.sendExample()

Sends a saved Postman example as the HTTP response. This is the key integration point between your existing Postman collection data and your mock server.

1
if (pm.mock.matchRequest('<request-id>', req)) {
2
  pm.mock.sendExample('<example-id>', res);
3
  return;
4
}

In this example, <request-id> is the ID of a saved request in your Postman collection and <example-id> is the ID of a saved example under that request. The example’s status code, headers, and body are all sent as the response.

Rather than looking up IDs manually, Postman provides a searchable dropdown directly in the mock code editor. When you click on the string argument of matchRequest or sendExample, a dropdown list appears where you can search your workspace’s requests and examples by name or URL path.

Below is a complete example using the pm.mock API:

1
// Match GET /users and serve the saved "List Users - 200 OK" example
2
if (pm.mock.matchRequest('<get-users-request-id>', req)) {
3
  pm.mock.sendExample('<list-users-200-example-id>', res);
4
  return;
5
}
6
7
// Match GET /users/:id with a path variable
8
if (pm.mock.matchRequest('<request-id>', req)) {
9
  if (req.params.id === '999') {
10
    res.status(404).json({ error: 'User not found' });
11
  } else {
12
    pm.mock.sendExample('<get-user-200-example-id>', res);
13
  }
14
  return;
15
}
16
17
// Match POST /users
18
if (pm.mock.matchRequest('<request-id>', req)) {
19
  pm.mock.sendExample('<create-user-201-example-id>', res);
20
  return;
21
}
22
23
res.status(404).json({ error: 'Route not matched' });

Path variable matching

The matching algorithm supports path variables, which are URL segments prefixed with : that match any value in that position.

Example:

1
// Matches /products/42, /products/abc, /products/anything
2
if (pm.mock.matchRequest('<request-id>', req)) {
3
  console.log('Requested product ID:', req.params.id);
4
  res.status(200).json({ id: req.params.id, name: 'Example Product' });
5
  return;
6
}
7
8
// Nested path variables also work
9
if (pm.mock.matchRequest('<request-id>', req)) {
10
  res.status(200).json({
11
    orgId: req.params.orgId,
12
    userId: req.params.userId
13
  });
14
  return;
15
}

Mock your API with a response example

To customize your local mock server implementation, you need to create a collection with a request to your API and save the response as an example.

1. Click the Development tab in the sidebar.
2. Create a collection.
3. Create and send a request to your API.
4. In the response area, click Save Response to save the response as an example.