Skip to main content

Create Dynamic Mock Using Templates

Beeceptor takes advantage of the powerful Handlebars templating engine to provide dynamic mocked responses. This allows mocking rules to leverage attributes from the request payload and query parameters to generate responses that are tailored to the specific needs of the request, hence giving a personalized response to each request.


This feature is available with paid plans and takes the API mocking experience near to realistic.

Enabling template in a mocking rule

Beeceptor parses incoming request for request payload and query parameters as a JSON object. This object is available to template engine to be substituted response. Here are a few facts you should know before you start using this.

  • The template engine uses Handlebars's syntax.
  • By default, template engine is off. You need to explicitly mark a rule to enable usage of Handlebars template.

Editing a mocking rule

A handlebars expression is enclosed between {{ and }}. When the template is executed, these expressions are replaced with values from a request object. Beeceptor uses special Handlebars helpers to extract request parameters.

When there are syntax errors in defining templates, Beeceptor tries to recover safely and attempts to generate the mocked response. If there are unrecoverable errors, a response with 561 status code is returned. In such cases, you should review the template syntax and correct it.

Request payload helpers

These helpers allow you to pick any request parameter and send in mocked response.


Beeceptor supports following types of template helpers to extract request parameters and add to mocked response. The request payload is parsed only if the entering Content-Type is set to one of below.

  • JSON payload - application/json, application/json; charset=utf-8, application/vnd.api+json, application/ld+json, etc.
  • Form URL encoded - application/x-www-form-urlencoded
Helper NameDescription & syntax
bodyExtracts request payload/body from either JSON or Form URL Encoded. Both of these are built into JSON object to be used in the template. This typically works for POST, PATCH and PUT types of HTTP verbs.

{{body 'path' 'default-value'}}

queryParamExtracts query parameters and builds a JSON object to be used in the template. This works for all HTTP verbs.

{{queryParam 'path' 'default-value'}}

The path parameter allows accessing deep properties as flat key-names. Some examples are keyName, parent.child, keyName.1.childKey. This works for JSON Objects and JSON Arrays as object roots.
pathParamIf you are matching a request using regular expression (RegEx) on the request path, you can use named groups. All the named groups and their values are available to be used in the template.

{{pathParam 'group-name' 'default-value'}}

Here is an example where entity_id and child_id are defined as named groups in the mocking rule. These can be accessed in the template body as below: pathParam-example-mocking-rules
headerAll the request headers are available and can be used in the template. The headers are case-insensitive and you should use lowercase values in this syntax.

{{header 'header-name' 'default-value'}}

Here is an example on how to use header syntax: header-value-in-template

Parameter details:

  • The path, group-name or header-name are the required parameter in the above syntax.
  • The default value parameter is optional, and it falls back to empty string. If no value is found corresponding to given path or first parameter, the default-value is returned.


Consider a following example with mocking rule and request payload:

Mocking Template: Here is an example mocking template defined in a rule.

"type": "{{queryParam 'type'}}",
"address": "{{body 'address'}}",
"age": {{body 'age' '0'}},
"full_name": "{{body 'name.first'}} - {{body 'name.last'}}"

Request: Request payload entering with application/json content-type

at server path `/my-rule?type=individual`
"address": "80, Pearl Residency, MG Road, India",
"age": 99,
"name": {"first": "Arti", "last": "Jain"}

Response: Beeceptor will generate following response body. Here individual is picked from query parameter and rest from the JSON request payload.

"type": "individual",
"address": "80, Pearl Residency, MG Road, India",
"age": 99,
"full_name": "Arti - Jain"