Skip to navigation
API referenceSending Function Group

Rules for CreateAndSendEnvelope & CreateEnvelope

View as Markdown

Rules for CreateAndSendEnvelope and CreateEnvelope

API user specific rules

  • The length of AccountId, document Name should not exceed 100 characters. Document password length should not exceed 50 characters. UserName, Email and access code of the recipient should not exceed 100 characters.

  • SignatureName in SignatureInfo element should at least have one character. SignatureInitial should have a minimum 1 character and maximum 10 characters.

  • Font styles supported for recipient signature are RageItalic, Mistral, BradleyHandITC, KaufmannBT, Freehand575 and LuciaBT.

  • Allowed length for State attribute in address information element will be 2 characters. For Zip it will be 5 characters and for ZipPlus4 it will be 4 characters.

  • Allowed length for SSN4 will be 4 characters and for SSN9 it will be 9 characters.

  • The length of Label and Type for attachment element should not exceed 100 characters.

  • CaptiveInfo element is made up of the optional ClientUserId and EmbeddedRecipientStartURL elements that 1) determine if a recipient is embedded or remote, and 2) express a redirect URL used to start an embedded recipient’s signing session. ClientUserId is a sender created value that can be a maximum of 100 characters. If there is a value for this (it is not null) then the recipient is considered to be embedded. Note that if a ClientUserId is used and the account settings SignerMustHaveAccount or SignerMustLoginToSign are true, an error is generated on sending. EmbeddedRecipientStartURL is a sender provided valid URL string for redirecting the recipient. When using this option, the embedded recipient still receives an email from Docusign, just as a remote recipient would, but when the document link in the email is clicked the recipient is redirected, through Docusign, to this URL to complete their actions. When routing to the URL, it is up to the sender’s system (the server responding to the URL) to then request a recipient token to launch a signing session.

  • If the value SIGN_AT_DOCUSIGN is used for this node, the recipient will be directed to an embedded signing or viewing process directly at Docusign. The signing or viewing action is initiated by the Docusign system and the transaction activity and Certificate of Completion records will reflect this. In all other ways the process is identical to an embedded signing or viewing operation that would be launched by any partner.

    • It is important to remember that in a typical embedded workflow the authentication of an embedded recipient is the responsibility of the sending application and Docusign expects that senders will follow their own process for establishing the recipient’s identity. In this workflow the recipient goes through the sending application before the embedded signing or viewing process in initiated. However, when the sending application sets EmbeddedRecipientStartURL=SIGN_AT_DOCUSIGN, the recipient goes directly to the embedded signing or viewing process bypassing the sending application and any authentication steps the sending application would use. In this case, Docusign recommends that one of the normal Docusign authentication features (Access Code, Phone Authentication, SMS Authentication, etc.) be used to verify the identity of the recipient.
    • If a ClientUserId is NOT provided and an EmbeddedRecipientStartURL is provided, Docusign will ignore the redirect URL and launch the standard signing process for the email recipient. Information can be appended to the EmbeddedRecipientStartURL using merge fields. The available merge fields items are: EnvelopeId, RecipientId, RecipientName, RecipientEmail, and CustomFields. The CustomFields must be part of the Recipient or Envelope. The merge fields are enclosed in double brackets. Example: http://senderHost/[[mergeField1]]/beginSigningSession?[[mergeField2]]&[[mergeField3]]

Rules for determining the brandId used in an envelope:

  • If a brandId is specified in the envelope/template and that brandId is available to the account, that brand is used in the envelope.
  • If more than one template is used in an envelope and more than one brandId is specified, the first brandId specified is used throughout the envelope.
  • In cases where no brand is specified and the sender belongs to a Group; if there is only one brand associated with the Group, then that brand is used in the envelope. Otherwise, the account’s default signing brand is used.
  • For envelopes that do not meet any of the previous rules, the account’s default signing brand is used in the envelope.

Rules for Exceptions thrown by the API

  • AccountId specified while creating an envelope should exist else an exception with error message “Account_Does_Not_Exist_In_System” is thrown.
  • DocumentID specified in the tab element should refer to a document in the envelope else exception with error message “Tab_Refers_To_Missing_Document” is thrown.
  • RecipientID specified in the tab element should refer to an existing recipients ID attribute. Else exception is thrown with error message “Tab_Refers_To_Missing_Recipient”.
  • Tab is affixed to a specific page number of the document. So the document specified by DocumentID in the Tab element should have page number specified by PageNumber. Else exception “Tab_Pagenumber_Is_Not_In_Document” is thrown.
  • The document element in the CreateEnvelope and CreateAndSendEnvelope should contain the encoded document. Else exception “No_Document_Received” is thrown.
  • The Email specified in the recipient element should exist else an exception is thrown with error message “Invalid_Email_Address_For_Recipient”.
  • Recipient specified by UserName and Email pair in the recipient element must exist. Else exception with error message “Unknown_Envelope_Recipient” is thrown.
  • If a signer recipient has any tabs available to them in the envelope they will be required to have at least one signable tab in at least one of the documents. Else exception with error message “Signer_Recipient_Has_No_Signable_Tabs” is thrown. If the signer recipient has no tabs available they will be considered a freeform signer and be required to place the tabs themselves.
  • Access code is used to validate recipient identity. User has to enter the access code specified in the recipient element in the CreateEnvelope/CreateAndSendEnvelope to prove his/her identity. Recipient will need to validate his/her identity even if access code is not specified in the recipient element if RequireIDLookup attribute is set to true. But in this case the identity is verified not by entering access code, but by answering a questionnaire correctly. If the user fails to validate his/her identity then an exception is thrown with error message “Recipient_Has_Failed_Security_Check”.
  • All recipients in an envelope should have a valid routing order else an exception with error message “Recipient_Has_Invalid_RoutingOrder” is thrown.
  • There is a provision for creating custom tab. But in case of custom tab both the attributes Name and TabLabel should be specified. If only one of the attribute is specified in the Tab element then an exception “CustomTab_Is_Incomplete” is thrown.
  • Account should have API permission to utilize CreateEnvelope and CreateAndSendEnvelope methods. Account needs to have “InSession permission” to send envelopes to InSession recipients. Else an exception with error message “Account_Lacks_Permissions” is thrown.
  • AccountID mentioned should not be suspended by Docusign Administrator; else exception will be thrown with message “Account_Has_Been_Suspended”.
  • If the recipient Email specified in CreateAndSendEnvelope/CreateEnvelope is already reserved by another then processor throws an exception with error message “Email_Is_Reserved”.
  • In CreateEnvelope and CreateAndSend Envelope, the account Id is validated for pricing plan, if the account does not have a pricing plan then “Account_Lacks_Pricing_Plan” exception is thrown
  • InSession carbon copy recipients cannot be specified in CreateAndSendEnvelope. If the recipient Type is CC then ClientUserId has to be null else exception “Captive_Carbon_Copy_Recipient_Not_Supported” will be thrown.