Create and Start Envelope

POST/esignglobal/v1/envelope/createAndStart

Interface Description

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

Start envelope automatically: When the API is called successfully, the envelope is successfully created and opened, and the process starts to proceed automatically.
End envelope automatically: Envelope ends automatically after all signers signed.

Request Parameters

Parameter					Type	Required	Description
subject					string	true	Name of the envelope. e.g. Offer Letter
remark					string	false	Envelope message to all recipients, length limit 1000 words.
expireAfterSeconds					long	false	Envelope expiration time, number of seconds after which the envelope expires. Expiration range: 86,400 seconds (1 day) ~ 7,776,000 seconds (90 days)
redirectUrl					string	false	The page signers will be redirected to after completing signing process. The page url should be a valid HTTP address.
callBackUrl					string	false	The callback address to receive envelope events during the signing proces. Length limit: 500, should be a valid HTTP address.
sendLaterAfterSeconds					long	false	Support delayed sending in seconds Time range supported: 3600 seconds (1 hour) ~ 259200 seconds (30 days)
CCInfos					array	false	CC recipient information
	userEmail				string	false	Email address
	userName				string	false	The name of the CC recipient. [Note]: cannot contain the following 9 special characters: / \ : * " < > \|? And all emoji
signFiles					array	true	The information of the documents that need to be signed. The display order of the documents is the order added.
	fileKey				string	true	Document fileKey
attachments					array	false	Envelope attachment. Attachments will be displayed in the order they were added.
	fileKey				string	false	Attachment fileKey
