Skip to navigation
API referenceEmbedding Function Group

RequestRecipientToken and RequestRecipientFaxToken

View as Markdown

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

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.

// 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);
Embedded