> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Add step to template's workflow

POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/templates/{templateId}/workflow/steps
Content-Type: application/json

Adds a new step to a template's workflow.

Reference: https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopeworkflowdefinition/createtemplateworkflowstepdefinition

## Authentication

- `Authorization` header (required) (prefixed with ` Bearer  `) — OAuth 2.0 access token (JWT or auth-code grant). Sent as `Authorization: Bearer <token>` on every request except `GET /v2.1` and `GET /service_information`, which are public discovery endpoints.

## Servers

- `https://demo.docusign.net/restapi` (Demo, default)
- `https://www.docusign.net/restapi` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The external account number (int) or account ID Guid.
- `templateId` (string, required) — The ID of the template.

### Body (application/json)

This endpoint expects a workflowStep.

- `action` (string, optional) — Indicates the action to perform. Valid values: - `pause_before`: The workflow should pause before the trigger described by `triggerOnItem` is reached.
- `completedDate` (string, optional) — The timestamp of when the workflow step transitioned to `completed` status. This property is read-only.
- `delayedRouting` (delayedRouting, optional) — A complex element that specifies the delayed routing settings for the workflow step.
- `itemId` (string, optional) — The unique ID of the item being triggered.
- `recipientRouting` (recipientRouting, optional) — Describes the recipient routing rules.
- `status` (string, optional) — The status of the step. Valid values: - `inactive` - `in_progress` - `paused` - `pending` - `completed` This property is read-only.
- `triggeredDate` (string, optional) — The timestamp of when the workflow step transitioned to `in_progress` status. This property is read-only.
- `triggerOnItem` (string, optional) — The type of item that triggers this workflow step. Valid values: - `routing_order`
- `workflowStepId` (string, optional) — A unique identifier for this workflow step. This property is read-only.

## Response

### 201

Successful response.

- `action` (string, optional) — Indicates the action to perform. Valid values: - `pause_before`: The workflow should pause before the trigger described by `triggerOnItem` is reached.
- `completedDate` (string, optional) — The timestamp of when the workflow step transitioned to `completed` status. This property is read-only.
- `delayedRouting` (delayedRouting, optional) — A complex element that specifies the delayed routing settings for the workflow step.
- `itemId` (string, optional) — The unique ID of the item being triggered.
- `recipientRouting` (recipientRouting, optional) — Describes the recipient routing rules.
- `status` (string, optional) — The status of the step. Valid values: - `inactive` - `in_progress` - `paused` - `pending` - `completed` This property is read-only.
- `triggeredDate` (string, optional) — The timestamp of when the workflow step transitioned to `in_progress` status. This property is read-only.
- `triggerOnItem` (string, optional) — The type of item that triggers this workflow step. Valid values: - `routing_order`
- `workflowStepId` (string, optional) — A unique identifier for this workflow step. This property is read-only.

## Errors

### 400 Bad Request Error

Error encountered.

- `errorCode` (string, optional) — The code associated with the error condition.
- `message` (string, optional) — A brief message describing the error condition.

## Types

### delayedRouting

A complex element that specifies the delayed routing settings for the workflow step.

- `resumeDate` (string, optional) — The ISO 8601 timestamp of when the envelope is scheduled to be sent to the recipients associated with the workflow step. This property is `null` if the workflow step has not been initiated. This property is read-only.
- `rules` (list of envelopeDelayRule, optional) — User-specified rules indicating how and when the envelope should sent for the workflow step and its associated recipients. Only one rule may be specified.
- `status` (string, optional) — Status of the delayed routing step. Valid values: - `pending`: The workflow step has not been reached and the delay has not been initiated. - `started`: The workflow step has begun and the delay is in progress. The envelope has not yet been sent to the workflow step's recipients. - `completed`: The delay has elapsed and the envelope has been sent to the workflow step's recipients. This property is read-only.

### recipientRouting

Describes the recipient routing rules.

- `rules` (recipientRules, optional)

### envelopeDelayRule

A user-specified object that describes the envelope delay. To indicate a relative delay, use `delay`. To indicate the exact datetime the envelope should be sent, use `resumeDate`. Only one of the two properties can be used.

