Skip to navigation
Workflow Builder API 101

Embed a workflow in your web application

View as Markdown

When your Workflow Builder API integration starts a workflow instance by making a Workflows: triggerWorkflow request, the response includes an instance_url. This is the URL of the web page where a user completes the workflow steps. Your integration has two options for displaying the instance_url:

  • Redirect the user’s browser to the workflow instance URL: The user is routed from your web application to the Docusign platform. When the user completes the workflow, they remain at the Docusign platform instead of returning to your web application.

    For sample code that demonstrates this option, see How to trigger a Workflow Builder workflow and the Workflows Sample App.

  • Embed the workflow instance URL in an iframe: The workflow is displayed within your web application, and your web application’s user interface is visible as users complete the workflow. This contributes to a more seamless user experience. When a user finishes the workflow, their browser window still displays your web application, which can route the user to other pages in your application as needed.

Embedded workflow instance recommendations and restrictions

Workflow start methods

For Workflow Builder API integrations that embed workflow instances, the supported workflow start methods are From a Link and From an API call.

Workflow starting variable values

If your integration’s Workflows: triggerWorkflow request will include starting variable values passed in the trigger_inputs object, Docusign recommends that the workflow start method be set to From an API call instead of From a Link. For sample code that includes starting variable values, see How to trigger a Workflow Builder workflow.

Workflow step types

These restrictions related to workflow step types apply to embedded workflow instances:

  • All workflow step types are supported with integrations that embed workflow instances, except for Collect Data from an ID.
  • For Verify Someone’s Identity steps, only the Phone Authentication verification method is supported with embedded workflow instances.
  • If a workflow does not include any steps that users complete in a UI, Docusign does not recommend embedding workflow instances in your web application. An example of a workflow with no UI steps is one that only sends an email to users.
  • For workflows that include a Send Documents for Signature step, focused view display of the agreement to be signed is not supported.

Embed a workflow instance URL

To embed the instance_url returned in a Workflows: triggerWorkflow response, include the URL in an iframe, for example:

<div className={styles.formContainer}>
  <iframe src={triggerUrl} width="800" height="600">
  </iframe>
</div>

Next steps