Skip to main content
Blog
Home/

New Maestro API endpoints: More control, more automation, less effort

Author Venkat Kotu
Venkat KotuSenior Software Engineer
Summary8 min read

New Maestro API endpoints open up powerful lifecycle control, enabling teams to make their workflows smarter, safer, and more adaptive.

    • Steps to trigger a workflow instance
          • Retrieve workflow instance information
                • Manage workflows
                      • Try it yourself
                      • Final thoughts
                      • Additional resources

                      Table of contents

                      Automated workflows are powerful, but they’re even more valuable when you can manage them with precision. That’s why we’re excited to introduce a new set of Maestro API endpoints that give developers complete control over a workflow’s lifecycle: from triggering a new instance to pausing or resuming execution and even canceling a running instance. Whether you’re automating onboarding, finance approvals, or custom agreements, these new endpoints help you handle real-world scenarios like version changes, data issues, or human reviews.

                      Note: The example cURL requests in this post use the production base URI. For testing on the developer (demo) environment, use the developer environment base URI. See API endpoints for details.

                      Steps to trigger a workflow instance

                      A workflow is a reusable template that defines a sequence of agreement process steps, such as filling out a web form or signing an agreement. A workflow instance is a runtime execution of the steps in a workflow for a specific customer. The following sections explain how to programmatically start a workflow instance from a workflow.

                      📋 Step 1. List available workflows

                      Before triggering a workflow instance, you’ll need to retrieve a list of available workflows in your account.

                      Endpoint

                      GET /v1/accounts/{accountId}/workflows

                      {accountId} is your Docusign account ID.

                      Example request (Bash using cURL)

                      curl --request GET \
                        'https://api.docusign.com/v1/accounts/{accountId}/workflows' \
                        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

                      Example response

                      {
                        "data": [
                          {
                            "id": "276f70ca-xxxx-xxxx-xxxx-dca4a3c08304",
                            "name": "jane_Test_Workflow",
                            "account_id": "6f8f04d8-xxxx-xxxx-xxxx-66153699f837",
                            "status": "active",
                            "metadata": {
                              "created_at": "2025-04-11T17:30:46.477+00:00",
                              "created_by": "65499beb-xxxx-xxxx-xxxx-e050694402c3",
                              "modified_at": "2025-04-11T17:41:21.857+00:00"
                            }
                          }
                        ]
                      }

                      Why this matters

                      The id value you get from this response is crucial; it’s the unique identifier for a workflow and is used in every subsequent step, from retrieving trigger requirements to starting a workflow instance and managing the workflow (pause, resume, etc.).

                      🔍 Step 2. Get trigger requirements

                      Before triggering a workflow instance, you need to know what input parameters it expects (for example, email address, department, file name). That’s where this endpoint helps.

                      Endpoint

                      GET /v1/accounts/{accountId}/workflows/{workflowId}/trigger-requirements

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}:The unique ID of the workflow. You can obtain this from the GET /v1/accounts/{accountId}/workflows response.

                      Example request (Bash using cURL)

                        'https://api.docusign.com/v1/accounts/{accountId}/workflows/{workflowId}/trigger-requirements' \
                        --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

                      Example response

                      {
                        "trigger_id": "c30c7afc-xxxx-xxxx-xxxx-d90f651b584b",
                        "trigger_event_type": "HTTP",
                        "trigger_http_config": {
                          "method": "POST",
                          "url": "https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/actions/trigger"
                        },
                        "trigger_input_schema": [
                          {
                            "field_name": "Email",
                            "field_data_type": "String"
                          },
                          {
                            "field_name": "Name",
                            "field_data_type": "String"
                          }
                        ],
                        "metadata": {
                          "created_at": "2025-04-11T17:30:46.477+00:00",
                          "created_by": "65499beb-xxxx-xxxx-xxxx-e050694402c3",
                          "modified_at": "2025-04-11T17:41:21.857+00:00",
                          "response_timestamp": "2025-07-31T22:09:17.184559Z",
                          "response_duration_ms": 760
                        }
                      }

                      Why this matters

                      This response provides two key things:

                      1. Where to send the trigger request: The trigger_http_config.url tells you the exact endpoint to use when you POST data to trigger the workflow instance.

                      2. What fields to include: The trigger_input_schema in the example response tells you that you must include:

                        • Email as a String

                        • Name as a String

                      This schema ensures your request payload is correctly structured; otherwise, the trigger will fail. Think of this as the contract between your app and the workflow engine.

                      Next, you’ll use this information to actually fire the workflow instance in Step 3.

                      🚀 Step 3. Trigger the workflow

                      Once you’ve checked the trigger requirements, you’re ready to start (or trigger) the workflow by providing the required inputs.

                      This endpoint starts a new execution of a published workflow. It’s commonly used when you want to programmatically initiate a workflow instance with specific input values. For example, a workflow that sends documents for signing would require the recipient name and email as input values. The response includes a unique instance ID and a secure instance_url, which users can open in a browser to complete any manual workflow steps.

                      Endpoint

                      POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/trigger

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}:The unique ID of the workflow. You can obtain this from the GET /v1/accounts/{accountId}/workflows response.

                      Example request (Bash using cURL)

                      curl --location 'https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/actions/trigger' \
                      --header 'Content-Type: application/json' \
                      --header 'Authorization: Bearer ACCESS TOKEN' \
                      --data-raw '{
                          "instance_name": "Venkat Test Trigger From Post man 3",
                          "trigger_inputs": {
                              "startDate": "2025-08-01",
                              "Email": "venkat.kotu@docusign.com",
                              "Name": "Venkat"
                          }
                      }'

                      Example response

                      {
                        "instance_id": "99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77",
                        "instance_url": "https://apps.docusign.com/api/maestro/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-
                          66153699f837/instances/99895a0-xxxx-xxxx-xxxx-5b7acf4f0d77/execution?mtid=ef2bd809-xxxx-xxxx-xxxx-
                          19579926b676&mtsec=qhvMO4reeL9hCZpJRC6idHq-NAx4ZrQvFZIkvTSUJoM"
                      }

                      Why this matters

                      This response gives you two important pieces of information:

                      • instance_id: This is the unique ID of the workflow instance you just created. You’ll need this in later steps—for example, to cancel or check the status of the instance.

                      • instance_url: This is a direct link to the Docusign Maestro UI, where users can view the instance’s progress and complete any manual steps, such as approvals and data inputs, that the workflow may require. You can open this in the browser or embed it in your internal tools for easy access.

                      This makes it easy to bridge programmatic control with human interaction, helping your workflows move forward with full visibility and flexibility.

                      Retrieve workflow instance information

                      📋 List all workflow instances

                      Need to check the status of workflow instances? Use this endpoint to retrieve a list of all workflow instances created from a specific workflow.

                      Endpoint

                      GET /v1/accounts/{accountId}/workflows/{workflowId}/instances

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}: The unique ID of the workflow. You can obtain this from the GET /v1/accounts/{accountId}/workflows response.

                      Example request (Bash using cURL)

                      curl --location 'https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/instances' \
                      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
                      --header 'Content-Type: application/json'

                      Example response

                      {
                        "data": [
                          {
                            "id": "99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77",
                            "name": "jane Test Trigger From Postman 3",
                            "workflow_status": "In Progress",
                            "template_id": "276f70ca-xxxx-xxxx-xxxx-dca4a3c08304",
                            "account_id": "6f8f04d8-xxxx-xxxx-xxxx-66153699f837",
                            "started_at": "2025-07-31T22:15:07.941+00:00",
                            "started_by": "65499beb-xxxx-xxxx-xxxx-e050694402c3",
                            "started_by_name": "jane doe",
                            "started_by_role": "Preparer",
                            "expires_at": "2025-10-29T22:15:10.449+00:00",
                            "last_modified_at": "2025-07-31T22:15:10.803+00:00",
                            "trigger_inputs": {
                              "Email": "jane.doe@example.com",
                              "Name": "jane",
                              "startDate": "2025-07-31T22:15:06.759Z",
                              "dacId": "99895a08--xxxx-xxxx-xxxx-5b7acf4f0d77",
                              "id": "9e8adaac-xxxx-xxxx-xxxx-2dc1de83cf70",
                              "participantIdMap": {
                                "4124c851-xxxx-xxxx-xxxx-40d46d2d35d0": "9e8adaac-xxxx-xxxx-xxxx-2dc1de83cf70",
                                "68bea0a9--xxxx-xxxx-xxxx-58dbaa1f99e3": "c22480b1-xxxx-xxxx-xxxx-51151b925ca8"
                              }
                            },
                            "total_steps": 1,
                            "last_completed_step": 0
                          }
                        ],
                        "response_metadata": {
                          "response_timestamp": "2025-07-31T22:36:03.7781299Z",
                          "response_duration_ms": 802
                        }
                      }

                      🔍 Get a specific workflow instance

                      Use this endpoint to retrieve detailed information about a specific instance of a workflow. This can be useful for checking the current status of a workflow run, verifying who initiated it, reviewing trigger inputs, or tracking progress through the steps.

                      Endpoint

                      GET /v1/accounts/{accountId}/workflows/{workflowId}/instances/{instanceId}

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}: The unique ID of the workflow. You can obtain this from the GET /v1/accounts/{accountId}/workflows response.

                      • {instanceId}: The unique ID of the specific workflow instance you want to retrieve. You can obtain this from the response to either of these requests:

                        • POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/trigger

                        • GET /v1/accounts/{accountId}/workflows/{workflowId}/instances

                      Example request (Bash using cURL)

                      curl --location 'https://api.docusign.com/v1/accounts/6f8f04d8--xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca--xxxx-xxxx-xxxx-dca4a3c08304/instances/99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77' \
                      --header 'Content-Type: application/json' \
                      --header 'Authorization: Bearer ACCESS TOKEN' \
                      --data ''

                      Example response

                      {
                        "id": "99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77",
                        "name": "Venkat Test Trigger From Postman 3",
                        "workflow_status": "In Progress",
                        "template_id": "276f70ca-xxxx-xxxx-xxxx-dca4a3c08304",
                        "account_id": "6f8f04d8-xxxx-xxxx-xxxx-66153699f837",
                        "started_at": "2025-07-31T22:15:07.941+00:00",
                        "started_by": "65499beb-xxxx-xxxx-xxxx-e050694402c3",
                        "started_by_name": "Venkat Kotu",
                        "started_by_role": "Preparer",
                        "expires_at": "2025-10-29T22:15:10.449+00:00",
                        "last_modified_at": "2025-07-31T22:15:10.803+00:00",
                        "trigger_inputs": {
                          "Email": "jane.doe@example.com",
                          "Name": "Venkat",
                          "dacId": "99895a08--xxxx-xxxx-xxxx-5b7acf4f0d77",
                          "id": "9e8adaac-xxxx-xxxx-xxxx-2dc1de83cf70",
                          "participantIdMap": {
                            "4124c851-xxxx-xxxx-xxxx-40d46d2d35d0": "9e8adaac-xxxx-xxxx-xxxx-2dc1de83cf70",
                            "68bea0a9-xxxx-xxxx-xxxx-58dbaa1f99e3": "c22480b1-xxxx-xxxx-xxxx-51151b925ca8
                          },
                          "startDate": "2025-07-31T22:15:06.759Z"
                        },
                        "total_steps": 1,
                        "last_completed_step": 0,
                        "tags": [],
                        "metadata": {
                          "workflow_created_by": "65499beb-xxxx-xxxx-xxxx-e050694402c3",
                          "workflow_version": "1.0.0",
                          "workflow_metadata_id": "67f9543fcd2943f4119cf978"
                        }
                      }

                      What this tells you

                      The data in the response represents one instance of the workflow. Here’s what to focus on:

                      • id: This is the instance ID. Use it to cancel the instance programmatically.

                      • workflow_status: Shows whether the instance is running, completed, or failed.

                      • trigger_inputs: Displays the input values (like email, name, start date) that were passed in when the workflow was triggered.

                      • started_by_name: Helps trace who kicked off the workflow.

                      • expires_at: Useful if you have SLAs or time-sensitive steps.

                      Manage workflows

                      ⏸️ Pause the creation of new workflow instances

                      This endpoint pauses the specified workflow, preventing users from starting any new instances of it.

                      Endpoint

                      POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/pause

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}: The unique ID of the workflow you want to pause. You can retrieve this using the GET /v1/accounts/{accountId}/workflows endpoint.

                      Example request (Bash using cURL)

                      curl --location --request POST 'https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/actions/pause' \
                      --header 'Content-Type: application/json' \
                      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

                      Example response

                      {
                        "workflowDefinitionId": "276f70ca-xxxx-xxxx-xxxx-dca4a3c08304",
                        "status": "paused"
                      }

                      ▶️ Resume workflow

                      This endpoint resumes a paused workflow, enabling users to create new instances of it. Use this after you have paused a workflow using the POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/pause endpoint. Endpoint

                      POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/resume

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}: The unique ID of the workflow you want to pause. You can retrieve this using the GET /v1/accounts/{accountId}/workflows endpoint.

                      Example request

                      curl --location --request POST 'https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/actions/resume' \
                      --header 'Content-Type: application/json' \
                      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

                      Example response

                      {
                        "workflowDefinitionId": "276f70ca-xxxx-xxxx-xxxx-dca4a3c08304",
                        "status": "active"
                      }

                      🛑 Cancel a workflow instance

                      This endpoint cancels a specific in-progress workflow instance. Once a workflow instance has been canceled, the participant cannot take any further action in the workflow instance or complete it. Endpoint

                      POST /v1/accounts/{accountId}/workflows/{workflowId}/instances/{instanceId}/actions/cancel

                      • {accountId}: Your Docusign account ID.

                      • {workflowId}: The unique ID of the workflow associated with the instance. Obtainable from the GET /v1/accounts/{accountId}/workflows endpoint or from the original workflow trigger response.

                      • {instanceId}: The unique ID of the workflow instance you want to cancel. You can retrieve this from the response to either of the following requests:

                        • POST /v1/accounts/{accountId}/workflows/{workflowId}/actions/trigger

                        • GET /v1/accounts/{accountId}/workflows/{workflowId}/instances

                      Example request

                      curl --location --request POST 'https://api.docusign.com/v1/accounts/6f8f04d8-xxxx-xxxx-xxxx-66153699f837/workflows/276f70ca-xxxx-xxxx-xxxx-dca4a3c08304/instances/99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77/actions/cancel' \
                      --header 'Content-Type: application/json' \
                      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

                      Example response

                      {
                        "instanceId": "99895a08-xxxx-xxxx-xxxx-5b7acf4f0d77",
                        "status": "canceled"
                      }

                      Try it yourself

                      Ready to put it all into action? Start by generating an access token using your preferred authentication method. Then, try out these endpoints using tools like Postman or your own platform. You can even jumpstart testing with the official Maestro API Postman collection. With just a few API calls, you’ll see your workflows come to life, or pause, exactly when you need them to.

                      See our full Maestro API reference documentation, including example requests and responses. 

                      If you’re already using Maestro in the UI, these endpoints will feel familiar. If you’re new to Maestro, this is a great time to get started. You can define your workflows once, and then automate the rest.

                      Final thoughts

                      These new Maestro API endpoints open up powerful lifecycle control for teams building real-world automation. Whether you need to pause and resume the creation of workflow instances to accommodate business needs or cancel a running workflow instance to address a customer service issue, you now have the tools to make your workflows smarter, safer, and more adaptive. Got ideas or feedback? Share it with the Docusign Developer Community.

                      Additional resources

                      Author Venkat Kotu
                      Venkat KotuSenior Software Engineer

                      Venkat Kotu is a Senior Software Engineer at Docusign, where he has been leading initiatives on the Intelligent Agreement Management (IAM) platform since 2023. With over 13 years of experience in software engineering, he focuses on building scalable APIs, cloud-native services, and developer tools that power agreement workflows and help organizations create, automate, and manage large-scale agreements more efficiently. He's passionate about developing scalable APIs, cloud services, and tools that simplify agreement workflows for developers and enterprises alike.

                      More posts from this author

                      Related posts

                      • Developers

                        Scaling with Docusign: The ISV՚s guide to account cloning

                        Author Abhay Kumar Nelaturu
                        Abhay Kumar Nelaturu
                        Scaling with Docusign: The ISV՚s guide to account cloning

                      Discover what's new with Docusign IAM or start with eSignature for free

                      Explore Docusign IAMTry eSignature for Free
                      Person smiling while presenting