> 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

# Trigger instance of workflow builder workflow

POST https://api-d.docusign.com/v1/accounts/{accountId}/workflows/{workflowId}/actions/trigger
Content-Type: application/json

This operation triggers a new instance of a specified Workflow Builder workflow. When invoked,
the workflow is started based on the provided input data, and the workflow instance
begins executing according to its defined logic and configuration.

The request requires an `instance_name` and any input data necessary to start the workflow,
as described by the workflow's `trigger_input_schema`. The `instance_name` is a user-defined
label for tracking the workflow run, while the input data fields should match the schema defined
in the workflow.

The operation is event-driven and typically triggered by an external HTTP event or system call,
allowing for the automatic execution of complex processes that span multiple systems or components.

Upon successful execution, the response returns the unique identifier (`id`) for the newly
created workflow instance, along with a URL (`workflow_instance_url`) that can be used to
interact with or track the running instance.

### Use Cases:
- Automating user registration workflows where input fields like `name` and `email` are provided.
- Processing financial transactions where details such as `amount` and `currency` are required.
- Sending notifications based on user interactions in other systems.

### Key Features:
- **Automated Execution**: Once triggered, the workflow runs until a step requires manual intervention.
- **Input-Driven**: Workflow execution is based on the provided input data, which is validated
  against the workflow's input schema.
- **Real-Time Triggering**: Designed to be invoked as part of an event-driven architecture,
  allowing for workflows to respond to external events.
- **Tracking and Interaction**: The response includes a URL that allows users to check the status
  of the workflow instance or take further actions while it runs.


Reference: https://developers.docusign.com/docs/workflow-builder-api/reference/workflowbuilder/workflows/triggerworkflow

## Authentication

- `Authorization` header (bearer token, required) — OAuth2 authentication. - Demo: - authorizationUrl: https://account-d.docusign.com/oauth/auth - tokenUrl: https://account-d.docusign.com/oauth/token - Production: - authorizationUrl: https://account.docusign.com/oauth/auth - tokenUrl: https://account.docusign.com/oauth/token

## Servers

- `https://api-d.docusign.com` (Demo, default)
- `https://api.docusign.com` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The unique identifier of the account.
- `workflowId` (string, required) — A universally unique identifier (UUID) in standard 8-4-4-4-12 format.

### Body (application/json)

This endpoint expects a TriggerWorkflow.

- `instance_name` (string, required) — A descriptive name for the specific instance of the workflow being triggered. This is typically used for identification and tracking purposes. Example: "User Registration Workflow Instance"
- `trigger_inputs` (TriggerInputs, required) — A key-value pair where the key is the `field_name` defined in the `trigger_input_schema` of the workflow definition, and the value is the actual input data. Supported types include string, number, boolean, object, or array.

## Response

### 201

Indicates a trigger has successfully launched a workflow instance

- `instance_id` (string, optional) — A unique identifier for this specific instance of the workflow. This UUID is used to reference the running instance in other API calls (e.g., to retrieve its status or terminate the instance). Example: '1a46ccde-9db4-42d6-94fa-0ddd07a3d2ff'
- `instance_url` (string, optional) — A fully-qualified URL that can be used to access or interact with this workflow instance while it is running. This URL may provide access to additional details, actions, or logs related to the workflow execution.
- `response_timestamp` (datetime, optional) — The timestamp indicating when the response was generated.
- `response_duration_ms` (integer, optional) — The duration of time, in milliseconds, that the server took to process and respond to the request. This is measured from the time the server received the request until the time the response was sent.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracking and debugging.

## Errors

### 400 Bad Request Error

Bad Request - The request could not be understood or was missing required parameters.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 401 Unauthorized Error

Unauthorized - Authentication is required and has failed or not been provided.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 403 Forbidden Error

Forbidden - The request was valid, but you do not have permission to perform the action.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 404 Not Found Error

Not Found - The requested resource could not be found.

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference that identifies the problem type. Use 'about:blank' when the problem has no additional semantics beyond the HTTP status code.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem (typically the request path).
- `timestamp` (datetime, optional) — The timestamp when the error occurred.
- `request_id` (string, optional) — Correlation identifier for the request, useful for support investigations.
- `errors` (list of ValidationError, optional) — Optional list of individual validation or domain errors.

## Types

### TriggerInputs

A key-value pair where the key is the `field_name` defined in the `trigger_input_schema` of the workflow definition, and the value is the actual input data. Supported types include string, number, boolean, object, or array.

- string
- double
- boolean
- map from string to any
- list of any

### ValidationError

A single field-level or domain validation error.

- `code` (string, required) — Machine-readable error code.
- `message` (string, required) — Human-readable description of the error.
- `target` (string, optional) — The field or parameter this error relates to.

## Examples

**Request**

```json
{
  "instance_name": "Sample Workflow Run",
  "trigger_inputs": {}
}
```

**Response**

```json
{
  "instance_id": "9bd95fba-60f7-4f74-a11b-af00c0617ad9",
  "instance_url": "https://apps-d.docusign.com/api/maestro/v1/accounts/97878f25-e391-4be4-a8f0-cf5f415f134e/instances/3695f629-e367-4243-abeb-5cb526b9559f/execution?mtid=34b2fb6c-cfd8-4084-9de6-94c111b17a9e&mtsec=U5OWGv7RQwmHgMX2UzhOWbTSdVoWYP8N-7qkE_ishaI"
}
```