DocuSign.Api.EnvelopeViews (DocuSign v2.0.0)

View Source

API calls for all endpoints tagged EnvelopeViews.

Summary

Functions

Revokes the correction view URL to the Envelope UI. This API method is obsolete. Your application should not call it. It acts as a null operation.

Returns a URL to the Docusign eSignature web application. Returns a URL that enables you to embed the Docusign UI in your applications. To view a specific envelope, set the envelopeId property in the request body. ## Information security notice This method provides full access to the sending account. ### Related topics - How to embed the Docusign UI in your app

Returns a URL to the envelope correction UI. Use after an envelope has been sent. 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. 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 (Android) or 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 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 Correct View, the envelope must be in the sent or delivered state. Otherwise, a 400 error will be returned with an error message in the response body: { "errorCode": "ENVELOPE_INVALID_STATUS", "message": "Invalid envelope status. Correct view cannot be created for an envelope in a Created state." } ### Modifying the envelope after redirection If you set "sendButtonAction": "redirect" or "backButtonAction": "redirect", and your app will modify the envelope before or after the view completes, you must lock the envelope before the API call and provide the lock as the lockToken attribute in the API request object. Delete the lock token after the browser has been redirected to your application. ### 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. In this page, use JavaScript and the 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 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 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.

Returns a URL to the edit view UI. Use before an envelope has been sent. This API method has been replaced by the EnvelopeViews:createSender API method. The two API methods work exactly the same, Migration required To solve an application security issue, you must migrate to the new API request format. See the EnvelopeViews:createSender API method for more information. Backwards compatibility will be provided for a limited time.

Returns a URL to the shared recipient view UI for an envelope. Returns a URL that enables you to embed the Docusign UI recipient view of a shared envelope in your applications. This is the view that a user sees of an envelope that a recipient on the same account has shared with them. Due to screen space issues, do not use an <iframe> for embedded operations on mobile devices. For iOS devices, Docusign recommends using a WebView. ### Related topics - Embedded signing and sending - How to send an envelope via your app - How to embed the Docusign UI in your app

Returns a URL to the recipient view UI. For signer recipients, returns the embedded signing view. Can also be used for other recipient types. Returns a URL that enables you to embed the recipient view of the DocuSign UI in your applications. If the recipient is a signer, then the view will provide the signing ceremony. This method is only used with envelopes in the sent status. <ds-inlinemessage kind="information" markdown="1"> Due to screen space issues, do not use an <code>&lt;iframe&gt;</code> for embedded operations on mobile devices. For iOS devices, Docusign recommends using a WebView. </ds-inlinemessage> ### The returned URL The URL returned in this method's response is intended to be used immediately to redirect the signer to the recipient view. You can open the recipient view in the current browser or in a new tab. After the signer is redirected to the recipient view, they must interact with the Docusign system periodically or their session will time out. <ds-inlinemessage kind="warning" markdown="1"> The returned URL can be used only once and expires after 5 minutes. Do not store or email the returned URL. </ds-inlinemessage> If you want to invite someone to an embedded signing session via email, the email invitation's URL must be to your application. When invoked, your app should request a recipientView URL from Docusign and then redirect the signer to that URL. ### How to specify the default language You can append the locale query parameter to the URL returned by this method to specify a language. The language for the recipient view follows this order or precedence: - The language specified by the sender for the recipient. - The locale parameter appended to the URL. - The account language if the signer has a Docusign account. - The language used in a previous signing if the signer is return signer. - The browser language. For example, to set the default language to Canadian French, you would add this query parameter to the returned URL: ...&locale=fr_CA ## Authentication Your application is responsible for authenticating the identity of the recipient or signer when you use this method. Use the following parameters to record how the recipient was authenticated. - assertionId - authenticationInstant - authenticationMethod - clientUserId - securityDomain At a minimum, authenticationMethod and clientUserId are required. The information that you provide is included in the envelope's certificate of completion. ## Sending to a remote signer You can request a signing session for a remote recipient who has a Docusign account. Authenticate the request using the recipient's credentials, and do not specify a clientUserId. This differs from the typical behavior where the request is authenticated using the sender's credentials, and the recipient has a clientUserId defined. ## Redirecting back to returnUrl After the signer completes or ends the signing ceremony, Docusign redirects the user's browser back to your app via the returnUrl that you supplied in the request. The signer may be redirected through various Docusign subdomains, depending on the region of the account sending the envelope. Please consult Allowlists for Docusign eSignature service in Security for Docusign eSignature when setting up your allowlists ### The event status parameter Docusign appends an event query parameter to the returnUrl with the outcome of the signing ceremony. Your app can use this event parameter to determine the next step for the envelope. Do not fetch the envelope status by using Envelopes: get or a similar method because doing so will probably hit request and polling limits. | event query parameter | Meaning | | :------------------- | :--------------------------------------------------------------------------------------- | | signing_complete | The recipient has signed the document. | | cancel | The recipient decided to finish later. | | decline | The recipient declined to sign the document. | | exception | An exception has occurred on the server during the signing session. | | fax_pending | Recipient has a fax pending. | | session_timeout | The recipient did not sign the document in time. The timeout is set to 20 minutes. | | ttl_expired | The token was not used within the timeout period or the token has already been accessed. | | viewing_complete | The recipient did not need to sign but has completed the viewing ceremony. | <ds-inlinemessage kind="information" markdown="1"> Because a user can cancel redirection, close their browser after signing, or spoof the landing URL, you should not rely on the <code>returnUrl</code> alone as the single source of truth for envelope status for your integration. </ds-inlinemessage> ### Maintaining State After the recipient completes the recipient view (or signing ceremony), they are redirected to your application. Your application can recover state information about the transaction by storing information in a cookie, or by including query parameters in the returnUrl field. For example. https://myapp.example.com/docusign_return?myState=12345 When the user is redirected to your app, the event query parameter will be appended. In this example, prevent spoofing by not using a guessable value as the state value. ### Related topics - How to request a signature through your app - How to request a signature using a composite template - How to send an envelope via your app - How to set envelope tab values - How to set tab values in a template - How to request a signature using focused view

Returns a URL to the sender view UI. Used before an envelope has been sent. 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. 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 (Android) or 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 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. In this page, use JavaScript and the 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 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 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.

Functions

views_delete_envelope_correct_view(connection, account_id, envelope_id, opts \\ [])

@spec views_delete_envelope_correct_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, nil} | {:ok, DocuSign.Model.ErrorDetails.t()} | {:error, Tesla.Env.t()}

Revokes the correction view URL to the Envelope UI. This API method is obsolete. Your application should not call it. It acts as a null operation.

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The envelope's GUID. Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
  • opts (keyword): Optional parameters
    • :body (CorrectViewRequest):

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure

views_post_account_console_view(connection, account_id, opts \\ [])

