Mock server responses matching request query string params




I am testing Postman Mock Server functionality and I am not able to understand how does the matching algorithm works.
Especially, is it possible to returns different response according to to matching request query params values ?

For instance:

http://domain/path&code=1 would return a save Response with the exactly same request (except the http/domain part which would be replaced by the mock cloud domain).

http://domain/path&code=2 would return another (different response) associated with the exact same request.

Or is the comparison made only on the path ?



Hi @overflow! Our docs haven’t been updated on this yet (working on it!) but we recently added two new optional headers: x-mock-response-name and x-mock-response-id, either of which can be used to specify the exact response you want to receive.

x-mock-response-name = The name of your saved example, which you can view in our UI or by calling our Postman API.

x-mock-response-id = The ID of your saved example, which you can find via exporting your collection or by calling our Postman API w/ GET (Single Collection), which will list the response ID under the request it’s associated with.


Hello @claire !

Thank you so much for your detailed answer ! So I understood how those headers works using Postman API however I don’t think this might be of any use for my use case. Let me explain.

I am doing integration testing black boxing my application.
I send a batch of requests with associated responses.

I do send requests to routes exposed by my application which are POST with some parameters in the request body. My mock server is then called by the application but the Headers aren’t passed from my entry request to the GET request onto the mock server.

That’s why my unique solution without making any modification to my app would have been examples served correctly by the matching algorithm.

Do you think there’s a solution for this use case ?



As of today, there is no way for you to achieve what you want without specifying the extra headers.

The mock server currently does not look at the query params while matching requests to examples. This means if your examples differ in only the query params, mock will consistently return the first example that it finds that matches the path. You can of-course use the x-mock-response-name or the x-mock-response-id headers to explicitly specify which example you want Mock server to return.

You could maintain a mapping on your application side (mapping a signature of url + query params to the example id or name). You can also use a Mock server to dynamically serve this data and then add the corresponding x-mock-response-name to the request url that matches that signature.


I have a similar situation where I want to mock different responses for different query parameters on the same path.

I’m a bit confused by the need to use the x-mock-* headers. I understand how the headers are used, and I can add the headers to have the correct response returned. However, unless I’m missing something, the whole point of setting up the mock is so that I can “mock” the actual API calls without having to change my calls. Having to add the headers means that I’m having to modify my calls to include those headers.

My goal is to simply be able to configure the server that my application is pointing to for the API calls from the real (or yet-to-be-created) API server to the mock server. That means I should not have to modify my code to add headers that are specific to the mock service. Those headers have no bearing on the actual API, so I don’t want to then remove those headers before I connect to the real API.

Am I missing something in how we’re supposed to go about using the mock servers?


We do plan to improve the Mock server functionality by providing better ways to match requests to responses and that includes query param matching. However, as of today, using the x-mock-* headers is the only workaround we have.


Any word on this? The custom header doesn’t really work for integration testing or development - after all, we don’t want to write production code that contains headers for Postman mocks… We’re about to switching to an API gateway just for the sake of being able to develop against some somewhat dynamic endpoint mockups, but would love to keep things in Postman.


Would be great to get an update on when/if we can use query param matching!


This is a huge disappointment for me. The documentation needs to be more clear on this. It can be very time consuming trying inject headers when you have multiple requests in a large system.


Hi, just want to +1 on this. Adding query parameters to the matching algorithm would be greatly appreciated.


I agree this functionality is greatly needed and it would be best if we could also define POST body based responses - match a certain POST body.

Truly, we can’t mock anything with the current system. Luckily, I have a very limited API for the next few weeks. After that, we will outgrow the current mock functionality and Postman’s usefulness decreases rapidly.


This is coming soon folks. Thank you for your patience!


I also fell into this trap. According to the documentation, the mock server matches strict request/response pairs so I assumed everything I enter in the “Example request” area is taken into account. It didn’t work for my POST requests that only differ in the body. Before I was going to convert my requests to more familiar GET-based, I searched for the exact matching algorithm and stumbled upon this. I can’t believe even this won’t work.

I might be understanding web APIs wrong, but isn’t it normal that requests that differ by URL belong in different ‘requests’ and those with the same URL but with different parameters belong to the same request but to different Examples?


It didn’t work for my POST requests that only differ in the body.

Same situation for me. I’m using v6.7.2. I have two different examples in a POST request. They differ only in body x-www-form-urlencoded part. When I try to get, only the first one is returned from mock server in all conditions.

@abhinav Is this feature in postman’s roadmap? If yes, in which version will it be released?

Currently, I’ll go with x-mock-response-name. I love Postman by the way. Great job! :blush: