Add Signers

POST/esignglobal/v1/envelope/recipients/addSigners

Interface Description

Add signatories to an existed envelope.

Warning:

Support adding new signers after the envelope is started.The signing order of the newly added signer must be greater than the signing order of any signer currently in progress.
The same signer (identified uniquely by email) cannot be added multiple times. To update signing information, developers should re-add the corresponding signer.
An envelope can have a maximum of 10 signers.

Request Parameters

Parameter					Type	Required	Description
envelopeId					string	true	Envelope ID
SignerInfos					array	true	Sign Information
	businessId				string	false	Developer customized business number, length limit 500
	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	Signer's Phone Number 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 signer is required per signOrder. false-All signers in the same signOrder must sign.
	authModes				string	false	Verification method, noAuth by default noAuth-Do not verify accessCode-Access code sms-SMS OTP idVerification-ID Verification emailAuth-Email OTP
	authConfig				object	false	Authentication Method
		accessCode			object	false	Required when authModes = accessCode
			accessCode		string	false	Access code content, case-insensitive, can contain alphanumeric, length limit 45.
			promptInfo		string	false	Access code prompt information, must not contain the access code, length limit 30.
		sms			object	false	Required when authModes = sms
			countryCode		string	false	The International Code of the country or region, without "+".
			number		string	false	Maximum length: 13
		idVerification			object	false	Required when authModes = idVerification
			name		string	false	The full name on the signer's identity document, with a maximum length of 100 characters.
		emailAuth			object	false	Required when authModes = emailAuth
			authEmail		string	false	Signatory's authentication email.
	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 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 approval-approval field
			sizeRule		string	false	Sign configs display method originalSize-Original size of stamp/signature image targetSize-Customized target size When sizeRule, height, and width are all empty, the signature/seal is rendered at its original size. When sizeRule is empty but height or width is provided, it is rendered at the specified dimensions. When sizeRule is provided, it is rendered according to the specified display rule.
			height		int	false	Signature or stamp field height. unit: px When fieldType is signature, the height can be set within the range of 20–250 px. When fieldType is stamp, the height can be set within the range of 30–280 px.
			width		int	false	Signature or stamp field width. unit: px When fieldType is signature, the width can be set within the range of 20–250 px. When fieldType is stamp, the width can be set within the range of 30–280 px.
			signatureOptions		string	false	The way to generate a signature. Only applicable when fieldType is signature. template handDrawn upload 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-signers can adjust the position of their own signing fields.
			allowedOptions		array	false	The options available for the signer's approval. Applicable when fieldType is approval. Defaults to ["approve", "decline"]. approve - Approve decline - Decline
			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		string	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		string	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
			fieldType		string	false	Field Type: 1-Text 15-Check
			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	Check Properties
				tickOptions	array	false	Only effective for Check 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-Signers cannot adjust the position of their own signing fields. true-Signers 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

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "authModes": "sms",
            "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "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": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "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		Type	Description
envelopeId		string	Envelope ID
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": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [

        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}