Quickly Initiate Envelope

POST /esignglobal/v1/envelope/createAndStart

Interface Description

Quickly initiate an envelope, including functions such as creating an envelope, adding documents pending signature, and adding signers.

Supports automatic activation: After the interface call succeeds, the envelope is successfully created and activated, at which point it automatically begins to flow.
Supports automatic completion: Once all signers have completed their signatures, the envelope automatically ends.

Request Parameters

Parameter Name					Type	Required	Description
subject					string	true	Envelope Subject Example: "Offer Letter"
remark					string	false	Envelope remarks, with a length limit of 1000 characters
signerSettings					object	false	Operations allowed for signers
	allowTransfer				boolean	false	Whether to allow the signer to transfer this envelope to another person for signing. Default is false. true - Allows signers in the envelope to have the power to transfer the envelope to others; false - Does not allow signers in the envelope to have the power to transfer the envelope to others;
	allowModifyName				boolean	false	Whether to allow the signing party to modify their name. This only applies to template signatures. Default is false. true - Allows the signer to modify their name false - Does not allow the signer to modify their name
expireAfterSeconds					long	false	Envelope expiration time. The envelope expires after a specified number of seconds. Expiration range: 86,400 seconds (1 day) ~ 7,776,000 seconds (90 days)
redirectUrl					string	false	Must be a valid HTTPS address
callBackUrl					string	false	Callback URL (length 500). Must conform to the HTTPS protocol address format.
sendLaterAfterSeconds					long	false	Supports user-delayed sending, measured in seconds Supported time range: 3600 seconds (1 hour) ~ 259200 seconds (30 days)
autoFinish					boolean	false	Controls whether the envelope automatically ends. Default is true. true- Envelope ends automatically false- Envelope ends manually
CCInfos					array	false	CC recipient information collection
	userEmail				string	false	CC recipient email address
	userName				string	false	CC recipient name, used to display the CC recipient's name on the signing page and envelope. [Note]: Must not contain the following 9 special characters: / \ : * " < > \| ? and all emoji characters
	ccOrder				int	false	The sequential position of the CC recipient in the signing process, sharing the sequence with the signer's signOrder. If not provided, the original CC notification logic will be retained.
	customizeSettings				object	false	Custom configuration
		notificationSettings			object	false	Notification-type custom configuration
			notificationLanguage		string	false	Notification language, defaults to the 'Default Notification Language' setting en-US English zh-CN Simplified Chinese zh-Hant Traditional Chinese ja-JP Japanese es-MX Spanish pt-PT Portuguese th-TH Thai id-ID Indonesian vi-VN Vietnamese ms-MY Malay fil-PH Filipino de-DE German fr-FR French ru-RU Russian it-IT Italian ko-KR Korean
signFiles					array	true	Collection of signing document information, displayed in the order documents were added.
	fileKey				string	true	Signing document fileKey, only PDF format is supported
	documentFields				array	false	List of dimension control elements. Used to add dimension controls that are not bound to signers on specified documents.
		fieldType			string	false	Control type. Pass eMeterai to indicate the Indonesian stamp duty control.
		pageNo			string	false	Page number where the control is located. The Indonesian stamp duty control only supports specifying a single page; you must pass a single page number. Continuous or non-continuous multi-page formats such as 1-3 or 1,3 are not supported.
		posX			float	false	X-axis offset, with the bottom-left corner of the page as the coordinate origin. The coordinate range is consistent with that of other controls.
		posY			float	false	Y-axis offset, with the bottom-left corner of the page as the origin. The coordinate range is consistent with that of other controls.
attachments					array	false	Envelope attachment collection, displayed in the order files were added.
	fileKey				string	false	File fileKey
signerInfos					array	true	Signer information collection
	businessId				string	false	Developer-defined business number, with a length limit of 500 characters
	roleTypes				array	false	Signer operation method, default value is `["sign", "fill"]` fill - Fill in sign - Sign
	deliveryMethods				string	false	Notification method, default is auto auto- When userEmail is provided, send an email notification; when phoneNumber is provided, send an SMS notification none- Do not send message notifications email- Send email notification sms- Send SMS notification WhatsApp- Send WhatsApp notification
	userEmail				string	false	Signer's email address
	userName				string	true	Signer name, used to display the signer's name on the signing page and envelope. [Note] The following 9 special characters are not allowed: / \ : * " < > \| ? and all emoji characters
	minimumReadingDuration				int	false	Forced reading countdown time setting on the configuration page. Default value is 0 (unit: seconds, maximum value: 999). 0 or omitting this parameter indicates that the feature is disabled; no reading countdown is required.
	readToEndRequired				boolean	false	Indicates whether the document must be read to the end. Default is false; true enables the feature; false or omitting this parameter disables it.
	phoneNumber				object	false	Phone number. Defaults to empty. Required when SMS notifications are needed. Both countryCode and number must be provided.
		countryCode			string	false	International country/region code. Do not include the '+' symbol.
		number			string	false	No format validation. Maximum length is limited to 13 characters.
	customizeSettings				object	false	Custom configuration
		notificationSettings			object	false	Notification-specific custom configuration
			customizeMessage		string	false	Dedicated message notification. Character limit: 200.
			notificationLanguage		string	false	Notification language. Defaults to the 'Default Notification Language' setting. en-US English zh-CN Simplified Chinese zh-Hant Traditional Chinese ja-JP Japanese es-MX Spanish pt-PT Portuguese th-TH Thai id-ID Indonesian vi-VN Vietnamese ms-MY Malay fil-PH Filipino de-DE German fr-FR French ru-RU Russian it-IT Italian ko-KR Korean
	signOrder				int	true	Signing order, minimum value is 1. For parallel signing, the same order value can be specified.
	signTaskSuspend				boolean	false	Whether to set a process blocking node before this signing position, default is false. true - set blocking node; false - do not set blocking node. Blocking configuration must be consistent within an OR-signing group with the same signOrder.
	suspensionKey				string	false	Blocking node identifier, maximum 500 characters, unique within the same envelope. Required when signTaskSuspend=true; must not be passed when signTaskSuspend=false or omitted.
	suspendReason				string	false	Blocking reason, cannot be empty when provided, maximum 50 characters. Only allowed when signTaskSuspend=true; if omitted, it defaults to indicating that waiting for external system processing is required. Must not be passed when signTaskSuspend=false or omitted.
	anySigner				boolean	false	Whether to allow any one person to sign, default is false true- Only one person needs to sign among those with the same signOrder false- All persons with the same signOrder need to sign
	authModes				string	false	Verification method, default is noAuth noAuth- No verification accessCode- Verification using signing password sms- SMS OTP verification idVerification- ID document verification emailAuth- Email OTP verification digitalId- Electronic identity verification whatsappAuth- WhatsApp OTP verification
	authConfig				object	false	Verification Method Settings
		accessCode			object	false	Signature Password Settings, required when authModes=accessCode
			accessCode		string	false	Password content, case-insensitive, can include alphanumeric characters, maximum length 45
			promptInfo		string	false	Access password prompt message, cannot contain the access password, maximum length 30, required when authModes=accessCode
		sms			object	false	SMS OTP verification, required when authModes=sms
			countryCode		string	false	International country/region code, do not include '+'
			number		string	false	No format validation, only limit maximum length to 13 digits
		idVerification			object	false	ID document verification settings, required when authModes=idVerification
			name		string	false	Full name on the signer's ID document, maximum length 100 characters
		emailAuth			object	false	Email OTP verification, required when authModes=emailAuth
			authEmail		string	false	Signer identity verification email address
		digitalId			array	false	Electronic identity verification, required when authModes=digitalId
			authApp		string	false	APP used for electronic identity verification singpass- Use Singpass for identity authentication iamsmart- Use i AM Smart for identity authentication
			idNumber		string	false	ID document number of the signer to be verified When authApp=singpassthe input rule is: uppercase letter + 7 or 8 digits + uppercase letter When authApp=iamsmartthe input rule is: 1. One uppercase letter (A-Z), or two uppercase letters (AA-ZZ), as the start of the sequence; 2. Followed by 6 digits; 3. Finally, a check digit, which can be a number (0-9) or a letter (A-Z). Example: A888888(A)
		whatsappAuth			object	false	WhatsApp OTP verification, required when authModes=whatsappAuth
			countryCode		string	false	International country/region code, do not include '+'
			number		string	false	No format validation is performed; the maximum length is limited to 13 characters.
	digitalSignature				boolean	false	Whether to enable digital signatures. Default: false. true - enabled, false - disabled
	tsp				string	false	Select the TSP used by the signer. Default: false. If not set, the signer can freely choose the TSP to use. Enumerations include: vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha
	freeFormSign				boolean	false	Whether the signer has free seal usage rights. Default: false. Additional notes: When freeFormSign is set to true, other parameters under sealInfos do not need to be provided. If both are provided simultaneously, freeFormSign takes precedence over sealInfos, and the parameters under sealInfos will not take effect. [Note]Free seal usage means there are no restrictions on the number or position of seals/signatures that the signer can drag in.
	documentVisibility				object	false	File visibility configuration. Default: all visible.
		documentViewType			string	false	Visibility policy. Default: all. 'all' indicates that all signing documents within the envelope can be viewed, while 'limited' indicates that only one's own signed documents and supplementary visible documents can be viewed.
		viewableFileKeys			array	false	List of additional fileKeys allowed for viewing by the specified signing party; this parameter is only accepted and effective when documentViewType=limited.
	sealInfos				array	false	Signing task information
		fileKey			string	true	Signing file fileKey
		signConfigs			array	false	Control position information. The control's position must be specified to perform an electronic signature.
			fieldType		string	false	Control type, default is signature signature- Signature control stamp- Seal control approval- Approval control
			required		boolean	false	Whether it is required, default is required true- Required false- Not required
			signFieldStyle		string	false	Sealing method for the signing control, default is normalSeal. normalSeal- Normal seal pagingSeal- Perforated seal Only signature controls and seal controls support setting a perforated seal.
			pagingSealMode		string	false	Page range for the perforated seal, default is all. all- All pages assignedPages- Specified pages even- Even pages odd- Odd pages This parameter is supported only when signFieldStyle=pagingSeal.
			sizeRule		string	false	Stamp size display mode originalSize- Apply the stamp based on the actual size of the signature/stamp targetSize- Customize the width and height of the signature/stamp area When sizeRule, height, and width are all empty, apply the stamp based on the actual size of the signature/stamp; When sizeRule is empty but height and width are not empty, apply the stamp with the specified dimensions; When sizeRule is not empty, apply the stamp according to the specified display mode; For paging seals, this parameter does not need to be specified; the stamp is applied solely based on the actual size.
			height		int	false	Height of the signing control. Applicable when fieldType is signature or stamp. Unit: px. Only positive integers are accepted. Default value: auto (i.e., system-determined size); When fieldType=signature, the allowed range is 20-250px; When fieldType=stamp, the allowed range is 30-280px; This parameter does not need to be specified for paging seals.
			width		int	false	Width of the signing control. Applicable when fieldType is signature or stamp. Unit: px. Only positive integers are accepted. Default value: auto (i.e., system-determined size); When fieldType=signature, the range can be set to 20-250px; When fieldType=stamp, the range can be set to 30-280px; The perforation seal does not require this parameter.
			signatureOptions		string	false	Signature control options. Only applicable when fieldType is signature Acceptable parameters: template: Template signature handDrawn: Hand-drawn signature upload: Upload local signature image aiHandDrawn: AI hand-drawn signature Multiple selections allowed, separated by commas; all selected by default
			movable		boolean	false	Allow repositioning during signing, default false false - Signer is not allowed to adjust their own signature control position true - Signer is allowed to adjust their own signature control position
			allowedOptions		array	false	Options allowing signer approval, applicable when fieldType is approval. Default is ["approve", "decline"] approve- Approve decline-Reject
			pageNo		string	false	Signature page numbers; consecutive page numbers are connected with "-", and individual page numbers are connected with "," Example: 1-3,6-10 When pagingSealMode=assignedPages, pass the page range where the cross-page seal is applied. Cross-page seals can only be used for documents with more than one page.
			posX		float	false	X-axis coordinate [Note] If fieldType is signature, the coordinate position refers to the signature areaBottom-left corner； If fieldType is stamp, the coordinate position refers to the stamping areaCenter pointPosition Starting from February 3, 2026, when fieldType is signature or stamp, its coordinate position refers to the center point of the stamping area. For cross-page seals, you can pass 0, but not null. The control is fixed at the right edge of the document.
			posY		float	false	Y-axis coordinate [Note] If fieldType is signature, the coordinate position refers to the signature areaBottom-left corner； If fieldType is 'stamp', the coordinate position refers to the stamp area.Center pointPosition Starting from February 3, 2026, for fieldType 'signature' or 'stamp', the coordinate position refers to the center point of the stamp area.
		fillConfigs			array	false	Fill in control information
			fieldName		string	false	Control name, character limit 128
			required		boolean	false	Whether it is required, default is required true - Required false - Not required
			fieldType		string	false	Control type: 1 - Single-line text 15 - Checkbox
			textField		object	false	Text control attributes
				overflowType	int	false	Only applies to 'text', default is 1 1 - Auto-shrink font size 2-Limit Input
				minFontSize	float	false	Only applies to text, only effective when overflowType=1, default is 8 5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72
				width	int	false	Control width, default is 160px
				font	int	false	Only applies to text, font family, default is SimSun 1-SimSun 2-New SimSun 4-HeiTi 5-KaiTi 6-Arial 7-Helvetica 9-Times New Roman 10-FangSong 11-Georgia 12-Monospace
				fontSize	float	false	Only applies to text, font size, default is 12 5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72
				textColor	string	false	Only applies to text, hexadecimal color, default is black #000
				bold	boolean	false	Only applies to text, whether the font is bold, default is false true-Bold false-Not Bold
				italic	boolean	false	Only applies to text, whether the font is italic, default is false true-italic false-non-italic
				underline	boolean	false	Only applies to text; whether to add an underline, default false true-add underline false-no underline
				lineThrough	boolean	false	Only applies to text; whether to add a strikethrough, default false true-add strikethrough false-no strikethrough
				horizontalAlignment	string	false	Only applies to text; horizontal alignment format, default left LEFT-align left CENTER-center RIGHT-align right
			tickBoxField		object	false	Checkbox properties
				tickOptions	array	false	Only applies to tickBox, default 1 1-checked 2-ary
			posX		float	false	Control position X coordinate
			posY		float	false	Control position Y coordinate
			pageNo		string	false	Page number where the control is located
		signDateConfigs			array	false	Signature date position information
			movable		boolean	false	Allows moving the position during signing; default is false false - Signer is not allowed to adjust their own signature control position true - Signer is allowed to adjust their own signature control position
			pageNo		string	false	Signature page numbers; consecutive pages are connected with "-", and individual pages are separated by ",". Example: 1-3, 6-10; For non-consecutive pages, use "," as the separator.
			posX		float	false	X-axis offset, with the bottom-left corner of the page as the origin
			posY		float	false	Y-axis offset, with the bottom-left corner of the page as the origin
			signDateFormat		string	false	Signature date format; default format is yyyy-MM-dd Supports specified formats: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MMM dd,yyyy dd MMM yyyy

