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 CC recipient information
	userEmail				string	false	CC recipient email address
	userName				string	false	The name of the CC recipient, used to display the name of the CC recipient on the signature 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
	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 for the same signOrder false-All people in 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, when authModes=accessCodeis required.
		sms			object	false	SMS OTP verification, when authModes=smsis required
			countryCode		string	false	International code of the country/region, no need to include “+”
			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- Authenticate with Singpass iamsmart- Authenticate with i AM Smart
			idNumber		string	false	Signer's identity document number to be verified When authApp=singpass, the input rule is: uppercase letter + 7 or 8 digits + uppercase letter When authApp=iamsmart, the input rule is: 1. One uppercase letter (A-Z), or two uppercase letters (AA-ZZ), as the beginning of the sequence; 2. Followed by 6 digits; 3. Finally, a check code, 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 code of the country/region, no need to pass "+"
			number		string	false	No format verification, only limit the maximum length to 13 digits
	digitalSignature				boolean	false	Whether to enable digital signature, default is false true-enable, false-disable
	freeFormSign				boolean	false	Whether the signer can freely sign, default is false Supplementary explanation: 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 and drop
	sealInfos				array	false	Signing task information
		fileKey			string	true	Signing file fileKey
		signConfigs			array	false	Control position information, you must specify the position information of the control before you can perform electronic signature.
			fieldType		string	false	Control type, default is signature signature-Signature control stamp-Seal control approval-Approval control
			sizeRule		string	false	Signing area size display method originalSize-Apply the seal according to the actual size of the signature/seal targetSize-Customize the width and height of the signature/seal area When sizeRule, height, and width are all empty, the signature/seal will be placed according to its actual size; When sizeRule is empty, and height and width are not empty, the signature/seal will be placed according to the specified size; When sizeRule is not empty, the signature/seal will be placed according to the specified display method.
			height		int	false	Signature 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	Signature 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 to fieldType signature Acceptable parameters: template: Template signature handDrawn: Hand-drawn signature upload: Locally uploaded signature image Multiple selections are allowed, separated by ",", default is all selected
			movable		boolean	false	Allow moving the position when signing, default is false false - Signers are not allowed to adjust the position of their own signature controls true - Signers are allowed to adjust the position of their own signature controls
			allowedOptions		array	false	Options for signers to approve, applicable to fieldType 'approval'. Default is ["approve", "decline"] approve- Approve decline- Decline
			pageNo		string	false	Signing page number; consecutive page numbers are connected with "-", 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 stamp areaCenter pointPosition From February 3, 2026, if fieldType is signature or stamp, the coordinate position refers to the center point of the stamp 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, required by default true-Required false-Not required
			fieldType		string	false	Control type: 1-Single line text 15-Check box
			textField		object	false	Text Control Properties
				overflowType	int	false	Only effective for text, default is 1 1-Automatically reduce font size 2-Restrict input
				minFontSize	float	false	Only effective for text, only effective 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 effective for text, font, default is SimSun 1-SimSun 2-NSimSun 4-SimHei 5-KaiTi 6-Arial 7-Helvetica 9-Times New Roman 10-FangSong 11-Georgia 12-Monospace
				fontSize	float	false	Only effective for 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 effective for text, hexadecimal color, default is black #000
				bold	boolean	false	Only effective for text, whether the font is bold, default is false true-Bold false-Not bold
				italic	boolean	false	Only applies to text, whether italic, default false true-Italic false-Not 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 applies to text, horizontal alignment format, default left LEFT-Left aligned CENTER-Center aligned RIGHT-Right aligned
			tickBoxField		object	false	Checkbox Properties
				tickOptions	array	false	Only valid for tickBox, default is 1 1-Tick 2-Cross
			posX		float	false	X coordinate of control position
			posY		float	false	Y coordinate of control position
			pageNo		string	false	Page number where the control is located
		signDateConfigs			array	false	Signature date location information
			movable		boolean	false	Allow moving the position when signing, default is false false - Signers are not allowed to adjust the position of their signature controls true - Signers are allowed to adjust the position of their signature controls
			pageNo		string	false	Signing page number; consecutive page numbers are connected with "-", and individual page numbers are connected with ","，Example: 1-3, 6-10; If non-consecutive, pass "," to separate.
			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, with the bottom left corner of the page as the origin
			signDateFormat		string	false	Signing date format, the default format is yyyy-MM-dd Supports specified 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	Collection of CC recipient information
	userEmail	string	CC recipient email address
	userName	string	CC recipient name
signFiles		array	Collection of signed document information
	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's email address
	userName	string	Signer's name
	signUrl	string	Signing link address
	signOrder	int	Signer's 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"
}