> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Get URL to recipient view UI

POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient
Content-Type: application/json

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.

Due to screen space issues, Docusign recommends using [Focused View](/docs/esign-rest-api/how-to/request-signature-focused-view/) if you plan to include the Docusign signing elements inside an `<iframe>` object.
For iOS devices, Docusign recommends using a WebView.

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

The returned URL can be used only once and
expires after 5 minutes.
Do not store or email the returned URL.

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:

```text
...&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.                                                       |
| access\_code\_failed  | The recipient failed to provide the correct access code needed for recipient authentication. |
| 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.                                                                 |
| id\_check\_failed     | The recipient failed to complete identity verification correctly.                            |
| 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.                   |

Because a user can cancel redirection, close their
browser after signing, or spoof the landing URL,
you should not rely on the `returnUrl`
alone as the single source of truth for envelope
status for your integration.

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

Reference: https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient

## Authentication

- `Authorization` header (required) (prefixed with ` Bearer  `) — OAuth 2.0 access token (JWT or auth-code grant). Sent as `Authorization: Bearer <token>` on every request except `GET /v2.1` and `GET /service_information`, which are public discovery endpoints.

## Servers

- `https://demo.docusign.net/restapi` (Demo, default)
- `https://www.docusign.net/restapi` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The external account number (int) or account ID Guid.
- `envelopeId` (string, required) — The ID of the draft envelope or template to preview.

### Body (application/json)

This endpoint expects a recipientViewRequest.

- `assertionId` (string, optional) — A unique identifier of the authentication event executed by the client application.
- `authenticationInstant` (string, optional) — A sender-generated value that indicates the date and time that the signer was authenticated.
- `authenticationMethod` (string, optional) — 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, optional)
- `clientUserId` (string, optional) — 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, optional) — This value determines whether the display will show an embedded or focused view experience. If set to `focused`, the display will use the focused view experience. If set to `default`, or if not set, the display will use the embedded experience.
- `email` (string, optional) — (Required) Specifies the email of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient.
- `frameAncestors` (list of string, optional) — 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` (list of string, optional) — 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, optional) — 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, optional) — 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, optional) — Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
- `returnUrl` (string, optional) — (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, optional) — The domain in which the user authenticated.
- `userId` (string, optional) — 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, optional) — The username of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient.
- `xFrameOptions` (string, optional) — 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, optional) — 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.

- `url` (string, optional) — URL for the template edit view.

## Errors

### 400 Bad Request Error

Error encountered.

- `errorCode` (string, optional) — The code associated with the error condition.
- `message` (string, optional) — A brief message describing the error condition.

## Types

### recipientTokenClientURLs

- `onAccessCodeFailed` (string, optional)
- `onCancel` (string, optional)
- `onDecline` (string, optional)
- `onException` (string, optional)
- `onFaxPending` (string, optional)
- `onIdCheckFailed` (string, optional)
- `onSessionTimeout` (string, optional)
- `onSigningComplete` (string, optional)
- `onTTLExpired` (string, optional)
- `onViewingComplete` (string, optional)

## Examples

**Request**

```json
{
  "assertionId": "sample string 1",
  "authenticationInstant": "sample string 2",
  "authenticationMethod": "sample string 3",
  "clientURLs": {
    "onAccessCodeFailed": "sample string 1",
    "onCancel": "sample string 2",
    "onDecline": "sample string 3",
    "onException": "sample string 4",
    "onFaxPending": "sample string 5",
    "onIdCheckFailed": "sample string 6",
    "onSessionTimeout": "sample string 7",
    "onSigningComplete": "sample string 8",
    "onTTLExpired": "sample string 9",
    "onViewingComplete": "sample string 10"
  },
  "clientUserId": "sample string 4",
  "displayFormat": "sample string 5",
  "email": "sample string 6",
  "frameAncestors": [
    "sample string 1"
  ],
  "messageOrigins": [
    "sample string 1"
  ],
  "pingFrequency": "sample string 7",
  "pingUrl": "sample string 8",
  "recipientId": "sample string 9",
  "returnUrl": "sample string 10",
  "securityDomain": "sample string 11",
  "userId": "sample string 12",
  "userName": "sample string 13",
  "xFrameOptions": "sample string 14",
  "xFrameOptionsAllowFromUrl": "sample string 15"
}
```

**Response**

```json
{
  "url": "sample string 1"
}
```