Request Example

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "CCInfos": [
      {
        "userEmail": "cc_user@esignglobal.com",
        "userName": "cc_user_name",
        "ccOrder": 1
      }
    ],
    "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
    "signerInfos": [
      {
        "userEmail": "sender_user@tsign.cn",
        "userName": "sender_user_name",
        "phoneNumber": {
        	"countryCode": "86",
        	"number": "158****9242"
        }
        "signOrder": 1,
        "signTaskSuspend": true,
        "suspensionKey": "approval-node-001",
        "suspendReason": "等待外部审批",
        "authModes": "sms",
        "authConfig": {
            "sms": {
                "countryCode": "86",
                "number": "158****9242"
            }
        },
        "sealInfos": [
        {
            "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
            "signConfigs": [
              {
                "fieldType": "stamp",
                "pageNo": "1,3-5",
                "posX": 100.22222,
                "posY": 100.11111
              }
              "fillConfigs": [
              {
                "fieldId": "df0dd777bc774a2ba3fec4d108de242d",
                "fieldKey": "必填单行文本自动缩小字号最小字号Arial",
                "pageNo": "1",
                "posX": "88.70021",
                "posY": 745.409,
                "fieldType": "1",
                "required": true,
                "textField": {
                    "overflowType": "1",
                    "minFontSize": 8,
                    "font": "6",
                    "fontSize": "12",
                    "textColor": "#54ACD2",
                    "bold": false,
                    "italic": true,
                    "lineThrough": false,
                    "horizontalAlignment": "RIGHT"
                }
              },
              {
                  "fieldId": "888b899853544c49bd819d9f6d1e52cf",
                  "fieldKey": "必填勾选控件不限制选中样式不显示边框",
                  "pageNo": "3",
                  "posX": 451.77127,
                  "posY": 429.07626,
                  "fieldType": "15",
                  "required": true,
                  "tickBoxField": {
                      "tickOptions": [1,2],
                      "showBorder": false
                  }
                }
              ]
            ],
            "signDateConfigs":[
              {
                "pageNo":"1",
                "posX": 100.22,
                "posY": 100,
                "signDateFormat": "dd MMM yyyy"
              }
            ]
        }
      ]
    }
  ]
}

