> 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

# RequestRecipientToken and RequestRecipientFaxToken

Docusign constrains access to the Embedded signature process via short-lived Recipient Tokens. Successful token requests return an URL that will invoke the Docusign signing wizard for a particular envelope and Embedded Recipient. Envelopes must be sent before a recipient token can be requested (recipient tokens will not work with draft envelopes).

> **Important:** iFrames should not be used for embedded operations on mobile devices due to screen space issues. For iOS devices Docusign recommends using a WebView.

There are two types of recipient tokens available:

* **RequestRecipientToken**: This token returns a URL to invoke a Docusign signing session where the signer completes the signing process online. This URL may be up to 2083 characters in length, and can be redirected through varying subdomains depending on the region of the account sending the envelope. Ensure that:

* You have added all of [Docusign’s subdomains](https://www.docusign.com/trust/security/esignature) to your system's allowlist
  * Your system can handle URL lengths of at least 2083 characters

* **RequestRecipientFaxToken**: This token returns a URL to invoke a Docusign signing session where the signer is required to print out and sign documents. The documents are then returned to Docusign by fax or upload.

> **Note:** An alternative to using RequestRecipientFaxToken is to use RequestRecipientFaxPDF to return a PDF version of a fax cover page and documents in an envelope rather than returning a URL for a signing session. For more information about this option see [RequestRecipientFaxPDF](/docs/esign-soap-api/reference/embedding-group/requestrecipientfaxpdf).

This section describes the token methods and the behaviors.

The RequestRecipientToken and RequestRecipientFaxToken methods use the format and rules, and are divided into three sections: Entity Identification, Authentication Assertions and InSessionCallBackURL.

**`C#`**

```csharp title="C#"
// Create envelope as shown in linked code
DocuSignWeb.Envelope envelope = <create envelope>;
// Need to specify captive info for these recipients
envelope.Recipients[0].CaptiveInfo = new DocuSignWeb.RecipientCaptiveInfo();
envelope.Recipients[0].CaptiveInfo.ClientUserID = "User4521";

DocuSignWeb.EnvelopeStatus status = _apiClient.SendEnvelope(envelope);

// Construct the recipient token authentication assertion
// Specify ID, start time, method and domain
DocuSignWeb.RequestRecipientTokenAuthenticationAssertion assertion = new DocuSignWeb.RequestRecipientTokenAuthenticationAssertion();
assertion.AssertionID = new Guid().ToString();
assertion.AuthenticationInstant = DateTime.Now;
assertion.AuthenticationMethod = DocuSignWeb.RequestRecipientTokenAuthenticationAssertionAuthenticationMethod.Password;
assertion.SecurityDomain = "Request Recipient Token Test";

// Construct the URLs based on username
DocuSignWeb.Recipient recipient = envelope.Recipients[0];
DocuSignWeb.RequestRecipientTokenClientURLs urls = new DocuSignWeb.RequestRecipientTokenClientURLs();
String urlBase = baseURL;
urls.OnSigningComplete = urlBase + "?event=SignComplete&uname=" + recipient.UserName;
urls.OnViewingComplete = urlBase + "?event=ViewComplete&uname=" + recipient.UserName;
urls.OnCancel = urlBase + "?event=Cancel&uname=" + recipient.UserName;
urls.OnDecline = urlBase + "?event=Decline&uname=" + recipient.UserName;
urls.OnSessionTimeout = urlBase + "?event=Timeout&uname=" + recipient.UserName;
urls.OnTTLExpired = urlBase + "?event=TTLExpired&uname=" + recipient.UserName;
urls.OnIdCheckFailed = urlBase + "?event=IDCheck&uname=" + recipient.UserName;
urls.OnAccessCodeFailed = urlBase + "?event=AccessCode&uname=" + recipient.UserName;
urls.OnException = urlBase + "?event=Exception&uname=" + recipient.UserName;

// Request the token for a specific recipient
String token = _apiClient.RequestRecipientToken(status.EnvelopeID,
recipient.CaptiveInfo.ClientUserID, recipient.UserName,
recipient.Email, assertion, urls);

// Display token
Console.WriteLine("Recipient token is {0}", token);
```

**`PHP`**

```php title="PHP"
// Create an envelope as shown in linked code
$env = <create envelope>;

// Specify captive info for recipients
$captiveInfo = new RecipientCaptiveInfo();
$captiveInfo->ClientUserId = "User4521";
$env->Recipients[0]->CaptiveInfo = $captiveInfo;

// Now send the envelope
$sendEnvelopeparams = new SendEnvelope();
$sendEnvelopeparams->Envelope = $env;
$createResult = $api->SendEnvelope($sendEnvelopeparams)->SendEnvelopeResult;

// Construct the recipient token authentication assertion and specify
// ID, start time, method, and domain
$assertion = new RequestRecipientTokenAuthenticationAssertion();
$assertion->AssertionID = guid();
$assertion->AuthenticationInstant = nowXsdDate();
$assertion->AuthenticationMethod = RequestRecipientTokenAuthenticationAssertionAuthenticationMethod::Password;
$assertion->SecurityDomain = "Request Recipient Token Test";

// Construct the URLs based on UserName
$recip = $env->Recipients[0];
$urls = new RequestRecipientTokenClientURLs();
$urlbase = "https://127.0.0.1/";
$urls->OnSigningComplete = $urlbase . "?event=SignComplete&uname=" . $recip->UserName;
$urls->OnViewingComplete = $urlbase . "?event=ViewComplete&uname=" . $recip->UserName;
$urls->OnCancel = $urlbase . "?event=Cancel&uname=" . $recip->UserName;
$urls->OnDecline = $urlbase . "?event=Decline&uname=" . $recip->UserName;
$urls->OnSessionTimeout = $urlbase . "?event=Timeout&uname=" . $recip->UserName;
$urls->OnTTLExpired = $urlbase . "?event=TTLExpired&uname=" . $recip->UserName;
$urls->OnIdCheckFailed = $urlbase . "?event=IDCheck&uname=" . $recip->UserName;
$urls->OnAccessCodeFailed = $urlbase . "?event=AccesssCode&uname=" . $recip->UserName;
$urls->OnException = $urlbase . "?event=Exception&uname=" . $recip->UserName;

// Send
$requestRecipientTokenparams = new RequestRecipientToken();
$requestRecipientTokenparams->EnvelopeID = $createResult->EnvelopeID;
$requestRecipientTokenparams->ClientUserID = $recip->CaptiveInfo->ClientUserID;
$requestRecipientTokenparams->Username = $recip->UserName;
$requestRecipientTokenparams->Email = $recip->Email;
$requestRecipientTokenparams->AuthenticationAssertion = $assertion;
$requestRecipientTokenparams->ClientURLs = $urls;
$response = $api->RequestRecipientToken($requestRecipientTokenparams);
```

![Embedded](file:docs/assets/soap/RequestRecipientToken\(Embedded\).png)