SignerInfos					array	true	Signer Information
	businessId				string	false	Developer customized business number, length limit 500.
	deliveryMethods				string	false	Delivery methods. Default: auto auto-Delivery via email if `userEmail` is provided, or via SMS if `phoneNumber` is provided none-No notifications email-Email notification sms-SMS notification WhatsApp-WhatsApp notification
	userEmail				string	true	Signer's Email Address
	userName				string	true	Signer's Name [Note]: The following 9 special characters cannot be included: / \ : * " < > \|? and all emoji
	phoneNumber				object	false	Phone Number of Signer It's required when need to notificate signer with SMS.
		countryCode			string	false	The International Code of the country region, without "+"
		number			string	false	Phone number, maximum length: 13
	signOrder				int	true	Signer's sign order, minimum 1. In unordered signing, the same order value can be assigned.
	anySigner				boolean	false	Support signing by any one signer. Default: false true-Only one signatory is required per signOrder. false-All signers in the same signOrder must sign.
	authModes				string	false	Verification method, 0 by default 0-Do not verify 1-Access code 2-iAM Smart 3-SMS OTP 4-ID Verification
	authConfig				object	false	Authentication Method
		accessCode			object	false	Required when authModes = 1
			accessCode		string	false	Access code content, case-insensitive, can contain alphanumeric, length limit 45
		iAMSmart			object	false	Required when authModes = 2
			name		string	false	Full name of the signatory on the Hong Kong identity card, length limit 100 characters
			idCardType		string	false	Type of identity document: HKG_PSN_IDCARD Hong Kong Resident Identity Card
			idCardNum		string	false	ID number. e.g. Hong Kong Identity Card Number: A888888(A)
		sms			object	false	Required when authModes = 3
			countryCode		string	false	The International Code of the country or region, without "+".
			number		string	false	Maximum length: 13
		idVerification			object	false	Required when authModes = 4
			name		string	false	The full name on the signer's identity document, with a maximum length of 100 characters.
	freeFormSign				boolean	false	Whether the signer can freely sign. Default value: false Supplementary note: When freeFormSign is set to true, other parameters under sealInfos are not required. If both freeFormSign and sealInfos are specified, the priority of freeFormSign takes precedence, and the parameters under sealInfos will not take effect. [Note]: Free signature means that the signer has no restrictions on the number and position of stamps/signatures they can sign.
	SealInfos				array	false	Signing Task Information
		fileKey			string	true	Document fileKey
		signConfigs			array	false	Configures of signing
			fieldType		string	false	Field type, default: signature signature-signature field stamp-stamp field
			height		int	false	Signature field height, only applicable to signature field. unit: px default value: 60 range: 20 to 100 only positive integer input is supported
			signatureOptions		string	false	The way to generate a signature. Only applicable when fieldType is signature. template: Template signature handDrawn: Hand-drawn signature upload: Upload signature image from local device Multiple choices can be selected, separated by ",", all selected by default
			movable		boolean	false	Allow position adjustment during signing, default: false false-Signers cannot adjust the position of their own signing fields. true-Signatories can adjust the position of their own signing fields.
			PageNo		string	false	Sign page numbers.Consecutive pages are connected with a '-', and ',' is used for separate pages. e.g., 1-3,6-10
			posX		float	false	X-axis coordinate [Note]: If fieldType is signature, the coordinate position refers to the lower left corner of the signature field; If fieldType is stamp, the coordinate position refers to the center point of the stamp field.
			Posy		float	false	Y-axis coordinate [Note]: If fieldType is signature, the coordinate position refers to the lower left corner of the signature field; If fieldType is stamp, the coordinate position refers to the center point of the stamp field.
		fillConfigs			array	false	Fill in field information
			fieldName		string	false	Field name, character limit 128
			required		boolean	false	Required, default true: true-required false-not required
			fieldsType		string	false	Field Type: 1-Single line of text 15-Tick box
			textField		object	false	Text Filed Properties
				overflowType	int	false	Only effective for text 1-Automatically reduce font size 2-Limit input
				minFontSize	float	false	Only effective for text, only for overflowType, default = 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	Field width, default 160px
				font	int	false	Effective only for text, font, default Song 1-Song 2-New Song 4-Bold 5-Regular 6-Arial 7-Helvetica 9-Times New Roman 10-Faux Song 11-Georgia 12-Monospace
				fontSize	float	false	Only effective for text, 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 effective for text, hexadecimal color
				bold	boolean	false	Only effective for text, whether the font is bold or not true-bold false-not bold
				italic	boolean	false	Only effective for text, italic or not true-italic false-not italic
				underline	boolean	false	Only effective for text, whether the font is underlined. true-underlined false-not underlined
				lineThrough	boolean	false	Only effective for text, whether to add strikethrough true-add strikethrough false-no strikethrough
				horizontalAlignment	string	false	Only effective for text, horizontally centered format LEFT-Align Left CENTER-Align center RIGHT-Align Right
			tickBoxField		object	false	Tick Box Properties
				tickOptions	array	false	Only effective for tick box 1-tick 2-cross
			posX		float	false	X-axis coordinate
			posY		float	false	Y-axis coordinate
			pageNo		string	false	The page number of the field
		signDateConfigs			array	false	Signing date and location information
			movable		boolean	false	Allow position adjustment during signing, default: false false-Signatories cannot adjust the position of their own signing fields. true-Signatories can adjust the position of their own signing fields.
			pageNo		string	false	Sign page numbers.Consecutive pages are connected with a '-', and ',' is used for separate pages. e.g. 1-3, 6-10
			posX		float	false	X-axis coordinate
			posY		float	false	Y-axis coordinate
			signDateFormat		string	false	Date signed format. The default format is yyyy-MM-dd. Support for 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": "3",
        "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"
              }
            ]
        }
      ]
    }
  ]
}

Responses

Parameter		Type	Description
envelopeId		string	Envelope ID
CCInfos		array	CC Person Information
	userEmail	string	CC Email Address
	userName	string	CC Name
signFiles		array	Documents Information
	fileKey	string	Document fileKey
attachments		array	Envelope Attachment
	fileKey	string	Attachment fileKey
SignerInfos		array	Signing Information
	businessId	string	Developer customized business number
	userEmail	string	Email Address of signatory
	userName	string	Name of signatory
	signOrder	int	Sign order of signatory
	accessCode	string	Access code content of signatory

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