Add Steps to Tests

To add a test step to a Zephyr Squad test, send a POST request to /rest/zapi/latest/teststep/{issueId} with a JSON body containing properties of the created test step.

A test typically includes several steps. So, you will have to call this operation several times, each time passing different parameters.

Request URL


  • issueId - Required, number. Specifies the internal Jira ID of the Zephyr Test item to which you are going to add a test step. See how to get this ID.

Request body

The request body contains a JSON object that specifies properties of the new step, for example:


"step": "Enter the date",

"data": "01/Dec/2021",

"result": "The reported number should be 3."


These are the values of the test step’s text, data, and expected result. You can see these in the Test item screen in the Jira UI:

Test step fields in Jira

These values can include HTML tags.

Other request parameters

Every request must include authentication parameters. See Zephyr Squad Server REST API.


Operation reference



A successful response has the HTTP status 200 OK. Its body contains the JSON object with properties of the created step, for example:


"id": 14248,

"orderId": 1,

"step": "Enter the date",

"data": "01/Dec/2021",

"result": "The reported number of events should be equal to 3.",

"createdBy": "JIRAUSER10000",

"modifiedBy": "JIRAUSER10000",

"htmlStep": "<p>Enter the date</p>",

"htmlData": "<p>01/Dec/2021</p>",

"htmlResult": "<p>The reported number of events should be equal to 3.</p>",

"totalStepCount": 1,

"customFieldValuesMap": {}


Property description




The ID of the created step.


The position of the test step in the test case. The first step has position 1.




The test step’s text, data, and expected result in the plain text format.




The test step’s text, data, and expected result in the HTML format.


The Jira ID of the user who created the step.


The Jira ID of the user who modified the step.


The total number of steps in the test case (including the just created step).


The object whose properties contain values of the custom Zephyr fields (if any).

In case of an error, the server typically returns the 4xx or 5xx response code. The response body contains the description of the error (with certain exceptions). Here are some examples:

  • If the issueId parameter specifies a non-existing ID, the server returns 400 Bad Request, and the response body contains the following:

        "message": "IssueId 24620333 is Invalid."
  • Invalid JSON data in the request body causes an error on the server. In this case, the response code will be 500 Internal Server Error, and the response body will contain the exception text and the call stack.

  • If the request has invalid authentication parameters, the response will have the HTTP status 200 OK and the following body:

    "errorDesc": "You do not have the permission to make this request. Login Required.",
    "errorId": "ERROR"

Next steps

go.gifCreate Cycle

go.gifAdd Tests to Cycle

See Also

Zephyr Squad Server REST API

Publication date: