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

{
  "success": true,
  "data": {
    "id": "abc123",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

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

{
  "success": true,
  "data": {
    "id": "abc123",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}