Returns a URL to the shared recipient view UI for an envelope

Returns a URL that enables you to embed the envelope sender view of the Docusign UI. You can customize the appearance of the view via the settings request attribute. You can embed the view in an iframe. **API request update** The request object for this API method was updated in June 2024. The new API request format is described below. Existing applications must update to the new version; it solves a security issue with the old version. The deprecation schedule has been announced in the [Docusign Core Release Notes](https://support.docusign.com/s/document-item?language=en_US&bundleId=adp1720620778794_24-2-02-00-demo&topicId=wcz1616195757589.html&_LANG=enus). While backwards compatibility will be provided for a while for existing applications, all applications must be updated to be secure. See below for migration information. **Best practices** The returned URL expires after 10 minutes. Therefore, request the URL immediately before you redirect your user to it. Due to screen space issues, do not use an iframe for embedded operations on mobile devices. For mobile applications, use a [WebView](https://developer.android.com/reference/android/webkit/WebView) (Android) or [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview) (iOS). ## Customizing the user experience By default, the view includes two pages: the **Prepare** and **Tagger** pages. The settings object is used to control the user experience. For example, to limit the user to the **Tagger** page, and not allow the user to change the recipient information: * `"startingScreen": "Tagger"` * `"showBackButton": "false"` * `"showEditRecipients": "false"` Use the [Embedded Views Test Too](https://docusign.github.io/app-examples/embedded-views-v2/) to try the different UX controls. Some UI settings attributes are not yet implemented. ### The envelope must be in the correct state for the Embedded View To use the Sender View, the envelope **must** be in the `created` state. Otherwise, a 400 error will be returned with an error message in the response body: ``` { "errorCode": "ENVELOPE_INVALID_STATUS", "message": "Invalid envelope status. Sender view cannot be created for an envelope that is not in a draft state." } ``` ### Closing the view's iframe If you choose to embed the view in your application via an iframe, Docusign recommends this software pattern to close the iframe after the view has completed: * (One time) create a standalone “return” page that you will use as the `returnUrl` target for the view. The view will redirect the iframe to this URL when it has completed. Here's an [example return page](https://github.com/docusign/docusign.github.io/blob/master/jsfiddleDsResponse.html). In this page, use JavaScript and the [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) method to send a message to your application with the results of the view. * In your application, use `window.addEventListener("message", function_name)` to register a listener for incoming messages. * To show the view, use this API method, then set the iframe to load the URL from the API response. * In your application, receive the completion message, validate it, and then close the iframe. ### Information security This view only has write access to the specific envelope referenced in the API call. It also has read access to templates and other secondary information that a user can access to modify the envelope. The read access corresponds to the access rights of the user associated with the access token used for the API call. >**Recommendations:** >* Use the access token of a service user who can access the templates appropriate for your use case. >* Do not use the access token of a user with administrator privileges. ## Migrating to the current version of the request object This section only applies to existing applications that use the older version of the request object. Migrating from the old API request object to the new version will take under a day of developer time. **Step 1.** Does your application set the `returnUrl` attribute? Yes: continue with step 2. No: In this case, your users first update the envelope, and then the Docusign eSignature home screen is shown. To accomplish this UI pattern with the new API request format: * Set the `returnUrl` to a new endpoint for your application. You can use query parameters or session data to manage state. Remember to authenticate the incoming requests. * When the new endpoint is called, use the [EnvelopeViews:createConsole](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopeviews/createconsole/) API call to obtain and then display the Docusign eSignature home page to your application's user. **Step 2.** Does your application modify the default UI of the view? No: continue with step 3. Yes: With the new API request object, UI controls for the view are now set when you make the API call via the `settings` attribute. * Note the UI settings your application is currently modifying by adding and updating query parameters on the URL _returned_ by the API method. * Using the reference documentation below, create a settings object that accomplishes your UI goals. You can use the [Embedded Views Test tool](https://docusign.github.io/app-examples/embedded-views-v2/) to check your UI settings. Note that the `settings` object includes multiple objects and subobjects for various UI settings. * **Delete the code** in your application that modifies and adds query parameters to the URL returned by the API. With the new API format, your application will not make any changes to the returned URL. Exception: If you set the view's locale specifically, that is still accomplished by appending the `locale` query parameter. **Step 3.** Is the envelope always in the right state before you call the Embedded View? If your software may try to create the Embedded View when the envelope is not in the right state (see above), then you must add additional checks and logic to prevent this. **Step 4.** Check that these API attributes are set: * `"view" = "envelope"` * The `returnUrl` is set **Step 5.** All done! Test your application.