@spec views_post_account_console_view(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, DocuSign.Model.EnvelopeViews.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the Docusign eSignature web application. Returns a URL that enables you to embed the Docusign UI in your applications. To view a specific envelope, set the envelopeId property in the request body. ## Information security notice This method provides full access to the sending account. ### Related topics - How to embed the Docusign UI in your app

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • opts (keyword): Optional parameters
    • :body (ConsoleViewRequest):

Returns

  • {:ok, DocuSign.Model.EnvelopeViews.t} on success
  • {:error, Tesla.Env.t} on failure

views_post_envelope_correct_view(connection, account_id, envelope_id, opts \\ [])

@spec views_post_envelope_correct_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, DocuSign.Model.EnvelopeViews.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the envelope correction UI. Use after an envelope has been sent. 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. 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 (Android) or 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 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 Correct View, the envelope must be in the sent or delivered state. Otherwise, a 400 error will be returned with an error message in the response body: { "errorCode": "ENVELOPE_INVALID_STATUS", "message": "Invalid envelope status. Correct view cannot be created for an envelope in a Created state." } ### Modifying the envelope after redirection If you set "sendButtonAction": "redirect" or "backButtonAction": "redirect", and your app will modify the envelope before or after the view completes, you must lock the envelope before the API call and provide the lock as the lockToken attribute in the API request object. Delete the lock token after the browser has been redirected to your application. ### 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. In this page, use JavaScript and the 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 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 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.

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The envelope's GUID. Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
  • opts (keyword): Optional parameters
    • :body (EnvelopeViewRequest):

Returns

  • {:ok, DocuSign.Model.EnvelopeViews.t} on success
  • {:error, Tesla.Env.t} on failure

views_post_envelope_edit_view(connection, account_id, envelope_id, opts \\ [])

@spec views_post_envelope_edit_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, DocuSign.Model.EnvelopeViews.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the edit view UI. Use before an envelope has been sent. This API method has been replaced by the EnvelopeViews:createSender API method. The two API methods work exactly the same, Migration required To solve an application security issue, you must migrate to the new API request format. See the EnvelopeViews:createSender API method for more information. Backwards compatibility will be provided for a limited time.

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The envelope's GUID. Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
  • opts (keyword): Optional parameters
    • :body (EnvelopeViewRequest):

Returns

  • {:ok, DocuSign.Model.EnvelopeViews.t} on success
  • {:error, Tesla.Env.t} on failure

views_post_envelope_recipient_shared_view(connection, account_id, envelope_id, opts \\ [])

@spec views_post_envelope_recipient_shared_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, DocuSign.Model.ViewUrl.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the shared recipient view UI for an envelope. Returns a URL that enables you to embed the Docusign UI recipient view of a shared envelope in your applications. This is the view that a user sees of an envelope that a recipient on the same account has shared with them. Due to screen space issues, do not use an <iframe> for embedded operations on mobile devices. For iOS devices, Docusign recommends using a WebView. ### Related topics - Embedded signing and sending - How to send an envelope via your app - How to embed the Docusign UI in your app

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The envelope's GUID. Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
  • opts (keyword): Optional parameters
    • :body (RecipientViewRequest):

Returns

  • {:ok, DocuSign.Model.ViewUrl.t} on success
  • {:error, Tesla.Env.t} on failure

views_post_envelope_recipient_view(connection, account_id, envelope_id, opts \\ [])

@spec views_post_envelope_recipient_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, DocuSign.Model.EnvelopeViews.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the recipient view UI. For signer recipients, returns the embedded signing view. Can also be used for other recipient types. Returns a URL that enables you to embed the recipient view of the DocuSign UI in your applications. If the recipient is a signer, then the view will provide the signing ceremony. This method is only used with envelopes in the sent status. <ds-inlinemessage kind="information" markdown="1"> Due to screen space issues, do not use an <code>&lt;iframe&gt;</code> for embedded operations on mobile devices. For iOS devices, Docusign recommends using a WebView. </ds-inlinemessage> ### The returned URL The URL returned in this method's response is intended to be used immediately to redirect the signer to the recipient view. You can open the recipient view in the current browser or in a new tab. After the signer is redirected to the recipient view, they must interact with the Docusign system periodically or their session will time out. <ds-inlinemessage kind="warning" markdown="1"> The returned URL can be used only once and expires after 5 minutes. Do not store or email the returned URL. </ds-inlinemessage> If you want to invite someone to an embedded signing session via email, the email invitation's URL must be to your application. When invoked, your app should request a recipientView URL from Docusign and then redirect the signer to that URL. ### How to specify the default language You can append the locale query parameter to the URL returned by this method to specify a language. The language for the recipient view follows this order or precedence: - The language specified by the sender for the recipient. - The locale parameter appended to the URL. - The account language if the signer has a Docusign account. - The language used in a previous signing if the signer is return signer. - The browser language. For example, to set the default language to Canadian French, you would add this query parameter to the returned URL: ...&locale=fr_CA ## Authentication Your application is responsible for authenticating the identity of the recipient or signer when you use this method. Use the following parameters to record how the recipient was authenticated. - assertionId - authenticationInstant - authenticationMethod - clientUserId - securityDomain At a minimum, authenticationMethod and clientUserId are required. The information that you provide is included in the envelope's certificate of completion. ## Sending to a remote signer You can request a signing session for a remote recipient who has a Docusign account. Authenticate the request using the recipient's credentials, and do not specify a clientUserId. This differs from the typical behavior where the request is authenticated using the sender's credentials, and the recipient has a clientUserId defined. ## Redirecting back to returnUrl After the signer completes or ends the signing ceremony, Docusign redirects the user's browser back to your app via the returnUrl that you supplied in the request. The signer may be redirected through various Docusign subdomains, depending on the region of the account sending the envelope. Please consult Allowlists for Docusign eSignature service in Security for Docusign eSignature when setting up your allowlists ### The event status parameter Docusign appends an event query parameter to the returnUrl with the outcome of the signing ceremony. Your app can use this event parameter to determine the next step for the envelope. Do not fetch the envelope status by using Envelopes: get or a similar method because doing so will probably hit request and polling limits. | event query parameter | Meaning | | :------------------- | :--------------------------------------------------------------------------------------- | | signing_complete | The recipient has signed the document. | | cancel | The recipient decided to finish later. | | decline | The recipient declined to sign the document. | | exception | An exception has occurred on the server during the signing session. | | fax_pending | Recipient has a fax pending. | | session_timeout | The recipient did not sign the document in time. The timeout is set to 20 minutes. | | ttl_expired | The token was not used within the timeout period or the token has already been accessed. | | viewing_complete | The recipient did not need to sign but has completed the viewing ceremony. | <ds-inlinemessage kind="information" markdown="1"> Because a user can cancel redirection, close their browser after signing, or spoof the landing URL, you should not rely on the <code>returnUrl</code> alone as the single source of truth for envelope status for your integration. </ds-inlinemessage> ### Maintaining State After the recipient completes the recipient view (or signing ceremony), they are redirected to your application. Your application can recover state information about the transaction by storing information in a cookie, or by including query parameters in the returnUrl field. For example. https://myapp.example.com/docusign_return?myState=12345 When the user is redirected to your app, the event query parameter will be appended. In this example, prevent spoofing by not using a guessable value as the state value. ### Related topics - How to request a signature through your app - How to request a signature using a composite template - How to send an envelope via your app - How to set envelope tab values - How to set tab values in a template - How to request a signature using focused view

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The ID of the draft envelope or template to preview.
  • opts (keyword): Optional parameters
    • :body (RecipientViewRequest):

Returns

  • {:ok, DocuSign.Model.EnvelopeViews.t} on success
  • {:error, Tesla.Env.t} on failure

views_post_envelope_sender_view(connection, account_id, envelope_id, opts \\ [])

@spec views_post_envelope_sender_view(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, DocuSign.Model.EnvelopeViews.t()}
  | {:ok, DocuSign.Model.ErrorDetails.t()}
  | {:error, Tesla.Env.t()}

Returns a URL to the sender view UI. Used before an envelope has been sent. 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. 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 (Android) or 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 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. In this page, use JavaScript and the 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 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 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.

Parameters

  • connection (DocuSign.Connection): Connection to server
  • account_id (String.t): The external account number (int) or account ID GUID.
  • envelope_id (String.t): The envelope's GUID. Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
  • opts (keyword): Optional parameters
    • :body (EnvelopeViewRequest):

Returns

  • {:ok, DocuSign.Model.EnvelopeViews.t} on success
  • {:error, Tesla.Env.t} on failure