---
title: "Returns a URL to the recipient view UI. For signer recipients, returns the embedded signing view. Can also be used for other recipient types."
method: POST
path: "/v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient"
tags: ["EnvelopeViews"]
---

# Returns a URL to the recipient view UI. For signer recipients, returns the embedded signing view. Can also be used for other recipient types.

`POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient`

Returns a URL that enables you to
[embed the recipient view](/docs/esign-rest-api/esign101/concepts/embedding/)
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](https://www.docusign.com/trust/security/esignature#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](/docs/esign-rest-api/reference/envelopes/envelopes/get/)
or a similar method because doing so
will probably hit [request and polling limits](/docs/esign-rest-api/esign101/rules-and-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](/docs/esign-rest-api/how-to/request-signature-in-app-embedded/)
- [How to request a signature using a composite template](/docs/esign-rest-api/how-to/request-signature-composite-template-embedded/)
- [How to send an envelope via your app](/docs/esign-rest-api/how-to/embedded-sending/)
- [How to set envelope tab values](/docs/esign-rest-api/how-to/set-envelope-tab-values/)
- [How to set tab values in a template](/docs/esign-rest-api/how-to/set-template-tab-values/)
- [How to request a signature using focused view](/docs/esign-rest-api/how-to/request-signature-focused-view/)

## Path parameters

- `accountId` string, required
- `envelopeId` string, required

## Request body

- RecipientViewRequest — The request body for the [EnvelopeViews: createRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient/) and [EnvelopeViews: createSharedRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createsharedrecipient/) methods.
  - `assertionId` string — A unique identifier of the authentication event executed by the client application.
  - `authenticationInstant` string — A sender-generated value that indicates the date and time that the signer was authenticated.
  - `authenticationMethod` string — Required. Choose a value that most closely matches the technique your application used to authenticate the recipient / signer. Choose a value from this list: * Biometric * Email * HTTPBasicAuth * Kerberos * KnowledgeBasedAuth * None * PaperDocuments * Password * RSASecureID * SingleSignOn_CASiteminder * SingleSignOn_InfoCard * SingleSignOn_MicrosoftActiveDirectory * SingleSignOn_Other * SingleSignOn_Passport * SingleSignOn_SAML * Smartcard * SSLMutualAuth * X509Certificate This information is included in the Certificate of Completion.
  - `clientURLs` RecipientTokenClientURLs
    - `onAccessCodeFailed` string
    - `onCancel` string
    - `onDecline` string
    - `onException` string
    - `onFaxPending` string
    - `onIdCheckFailed` string
    - `onSessionTimeout` string
    - `onSigningComplete` string
    - `onTTLExpired` string
    - `onViewingComplete` string
  - `clientUserId` string — A sender-created value. If provided, the recipient is treated as an embedded (captive) recipient or signer. Use your application's client ID (user ID) for the recipient. Doing so enables the details of your application's authentication of the recipient to be connected to the recipient's signature if the signature is disputed or repudiated. Maximum length: 100 characters.
  - `displayFormat` string
  - `email` string — (Required) Specifies the email of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient.
  - `frameAncestors` string[] — An array of ancestors that can embed the frame. This property is required when [using focus view](/docs/esign-rest-api/how-to/request-signature-focused-view/). In the demo environment, include your site URL and `https://apps-d.docusign.com`. You can use `http://localhost` for local development and testing. Example: `["https://my.site.com", "https://apps-d.docusign.com"]` In the production environment, include your site URL and `https://apps.docusign.com`. HTTPS must be enabled on your site. Example: `["https://my.site.com", "https://apps.docusign.com"]`
  - `messageOrigins` string[] — The originating domain for the signature request message. This property is required when [using focus view](/docs/esign-rest-api/how-to/request-signature-focused-view/). In the demo environment, the value must be `https://apps-d.docusign.com`. In production, the value must be `https://apps.docusign.com`.
  - `pingFrequency` string — Only used if `pingUrl` is specified. This is the interval, in seconds, between pings on the `pingUrl`. The default is `300` seconds. Valid values are 60-1200 seconds.
  - `pingUrl` string — The client URL that the Docusign Signing experience should ping to indicate to the client that Signing is active. An HTTP GET call is executed against the client. The response from the client is ignored. The intent is for the client to reset its session timer when the request is received.
  - `recipientId` string — Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
  - `returnUrl` string — (Required) The URL to which the user should be redirected after the signing session has ended. Maximum Length: 470 characters. If the `returnUrl` exceeds this limit, the user is redirected to a truncated URL Be sure to include `https://` in the URL or redirecting might fail on some browsers. When Docusign redirects to this URL, it will include an `event` query parameter that your app can use: * `access_code_failed`: Recipient used incorrect access code. * `cancel`: Recipient canceled the signing operation, possibly by using the **Finish Later** option. * `decline`: Recipient declined to sign. * `exception`: A system error occurred during the signing process. * `fax_pending`: Recipient has a fax pending. * `id_check_failed`: Recipient failed an ID check. * `session_timeout`: The session timed out. An account can control this timeout by using the **Signer Session Timeout** option. * `signing_complete`: The recipient completed the signing ceremony. * `ttl_expired`: The Time To Live token for the envelope has expired. After being successfully invoked, these tokens expire after five minutes. * `viewing_complete`: The recipient completed viewing an envelope that is in a read-only/terminal state, such as completed, declined, or voided.
  - `securityDomain` string — The domain in which the user authenticated.
  - `userId` string — The user ID of the recipient. You can use either the user ID or email and user name to identify the recipient. If `userId` is used and a `clientUserId` is provided, the value in the `userId` property must match a `recipientId` (which you can retrieve with a GET recipients call) for the envelope. If a `userId` is used and a `clientUserId` is not provided, the `userId` must match the user ID of the authenticating user.
  - `userName` string — The username of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient.
  - `xFrameOptions` string — Specifies whether a browser should be allowed to render a page in a frame or IFrame. Setting this property ensures that your content is not embedded into unauthorized pages or frames. Valid values are: - `deny`: The page cannot be displayed in a frame. - `same_origin`: The page can only be displayed in a frame on the same origin as the page itself. - `allow_from`: The page can only be displayed in a frame on the origin specified by the `xFrameOptionsAllowFromUrl` property.
  - `xFrameOptionsAllowFromUrl` string — When the value of `xFrameOptions` is `allow_from`, this property specifies the origin on which the page is allowed to display in a frame. If the value of `xFrameOptions` is `allow_from`, you must include a value for this property.

## 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)