Quickly Initiate Envelope

POST /esignglobal/v1/envelope/createAndStart

Interface Description

Quickly initiate envelopes, including creating envelopes, adding documents to be signed, and adding signers.

Support auto-start: After the interface is successfully called, the envelope is successfully created and started, and the envelope automatically starts circulating.
Support auto-completion: The envelope automatically completes after all signing parties have completed signing.

Request Parameters

Parameter Name					Type	Required	Description
subject					string	true	Envelope Subject Example: “Offer Letter”
remark					string	false	Envelope Remarks，Length limit of 1000 characters
signerSettings					object	false	Operations allowed for the signer
	allowTransfer				boolean	false	Whether the signer is allowed to forward the envelope to another person for signing, default is false true - Allows the signer in the envelope to have the power to forward the envelope to others; false - Does not allow the signer in the envelope to have the power to forward the envelope to others;
	allowModifyName				boolean	false	Whether the signer is allowed to modify the name, only valid for template signatures, default is false true - Allows the signer to modify the name false - Does not allow the signer to modify the name
expireAfterSeconds					long	false	Envelope expiration time, after how many seconds the envelope expires 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 address (length 500), must conform to the https protocol address.
sendLaterAfterSeconds					long	false	Supports users to delay sending, in seconds Supported time range: 3600 seconds (1 hour) ~ 259200 seconds (30 days)
CCInfos					array	false	Collection of copy recipient information
	userEmail				string	false	Email address of the copy recipient
	userName				string	false	The name of the CC, used to display the name of the CC on the signing page and envelope. 【Note】: Cannot contain the following 9 special characters: / \ : * " < > \| ? and all emoji expressions
	customizeSettings				object	false	Custom configuration
		notificationSettings			object	false	Notification type custom configuration
			notificationLanguage		string	false	Notification language, defaults to the “Default notification language” configuration 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 signed document information, displayed in the order the documents were added.
	fileKey				string	true	Signing document fileKey, only PDF format is supported
attachments					array	false	Envelope attachment collection, displayed in the order the files were added.
	fileKey				string	false	File fileKey
signerInfos					array	true	Collection of signer information
	businessId				string	false	Developer-defined business number, length limit 500
	deliveryMethods				string	false	Notification method, default is auto auto- Send email notification when userEmail is passed in, and send SMS notification when phoneNumber is passed in 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's name, used to display the signer's name on the signing page and in the envelope. [Note] Cannot contain the following 9 special characters: / \ : * " < > \| ? and all emoji expressions
	phoneNumber				object	false	Phone number, default is empty Required when SMS notifications are needed, both countryCode and number must be passed in
		countryCode			string	false	International code of the country/region, no need to include “+”
		number			string	false	No format verification, only limits the maximum length to 13 digits
	customizeSettings				object	false	Custom configuration
		notificationSettings			object	false	Notification-related custom configuration
			customizeMessage		string	false	Exclusive message notification, character limit 200
			notificationLanguage		string	false	Notification language, defaults to the “Default notification language” configuration 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	The signing order of the signer, the minimum is 1. Unordered signatures can specify the same order value.
	anySigner				boolean	false	Whether to support any one person to sign, default is false true-Only one person needs to sign with the same signOrder false-All people with the same signOrder need to sign
	authModes				string	false	Verification method, the default is noAuth noAuth-No verification accessCode-Verify with 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	Signing password settings, when authModes=accessCodeis required
			accessCode		string	false	Password content, case-insensitive, can contain alphanumeric characters, length limit 45
			promptInfo		string	false	Access password prompt information, cannot contain the access password, length limit 30, required when authModes=1.
		sms			object	false	SMS OTP verification, when authModes=smsis required
			countryCode		string	false	International code of the country/region, no need to pass in “+”
			number		string	false	No format verification, only the maximum length is limited to 13 digits
		idVerification			object	false	ID document verification settings, when authModes=idVerificationis required
			name		string	false	Full name on the signer's ID document, maximum length 100 characters
		emailAuth			object	false	Email OTP verification, when authModes=emailAuthis required
			authEmail		string	false	Signer's 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
			idNumber		string	false	Signer's ID card number to be verified
		whatsappAuth			object	false	WhatsApp OTP verification, required when authModes=whatsappAuth
			countryCode		string	false	International code of the country/region, no need to pass "+"
			number		string	false	No format verification, only the maximum length is limited to 13 digits
	digitalSignature				boolean	false	Whether to enable digital signature, default is false true-enable, false-disable
	freeFormSign				boolean	false	Whether the signer has free signing, the default value is false Additional notes: When freeFormSign is selected as true, there is no need to pass in other parameters under sealInfos. If they are passed in at the same time, freeFormSign has a higher priority than sealInfos, and the parameters under sealInfos will not take effect [Note]Free signing means there is no limit to the number and position of stamps/signatures that the signer can drag in
	sealInfos				array	false	Signing task information
		fileKey			string	true	Signing file fileKey
		signConfigs			array	false	Control position information. The position information of the control must be specified before an electronic signature can be performed.
			fieldType		string	false	Control type, default is signature signature-Signature control stamp-Stamp control approval-Approval control
			sizeRule		string	false	Display method of signing area size originalSize-Place stamp according to 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, the stamp is placed according to the actual size of the signature/stamp; When sizeRule is empty, and height and width are not empty, the stamp is placed according to the specified size; When sizeRule is not empty, the stamp is placed according to the specified display method.
			height		int	false	Signing control height, applicable to fieldType signature/stamp, unit is px, only positive integers are supported, default is auto (i.e., system automatic size); When fieldType=signature, the settable range is 20-250px; When fieldType=stamp, the settable range is 30-280px;
			width		int	false	Signing control width, applicable to fieldType signature/stamp, unit is px, only positive integers are supported, default is auto (i.e., system automatic size); When fieldType=signature, the settable range is 20-250px; When fieldType=stamp, the settable range is 30-280px;
			signatureOptions		string	false	Signature control options. Only applicable when fieldType is signature Acceptable parameters: template: Template signature handDrawn: Hand-drawn signature upload: Locally uploaded signature image Multiple selections are allowed, separated by ",", defaults to all selected
			movable		boolean	false	Allow moving the position during signing, defaults to false false - The signer is not allowed to adjust the position of their own signature control true - The signer is allowed to adjust the position of their own signature control
			allowedOptions		array	false	Options allowed for the signer to approve, applicable when fieldType is approval. Defaults to ["approve", "decline"] approve- Approve decline- Decline
			pageNo		string	false	Signing page number; consecutive page numbers are connected with "-", and individual page numbers are connected with "," Example: 1-3,6-10
			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 From February 3, 2026, if fieldType is signature or stamp, the coordinate position refers to the center point of the stamping area.
			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 stamping areaCenter pointPosition From February 3, 2026, if fieldType is signature or stamp, the coordinate position refers to the center point of the stamping 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 properties
				overflowType	int	false	Only valid for text, default is 1 1-Automatically reduce font size 2-Limit input
				minFontSize	float	false	Only valid for text, only valid for 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 valid for text, font, default is SimSun 1-SimSun 2-NSimSun 4-Black 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 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 black #000
				bold	boolean	false	Only applies to text, whether the font is bold, default false true-Bold false-Not bold
				italic	boolean	false	Only applies to text, whether italic, default false true-Italic false-Non-italic
				underline	boolean	false	Only applies to text, whether to add underline to the font, default false true-Add underline false-Do not add underline
				lineThrough	boolean	false	Only applies to text, whether to add strikethrough, default false true-Add strikethrough false-Do not add strikethrough
				horizontalAlignment	string	false	Only effective for text, horizontal centering format, default left LEFT-Left aligned CENTER-Centered RIGHT-Right aligned
			tickBoxField		object	false	Checkbox properties
				tickOptions	array	false	Only effective for tickBox, default 1 1-Check 2-Cross
			posX		float	false	Control position X coordinate
			posY		float	false	Control position Y coordinate
			pageNo		string	false	Page number of the control
		signDateConfigs			array	false	Signing date position information
			movable		boolean	false	Allow moving the position when signing, default false false - Signers are not allowed to adjust the position of their own signing controls true - Signers are allowed to adjust the position of their own signing controls
			pageNo		string	false	Signing page numbers; consecutive page numbers are connected with "-", and individual page numbers are connected with ","，Example: 1-3, 6-10; If non-consecutive, pass "," for separation.
			posX		float	false	x-axis offset, the lower left corner of the page is the origin of the coordinates
			posY		float	false	y-axis offset, the lower left corner of the page is the origin of the coordinates
			signDateFormat		string	false	Signing date format, the default format is yyyy-MM-dd Supports specifying formats: yyyy年MM月dd日 yyyy-MM-dd yyyy/MM/dd dd.MM.yyyy MM dd yyyy dd MM yyyy

Request Example

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "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,
        "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
	businessId	string	Developer-defined business number, length limit 500
	userEmail	string	Signer email address
	userName	string	Signer name
	signUrl	string	Signing link address
	signOrder	int	Signer signing order, minimum is 1
	accessCode	string	Signing page access password

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"
}