Add Signer

Parameter Name

Type

Required

Description

envelopeId

string

true

Envelope ID

signerInfos

array

true

Signer Information Collection

businessId

string

false

Developer-defined business number, length 500

roleTypes

array

false

Signer operation method, default value is ["sign", "fill"]

fill-Fill in

sign-Sign

string

false

userEmail

string

false

Signer's email address

documentVisibility

object

false

File visibility configuration, default is visible to all.

documentViewType

string

false

Visibility policy, default is 'all'; 'all' means all signing documents in the envelope can be viewed, while 'limited' means only your own signed documents and supplementary visible files can be viewed.

viewableFileKeys

array

false

List of fileKeys that the signer is additionally allowed to view; only accepted and effective when documentViewType=limited.

phoneNumber

object

false

Required for SMS notifications; both countryCode and number must be provided, default is empty.

countryCode

string

false

International dialing code for the country/region, do not include '+'

number

string

false

No format validation; maximum length is 13 characters.

customizeSettings

object

false

Custom configuration

notificationSettings

object

false

Notification-specific custom configuration

customizeMessage

string

false

Exclusive 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

userName

string

true

Signatory name, used to display the signatory's name on the signing page and in the process.

[Note] The following 9 special characters are not allowed: / \ : * " < > | ? and all emoji characters.

signOrder

int

true

Signatory signing order, minimum value is 1. For unordered signing, the same order value can be specified.

signTaskSuspend

boolean

false

Whether to set a process blocking node before this signing position. Default is false. true - Set blocking node; false - Do not set blocking node. The blocking configuration within the or-sign group of the same signOrder must be consistent.

suspensionKey

string

false

Blocking node identifier, up to 500 characters, unique within the same envelope. Required when signTaskSuspend=true; must not be passed when signTaskSuspend=false or not provided.

suspendReason

string

false

Blocking reason. Cannot be empty when passed, up to 50 characters. Can only be passed when signTaskSuspend=true; if not passed, it defaults to indicating that waiting for external system processing is required. Must not be passed when signTaskSuspend=false or not provided.

anySigner

boolean

false

Whether to support signing by any one person. Default is false.

true - Only one person needs to sign within the same signOrder

false - All persons within the same signOrder need to sign

authModes

string

false

Identity verification method, default is noAuth

Enum type:

authConfig

object

false

Verification Method Settings

accessCode

object

false

Passphrase settings, required when authModes=accessCode

accessCode

string

false

Passphrase content, case-insensitive, can include alphanumeric characters, maximum length 45

promptInfo

string

false

Access passphrase prompt message, cannot contain the access passphrase, maximum length 30, required when authModes=accessCode.

sms

object

false

SMS OTP verification, required when authModes=sms

countryCode

string

false

International dialing code for country/region, without the '+' symbol

number

string

false

No format validation, maximum length 13 digits

idVerification

object

false

ID document verification settings, required when authModes=idVerification

name

string

false

Full name as it appears on the signer's ID document, maximum length 100 characters

emailAuth

object

false

Email OTP verification, required when authModes=emailAuth

authEmail

string

false

Signer identity verification email address

digitalId

array

false

Electronic identity authentication, required when authModes=digitalId

authApp

string

false

APP used for electronic identity authentication

singpass- Use Singpass for identity authentication

iamsmart- Use MyInfo for identity authentication

idNumber

string

false

ID document number of the signer to be verified

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 beginning of the sequence;

2. Followed by 6 digits;

3. Finally, a check digit, 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, no need to include '+'

number

string

false

No format validation is performed; the maximum length is limited to 13 characters.

digitalSignature

boolean

false

Whether to enable digital signature, default false

true- Enabled

false- Disabled

tsp

string

false

Select the TSP used by the signer, default false.

If not set, the signer can freely choose the TSP to use. Enumerations include:

vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni

belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia

estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom

harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId

mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign

smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe

certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha

freeFormSign

boolean

false

Whether the signer has free seal placement, default value false

Additional notes:

When freeFormSign is set to true, other parameters under sealInfos do not need to be provided. If both are provided simultaneously, freeFormSign takes precedence over sealInfos, and the parameters under sealInfos will not take effect.

[Note] Free seal placement 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

File key of the signed document

signConfigs

array

false

Control position information. The control's position must be specified to perform electronic signing.

fieldType

string

false

Control type, acceptable values:

signature- Signature control