Response Parameters

Parameter Name		Type	Description
envelopeId		string	Envelope ID
CCInfos		array	CC Recipient Information Collection
	userEmail	string	CC Recipient Email Address
	userName	string	CC Recipient Name
signFiles		array	Signed Document Information Collection
	fileKey	string	Signed Document fileKey
attachments		array	Envelope Attachment Collection
	fileKey	string	File fileKey
signerInfos		array	Signing Information
	recipientId	string	Signer ID
	businessId	string	Developer-defined business number, maximum length of 500 characters
	userEmail	string	Signatory's email address
	userName	string	Signatory's name
	signUrl	string	Signing link URL
	signOrder	int	Signatory signing order, minimum value is 1
	accessCode	string	Access password for the signing page

Response example

{
  "code": "0",
    "data": {
    "signerInfos": [
      {
        "accessCode": "123456",
        "userEmail": "sender_user@tsign.cn",
        "signUrl": "http://app-test.esignglobal-inc.com/home/main/sign/start/base/dosign?envelopeId=4cd738a60225445f9d5f3afec468a639&signature=eyJhbGciOiJIUzI1NiIsInppcCI6IkRFRiJ9.eNqqVkrOzytJrShRsqpWSs0rS83JL0gNSSzO9kxRslJKtjC1MDKxTDVIMzA0SU4xSTIwNjAxSDRNTTVKMTIxTFOqrQUAAAD__w.YMBA5X9O8Ylk7x2rma-s1WxGwo2cjqy-O9CCQopzw88&tenantToken=AA0DDgQ0Y2Q3MzhhNjAyMjU0NDVmOWQ1ZjNhZmVjNDY4YTYzuQ4GNGNkNzM4YTYwMjI1NDQ1ZjlkNWYzYWZlYzQ2OGE2M7kOCjRjZDczOGE2MDIyNTQ0NWY5ZDVmM2FmZWM0NjhhNjO5AIBjNDIwMzg1ZDMyYzU0MGE4YTk1ZTE3ZTNkZmZjMDNm4g%3D%3D",
        "userName": "sender_user_name",
        "signOrder": "1"
      }
    ],
      "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
      "envelopeId": "4cd738a60225445f9d5f3afec468a639"
  },
  "message": "success"
}