Quick Envelope Initiation

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 is successful, the envelope is created and activated successfully, at which point the envelope automatically begins to flow.
Supports automatic completion: Once all signers have completed their signatures, the envelope is automatically closed.

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 the envelope to another person for signing. Default is false. true - Allows signers in the envelope to have the authority to transfer the envelope to others; false - Does not allow signers in the envelope to have the authority to transfer the envelope to others;
	allowModifyName				boolean	false	Whether to allow signatories to modify their names. This only applies to template signatures. Default is false. true - Allows signers to modify their names false - Does not allow signers to modify their names
expireAfterSeconds					long	false	Envelope expiration time. The envelope will expire after a specified number of seconds. Expiration range: 86,400 seconds (1 day) to 7,776,000 seconds (90 days)
redirectUrl					string	false	Must be a valid HTTPS address
callBackUrl					string	false	Callback URL (maximum length 500 characters). Must conform to the HTTPS protocol.
sendLaterAfterSeconds					long	false	Supports delayed sending by users, measured in seconds Supported time range: 3,600 seconds (1 hour) to 259,200 seconds (30 days)
autoFinish					boolean	false	Controls whether the envelope automatically ends. Default is true. true- Envelope automatically ends false- Envelope manually ends
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: / \ : * " < > \| ? or any emoji
	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 signed document information, displayed in the order documents were added.
	fileKey				string	true	Signed document fileKey, only PDF format is supported
	documentFields				array	false	List of control dimensions. 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 other controls' coordinate ranges.
		posY			float	false	Y-axis offset, with the bottom-left corner of the page as the coordinate origin. The coordinate range is consistent with other controls' coordinate ranges.
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, length limit 500
	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 passed, send email notification; when phoneNumber is passed, send SMS notification none-Do not send message notifications email-Send email notification sms-Send SMS notification WhatsApp-Send WhatsApp notification
	userEmail				string	false	Signer email address
	userName				string	true	Signer name, used to display the signer's name on the signing page and externally for the envelope. [Note] Must not contain the following 9 special characters: / \ : * " < > \| ? and all emoji
	minimumReadingDuration				int	false	Set the forced reading countdown time on the settings page. The default value is 0 (unit: seconds, maximum value: 999) 0 or omitting this parameter indicates that the feature is disabled; no reading countdown will be used
	readToEndRequired				boolean	false	Indicates whether users must 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 notification is needed; both countryCode and number must be provided
		countryCode			string	false	International country/region code; do not include the '+' sign
		number			string	false	No format validation; length is limited to a maximum of 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	The signing order of the signers, with a minimum value of 1. Unordered signatures can be assigned the same order value.
	anySigner				boolean	false	Whether to allow any person to sign, default is false true- Only one person needs to sign for the same signOrder false- All persons need to sign for the same signOrder
	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	Signing password settings, required when authModes=accessCode
			accessCode		string	false	Password content, case-insensitive, can contain letters and numbers, length limit 45
			promptInfo		string	false	Access password prompt message, must not contain the access password, length limit 30, required when authModes=accessCode.
		sms			object	false	SMS OTP verification, required when authModes=sms
			countryCode		string	false	International dialing code for country/region, do not include '+'
			number		string	false	No format validation; only maximum length of 13 characters is enforced
		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'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 iamsmart-Use i AM Smart for identity authentication
			idNumber		string	false	ID number of the signer pending verification 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 code, which can be a digit (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; only limits the maximum length to 13 characters
	digitalSignature				boolean	false	Whether to enable digital signature, default false true - enabled, false - disabled
	freeFormSign				boolean	false	Whether the signer uses free-form stamping, default value false Supplementary Notes: When freeFormSign is set to true, other parameters under sealInfos do not need to be provided. If both are provided, freeFormSign takes precedence over sealInfos, and the parameters under sealInfos will not take effect. [Note]Free-form signing means there are no restrictions on the number or position of seals/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 to perform electronic signatures.
			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	Signing control placement method, default is normalSeal. normalSeal- Standard Seal pagingSeal- Paging Seal Only signature controls and seal controls support the setting of a paging seal.
			pagingSealMode		string	false	The page range for applying the paging seal, default is all. all- All Pages assignedPages- Specified Pages even- Even Pages odd- Odd Pages Specifying is supported only when signFieldStyle=pagingSeal.
			sizeRule		string	false	Display method for signing area dimensions originalSize- Apply seal according to actual size of signature/seal targetSize- Custom width and height for signature/seal area When sizeRule, height, and width are all empty, apply the seal according to the actual size of the signature/seal; When sizeRule is empty but height and width are not empty, apply the seal according to the specified dimensions; When sizeRule is not empty, apply the seal according to the specified display method; The cross-page seal does not require this parameter; it is applied based on the actual size.
			height		int	false	Height of the signing control, applicable when fieldType is signature/stamp, in pixels (px). Only positive integers are supported. The default is auto (i.e., system-determined size); When fieldType=signature, the configurable range is 20-250px; When fieldType=stamp, the configurable range is 30-280px; The cross-page seal does not require this parameter.
			width		int	false	Width of the signing control, applicable when fieldType is signature/stamp, in pixels (px). Only positive integers are supported. The default is auto (i.e., system-determined size); When fieldType=signature, the configurable range is 20-250px; When fieldType=stamp, the configurable range is 30-280px; The cross-page seal does not require this parameter.
			signatureOptions		string	false	Signature control options. Only applicable when fieldType is signature Acceptable values: template: Template signature handDrawn: Hand-drawn signature upload: Upload local signature image Multiple selections are allowed, separated by commas. All options are selected by default.
			movable		boolean	false	Allows moving the position upon signing; default is 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 allowing the signer to approve, applicable when fieldType is approval. Default is ["approve", "decline"] approve- Agree decline- Decline
			pageNo		string	false	Page numbers for signing; consecutive pages are connected with "-", and individual pages are connected with "," Example: 1-3,6-10 When pagingSealMode=assignedPages, specify the page range where the cross-page seal will be placed. 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 refers to the signature areaBottom-left corner； If fieldType is stamp, the coordinate refers to the stamp areaCenter pointPosition Starting from February 3, 2026, for fieldType signature or stamp, the coordinate position refers to the center point of the stamp area. For overlapping seals, pass 0; null is not allowed. 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 areaCenter 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 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 applies to text, default is 1 1-Automatically shrink font size 2-Limit input
				minFontSize	float	false	Only applies to text, only applies 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, 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	Applies only to text, hexadecimal color, default black #000
				bold	boolean	false	Applies only to text, whether the font is bold, default false true - Bold false - Not bold
				italic	boolean	false	Applies only to text, whether the font is italic, default false true - Italic false - Not italic
				underline	boolean	false	Applies only to text, whether the font has an underline, default false true - Add underline false - Do not add underline
				lineThrough	boolean	false	Applies only to text, whether the font has a strikethrough, default false true - Add strikethrough false - Do not add strikethrough
				horizontalAlignment	string	false	Applies only to text, horizontal alignment format, default left LEFT - Align left CENTER-Center RIGHT-Right Align
			tickBoxField		object	false	Checkbox Properties
				tickOptions	array	false	Only applies to tickBox, default is 1 1-Checkmark 2-Cross
			posX		float	false	Control X-coordinate position
			posY		float	false	Control Y-coordinate position
			pageNo		string	false	Page number where the control is located
		signDateConfigs			array	false	Signature date position information
			movable		boolean	false	Allows repositioning during signing, default is false false-Signer cannot adjust their signature control position true-Signer can adjust their signature control position
			pageNo		string	false	Signature page numbers; use "-" for consecutive pages and "," for separate pages. 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 Supported 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",
    "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	Document fileKey
signerInfos		array	Signing information
	recipientId	string	Signer ID
	businessId	string	Developer-defined business number, length limit 500
	userEmail	string	Signer email address
	userName	string	Signer name
	signUrl	string	Signing link URL
	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"
}