- `delay` (string, optional) — A string timespan representing the duration of the sending delay. The timespan is in the format `d.hh:mm:ss` where `d` is the number of days, `hh` is the number of hours (measured on a 24-hour clock), `mm` is minutes, and `ss` is seconds. The maximum delay is 30 days.
- `resumeDate` (string, optional) — An ISO 8601 formatted datetime string indicating the date and time that the envelope will be sent. The specified datetime must occur in the future. It must not exceed 30 days from the time that the request is made.

### recipientRules

- `conditionalRecipients` (list of conditionalRecipientRule, optional)

### conditionalRecipientRule

A rule that defines a set of recipients and the conditions under which they will be used for the envelope.

- `conditions` (list of conditionalRecipientRuleCondition, optional) — An array of conditions that define when the recipients will be used.
- `order` (string, optional) — An integer that specifies the order in which rules are processed. Lower values are processed before higher values.
- `recipientGroup` (recipientGroup, optional) — Describes a group of recipients.
- `recipientId` (string, optional) — The ID of the recipient to whom the condition will be applied. This value should match the `recipientId` defined in the recipient object.

### conditionalRecipientRuleCondition

- `filters` (list of conditionalRecipientRuleFilter, optional)
- `order` (string, optional) — An integer that specifies the order in which rules are processed. Lower values are processed before higher values.
- `recipientLabel` (string, optional) — An identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).

### recipientGroup

Describes a group of recipients.

- `groupMessage` (string, optional) — The group message, typically a description of the group.
- `groupName` (string, optional) — The name of the group.
- `recipients` (list of recipientOption, optional) — An array of recipient objects that provides details about the recipients of the envelope.

### conditionalRecipientRuleFilter

- `operator` (string, optional) — How the tab value is compared to the `value` property. Valid values: - `equals` - `greaterThan` - `greaterThanEquals` - `lessThan` - `lessThanEquals` - `filled` - `selected`
- `recipientId` (string, optional) — A local reference used to map recipients to other objects, such as specific document tabs. A `recipientId` must be either an integer or a GUID, and the `recipientId` must be unique within an envelope. For example, many envelopes assign the first recipient a `recipientId` of `1`.
- `scope` (string, optional) — The scope under which the condition is evaluated. Valid values: - `tabs`
- `tabId` (string, optional) — The unique identifier for the tab.
- `tabLabel` (string, optional) — The label associated with the tab. This value may be an empty string. If no value is provided, the tab type is used as the value. Maximum Length: 500 characters.
- `tabType` (string, optional) — Indicates the type of tab (for example, `signHere` or `initialHere`).
- `value` (string, optional) — A set value to which the tab's actual value is compared.

### recipientOption

Describes a recipient who is a member of a conditional group.

- `email` (string, optional) — The email ID of the agent. This property is required. Maximum length: 100 characters.
- `name` (string, optional) — The full legal name of the recipient. Maximum length: 100 characters.
- `recipientLabel` (string, optional) — An identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).
- `roleName` (string, optional) — Specifies the signing group role of the recipient. This property is required.
- `signingGroupId` (string, optional) — The ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).

## Examples

**Request**

```json
{
  "action": "sample string 1",
  "completedDate": "sample string 2",
  "delayedRouting": {
    "resumeDate": "sample string 1",
    "rules": [
      {
        "delay": "sample string 1",
        "resumeDate": "sample string 2"
      }
    ],
    "status": "sample string 2"
  },
  "itemId": "sample string 3",
  "recipientRouting": {
    "rules": {
      "conditionalRecipients": [
        {
          "conditions": [
            {}
          ],
          "order": "sample string 1",
          "recipientId": "sample string 2"
        }
      ]
    }
  },
  "status": "sample string 4",
  "triggeredDate": "sample string 5",
  "triggerOnItem": "sample string 6",
  "workflowStepId": "sample string 7"
}
```

**Response**

```json
{
  "action": "sample string 1",
  "completedDate": "sample string 2",
  "delayedRouting": {
    "resumeDate": "sample string 1",
    "rules": [
      {
        "delay": "sample string 1",
        "resumeDate": "sample string 2"
      }
    ],
    "status": "sample string 2"
  },
  "itemId": "sample string 3",
  "recipientRouting": {
    "rules": {
      "conditionalRecipients": [
        {
          "conditions": [
            {}
          ],
          "order": "sample string 1",
          "recipientId": "sample string 2"
        }
      ]
    }
  },
  "status": "sample string 4",
  "triggeredDate": "sample string 5",
  "triggerOnItem": "sample string 6",
  "workflowStepId": "sample string 7"
}
```