stamp-Seal Control

Defaults to signature

Whether it is required, defaults to required

true-Required

false-Not Required

signFieldStyle

string

false

The method for placing the seal on the signing control, defaults to normalSeal.

normalSeal-Normal Seal

pagingSeal-Cross-page Seal

Only Signature Control and Seal Control support setting a cross-page seal.

pagingSealMode

string

false

The page range for placing the cross-page seal, defaults to all.

all-All Pages

assignedPages-Specified Pages

even-Even Pages

odd-Odd Pages

This parameter is supported only when signFieldStyle=pagingSeal.

sizeRule

string

false

Signature area size display mode

originalSize- Place 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, place the seal according to the actual size of the signature/seal;

When sizeRule is empty but height and width are not empty, place the seal according to the specified dimensions;

When sizeRule is not empty, place the seal according to the specified display mode;

For paging seals, this parameter does not need to be specified; the seal is placed solely based on its actual size.

height

int

false

Height of the signing control. Applicable when fieldType is signature/stamp, in pixels (px). Only positive integers are accepted. Default is auto (i.e., system-determined size);

When fieldType=signature, the allowed range is 20-250px;

When fieldType=stamp, the allowed range is 30-280px;

This parameter does not need to be specified for paging seals.

width

int

false

Width of the signing control. Applicable when fieldType is signature/stamp, in pixels (px). Only positive integers are accepted. Default is auto (i.e., system-determined size);

When fieldType=signature, the allowed range is 20-250px;

When fieldType=stamp, the allowed range is 30-280px;

The cross-page seal does not require specifying this parameter.

signatureOptions

string

false

Signature control options. Only applicable when fieldType is signature.

Acceptable parameters:

template

handDrawn

upload

aiHandDrawn

Multiple selections allowed, separated by commas; all selected by default

movable

boolean

false

Allows repositioning during 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 allowing signers to approve, applicable when fieldType is approval. Default is ["approve", "decline"]

approve- Approve

decline- Decline

pageNo

string

false

Page numbers for signing; consecutive pages connected with '-', individual pages separated by ',', e.g., 1-3, 6-10

When pagingSealMode=assignedPages, specify the page range where the cross-page seal will be applied. Cross-page seals can only be used for documents with more than one page.

posX

string

false

X-axis coordinate

Additional notes:

If fieldType is signature, the coordinate refers to the signature areaBottom-left corner；

If fieldType is stamp, the coordinate position refers to the center of the stamp area.Center pointPosition

Starting from February 3, 2026, if fieldType is signature or stamp, its coordinate position refers to the center of the stamp area.

For a cross-page seal, pass 0; null is not allowed. The control is fixed at the right edge of the document.

posY

string

false

Y-axis coordinate

Additional notes:

If fieldType is signature, the coordinate position refers to the center of the signature area.Bottom-left corner；

If fieldType is stamp, the coordinate position refers to the center of the stamp area.Center pointPosition

Starting from February 3, 2026, if fieldType is signature or stamp, its coordinate position refers to the center of the stamp area.

fillConfigs

array

false

Fill in control information

fieldName

string

false

Control name, character limit of 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 attributes

overflowType

int

false

Only effective for text, default is 1

1 - Auto-shrink font size

2 - Limit input

minFontSize

float

false

Only effective for text, only effective 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 effective for text, font, default is SimSun.

1 - SimSun

2-New Songti

4-Heiti

5-Kaiti

6-Arial

7-Helvetica

9-Times New Roman

10-Fangsong

11-Georgia

12-Monospace

fontSize

float

false

Applies only 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

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 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-No underline

lineThrough

boolean

false

Applies only to text. Whether to add strikethrough. Default is false.

true - Add strikethrough

false - Do not add strikethrough

horizontalAlignment

string

false

Applies only to text. Horizontal alignment format. Default is left.

LEFT - Align left

CENTER - Center

RIGHT - Align right

tickBoxField

object

false

Checkbox properties

tickOptions

array

false

Applies only to Check. Default is 1.

1 - Checkmark

2 - Cross

posX

float

false

Control position X coordinate

posY

float

false

Control position Y coordinate

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

pageNo

string

false

Signature page numbers; consecutive pages are connected with "-", and individual pages are separated by ",". Example: 1-3, 6-10

For non-consecutive pages, use "," as the delimiter

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; the default format is yyyy-MM-dd

Supported formats:

yyyy年MM月dd日

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy