--- title: "Returns a URL to the sender view UI. Used before an envelope has been sent." method: POST path: "/v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/sender" tags: ["EnvelopeViews"] --- # Returns a URL to the sender view UI. Used before an envelope has been sent. `POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/sender` 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](/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. ## Path parameters - `accountId` string, required - `envelopeId` string, required ## Request body - EnvelopeViewRequest - `returnUrl` string — **Required** Identifies the return point after sending the envelope. Docusign returns to the URL and includes an event parameter that can be used to redirect the recipient to another location. The possible event parameters returned are: * send (user sends the envelope) * save (user saves the envelope) * cancel (user cancels the sending transaction. No envelopeId is returned in this case.) * error (there is an error when performing the send) * sessionEnd (the sending session ends before the user completes another action). - `settings` EnvelopeViewSettings - `backButtonAction` string — Sets the behavior of the back button when clicked. Valid values: * `previousPage`: Navigate to browser's previous page * `redirect`: Redirect to the `returnUrl` specified in the request - `documentSettings` EnvelopeViewDocumentSettings - `showEditDocuments` string — When **false,** prevents the app user from adding, replacing, or deleting documents. The default value is **true.** - `showEditDocumentVisibility` string — When `false`, prevents the user from modifying document visibility settings. The default value is `true`. - `showEditPages` string — When `false`, prevents the user from deleting or rotating individual document pages via the thumbnail images. The default value is `true`. If `true` and `showEditDocuments` is `false`, the pages can be rotated but not deleted. - `showSaveAsDocumentCustomField` string — Reserved for Docusign. - `envelopeCustomFieldSettings` EnvelopeViewEnvelopeCustomFieldSettings - `showEnvelopeCustomFields` string — Reserved for Docusign. - `lockToken` string — If your app will modify the envelope after the user finishes editing the envelope, create and use a [lock token](/docs/esign-rest-api/reference/envelopes/envelopelocks/create/) for this attribute. Remember to delete the lock token after your app has finished its envelope modifications. - `recipientSettings` EnvelopeViewRecipientSettings - `showBulkSend` string — Reserved for Docusign. - `showContactsList` string — Reserved for Docusign. - `showEditMessage` string — Reserved for Docusign. - `showEditRecipients` string — When `false`, prevents the user from changing the recipients from the **Tagger** page. The default value is `true`. - `sendButtonAction` string — Sets the behavior of the send button when clicked. Valid values: * `send`: send the envelope and redirect with query parameter `event=Send` (default) * `redirect`: Change the Tagger page's button text to 'Continue'; when clicked, redirect to the `returnUrl` with query parameter `event=Save`. Set `showBackButton` to `false` and `startingScreen` to `Tagger`. - `showAdvancedOptions` string — Reserved for Docusign. - `showBackButton` string — Determines whether the Tagger's back button is shown. Valid values: * `true`: The back button is shown. This is the default value. * `false`: Prevents access to the Prepare screen by hiding the back button. - `showDiscardAction` string — When **true,** the Discard option is shown in the Actions menu. When **false,** the Discard option is not shown. The default value is **true.** - `showHeaderActions` string — Determines whether the Actions menu displays advanced actions. Valid values: * `true`: The Actions menu shows all options, including editing the message, recipients, documents, and advanced options. This is the default value. * `false`: The Actions menu will only show Save, Close, and Discard. To limit the user to tagging only, use this value and set `startingScreen` to `Tagger` and `showBackButton` to `false`. - `showSignNow` string - `startingScreen` string — Determines the starting screen for the sender view. Valid values: * `Prepare` (default) * `Tagger` - `taggerSettings` EnvelopeViewTaggerSettings - `paletteDefault` string — When `paletteSections` is set to `custom`, this property selects the default tagger palette. Valid values: * `custom` * `merge` * `notary` * `seals` * `smartContracts` * `annotations` * `smartSections` - `paletteSections` string — Valid values: * `default` (default): The default tagger palette UX * `none`: No tagger palette * `custom`: Set by `paletteDefault` - `paletteSettings` PaletteSettings — Reserved for Docusign. - `annotations` PaletteItemSettings - `show` string — Reserved for Docusign. - `custom` PaletteItemSettings - `show` string — Reserved for Docusign. - `merge` PaletteItemSettings - `show` string — Reserved for Docusign. - `notary` PaletteItemSettings - `show` string — Reserved for Docusign. - `seals` PaletteItemSettings - `show` string — Reserved for Docusign. - `smartContracts` PaletteItemSettings - `show` string — Reserved for Docusign. - `smartSections` PaletteItemSettings - `show` string — Reserved for Docusign. - `templateSettings` EnvelopeViewTemplateSettings - `showMatchingTemplatesPrompt` string — Reserved for Docusign. - `viewAccess` string — **Required** . Set to `envelope` ## Response `201` Successful response. ## Other responses - `400` — Error encountered. --- [API](https://skmtc.net/docusign/apis/docusign-esignature-rest-api.md) · [All operations](https://skmtc.net/docusign/apis/docusign-esignature-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docusign/docusign-esignature-rest-api/revisions/77f1998c313d/schema)