This case guides you through the structure of a configuration. Generally the following steps are necessary to test the configuration:

Upload a file
Create configuration
Send an envelope

Please also see the next figure for an overview of the envelope structure:

For a basic guide of REST and the different API calls please also have a look at our Postman tutorial.

1 Upload a file
2 Configuration
- 2.1 Starting configuration
- 2.2 Envelope configuration
  - 2.2.1 Unassigned elements
  - 2.2.2 Attachments
    - 2.2.2.1 Attachments
  - 2.2.3 Link configuration
    - 2.2.3.1 Link configuration
  - 2.2.4 Reading confirmation
    - 2.2.4.1 Area read confirmation
      - 2.2.4.1.1 Area read confirmation
    - 2.2.4.2 Page read confirmation
      - 2.2.4.2.1 Page read confirmation
    - 2.2.4.3 Document read confirmation
      - 2.2.4.3.1 Document read confirmation
- 2.3 Activities
  - 2.3.1 Action
    - - 2.3.1.1.1 Visibility option
    - 2.3.1.2 Automatic signing
    - 2.3.1.3 Document viewing
    - 2.3.1.4 P7M signing
    - 2.3.1.5 Signing
      - 2.3.1.5.1 Recipient configuration
      - 2.3.1.5.2 Recipient configuration
      - 2.3.1.5.3 Personal message
      - 2.3.1.5.4 Personal message
      - 2.3.1.5.5 Authentication
      - 2.3.1.5.6 Authentication
      - 2.3.1.5.7 Access code
      - 2.3.1.5.8 SMS-OTP
      - 2.3.1.5.9 Swedish Bank Id
      - 2.3.1.5.10 OAuth2
      - 2.3.1.5.11 SAML
      - 2.3.1.5.12 Additional recipient configuration
  - 2.3.2 Elements
    - 2.3.2.1 PDF Forms
      - 2.3.2.1.1 Textbox
      - 2.3.2.1.2 Textbox
      - 2.3.2.1.3 Checkbox
      - 2.3.2.1.4 Checkbox
      - 2.3.2.1.5 Combobox
      - 2.3.2.1.6 Combobox
      - 2.3.2.1.7 Radio button
      - 2.3.2.1.8 Radio button
      - 2.3.2.1.9 Listbox
      - 2.3.2.1.10 Listbox
    - 2.3.2.2 Signatures
      - 2.3.2.2.1 Signature information
      - 2.3.2.2.2 TaskConfiguration
      - 2.3.2.2.3 TaskConfiguration
      - 2.3.2.2.4 Field definition
      - 2.3.2.2.5 ClickToSign
      - 2.3.2.2.6 ClickToSign
      - 2.3.2.2.7 DrawToSign
      - 2.3.2.2.8 DrawToSign
      - 2.3.2.2.9 TypeToSign
      - 2.3.2.2.10 TypeToSign
      - 2.3.2.2.11 LocalCertificate
      - 2.3.2.2.12 LocalCertificate
      - 2.3.2.2.13 DisposableCertificate
      - 2.3.2.2.14 DisposableCertificate
      - 2.3.2.2.15 DisposableCertificate
      - 2.3.2.2.16 DisposableCertificate (Long-Lived)
      - 2.3.2.2.17 DisposableCertificate (Long-Lived)
      - 2.3.2.2.18 SwissComOnDemand
      - 2.3.2.2.19 SwissComOnDemand
      - 2.3.2.2.20 ATrustCertificate
      - 2.3.2.2.21 ATrustCertificate
      - 2.3.2.2.22 Biometric
      - 2.3.2.2.23 Biometric
      - 2.3.2.2.24 RemoteCertificate
      - 2.3.2.2.25 RemoteCertificate
      - 2.3.2.2.26 OneTimePassword
      - 2.3.2.2.27 OneTimePassword
      - 2.3.2.2.28 SwedishBankId
      - 2.3.2.2.29 SwedishBankId
      - 2.3.2.2.30 SignaturePlugins
      - 2.3.2.2.31 SignaturePlugins
    - 2.3.2.3 Predefined Field Elements
      - 2.3.2.3.1 Textfields
      - 2.3.2.3.2 Textfields
      - 2.3.2.3.3 EmailFields
      - 2.3.2.3.4 EmailFields
      - 2.3.2.3.5 InitialsFields
      - 2.3.2.3.6 InitialsFields
      - 2.3.2.3.7 GivenNameFields
      - 2.3.2.3.8 GivenNameFields
      - 2.3.2.3.9 SurnameFields
      - 2.3.2.3.10 SurnameFields
      - 2.3.2.3.11 FullNameFields
      - 2.3.2.3.12 FullNameFields
      - 2.3.2.3.13 DataFields
      - 2.3.2.3.14 DataFields
    - 2.3.2.4 FinishActionConfiguration
      - 2.3.2.4.1 Finish action configuration
  - 2.3.3 Additional envelope information
    - 2.3.3.1 Email configuration
      - 2.3.3.1.1 Email configuration
    - 2.3.3.2 Reminder configuration
      - 2.3.3.2.1 Reminder configuration
    - 2.3.3.3 Expiration configuration
      - 2.3.3.3.1 Expiration configuration
    - 2.3.3.4 Callback configuration
      - 2.3.3.4.1 Callback configuration
    - 2.3.3.5 Agreement configuration
      - 2.3.3.5.1 Agreement configuration
  - 2.3.4 Sending envelope

Upload a file

You can upload a file with the following URL:

https://demo.esignanywhere.net/Api/v6/file/upload

The result of the API call is the FileId which will be needed for the sending call.

Configuration

Please note that with api v6 the general policies are set as default:

   {
                    AllowAdhocFreeHandAnnotations = false,
                    AllowAdhocPdfAttachments = false,
                    AllowAdhocPdfPageAppending = false,
                    AllowAdhocPictureAnnotations = false,
                    AllowAdhocSignatures = false,
                    AllowAdhocStampings = false,
                    AllowAdhocTypewriterAnnotations = false,
                    AllowEmailDocument = true,
                    AllowPrintDocument = true,
                    AllowRejectWorkstep = true,
                    AllowSaveAuditTrail = true,
                    AllowSaveDocument = true,
                    AllowUndoLastAction = false,
                    AllowRotatingPages = false,
                    AllowAppendFileToWorkstep = false,
                    AllowAppendTasksToWorkstep = false,
                    AllowColorizePdfForms = false,
                    AllowReloadOfFinishedWorkstep = true,
                    AllowDownloadOfSignedP7MFiles = true
                };
            }

Via UI it is possible to change the following policies (settings can be found in organization settings → Policy for the document viewer for recipients):

<GeneralPolicies>
  <AllowSaveDocument>1</AllowSaveDocument>
  <AllowSaveAuditTrail>1</AllowSaveAuditTrail>
  <AllowUndoLastAction>1</AllowUndoLastAction>
  <AllowAdhocPdfAttachments>0</AllowAdhocPdfAttachments>
</GeneralPolicies>

The configuration is the core of the envelope. Within the configuration you can define following settings:

Envelope configuration
- Name
- Meta data
- Document time stamp etc.
Unassigned elements
- Textboxes
- Radio buttons
- signatures etc.
Activities
- Action
  - Sign
    - Recipient configuration
      - Authentication configuration
  - View
    - Recipient configuration
      - Authentication configuration
  - Sign automatic etc.
  - SignAsP7M
- Visibility options
Email configuration
Reminder configuration
Expiration configuration
Callback configuration
Agreement configuration

Starting configuration

Lets start with a nearly empty configuration first. Then fill it step by step with the settings above. In the next collapse you can find the sample configuration which includes one action (ClickToSign):

{
    "Documents": [{
            "FileId": "c5a229ae-1234-1234-b6e8-d4eb9fd7bcf5",
            "DocumentNumber": 1
        }
    ],
    "Name": "Test",
    "Activities": [{
            "Action": {
                "Sign": {
                    "RecipientConfiguration": {
                        "ContactInformation": {
                            "Email": "janedoe@sample.com",
                            "GivenName": "Jane",
                            "Surname": "Doe",
                            "LanguageCode": "EN"
                        }
                    },
                    "Elements": {
                        "Signatures": [{
                                "TaskConfiguration": {
                                    "OrderDefinition": {
                                        "OrderIndex": 0
                                    }
                                },
                                "ElementId": "sample sig clicktosign",
                                "Required": true,
                                "DocumentNumber": 1,
                                "DisplayName": "Sign here",
                                "AllowedSignatureTypes": {
                                    "ClickToSign": {
                                    }
                                },
                                "FieldDefinition": {
                                    "Position": {
                                        "PageNumber": 1,
                                        "X": 100,
                                        "Y": 200
                                    },
                                    "Size": {
                                        "Width": 100,
                                        "Height": 70
                                    }
                                }
                            }
                        ]
                    },
                    "SigningGroup": "firstSigner"
                }
            }
        }
    ]
}

The next screenshot shows the document after sending the configuration:

With this configuration we can now add the settings which are mentioned above. First, lets start with the envelope configuration.

Envelope configuration

You can place the general policies directly below the following row:

  "Name": "string",
  "MetaData": "string",
  "AddDocumentTimestamp": true,
  "ShareWithTeam": true,
  "LockFormFieldsOnFinish": true,

Unassigned elements

This section contains all elements which were not assigned to a specific recipient. This results for example from adding so called sig-string to the document. For example, the SIGNificant Server Platform, analyzes PDF documents and searches for so-called 'sig-strings'. When found, a signature field is inserted exactly on this position of the document.

Such elements could be:

PDF form fields
- Textboxes, Checkboxes, Comoboxes, Radio buttons, Listboxes
Signatures
Predefined field elements

Attachments

"Attachments": [
      {
        "ElementId": "string",
        "DocumentNumber": 0,
        "Required": true,
        "FileName": "string",
        "DisplayIconType": "Paperclip",
        "FieldDefinition": {
          "Position": {
            "PageNumber": 0,
            "X": 0,
            "Y": 0
          },
          "Size": {
            "Width": 0,
            "Height": 0
          }
        },
        "TaskConfiguration": {
          "OrderDefinition": {
            "OrderIndex": 0
          }
        }
      }
    ],

Link configuration

"LinkConfiguration": {
      "HyperLinks": [
        {
          "ElementId": "string",
          "Uri": "string",
          "DocumentNumber": 0,
          "FieldDefinition": {
            "Position": {
              "PageNumber": 0,
              "X": 0,
              "Y": 0
            },
            "Size": {
              "Width": 0,
              "Height": 0
            }
          }
        }
      ],
      "DocumentLinks": [
        {
          "ElementId": "string",
          "DocumentNumber": 0,
          "LinkAnchor": {
            "ElementId": "string",
            "DocumentNumber": 0,
            "LinkDefinition": {
              "Position": {
                "PageNumber": 0,
                "X": 0,
                "Y": 0
              },
              "Size": {
                "Width": 0,
                "Height": 0
              }
            }
          },
          "FieldDefinition": {
            "Position": {
              "PageNumber": 0,
              "X": 0,
              "Y": 0
            },
            "Size": {
              "Width": 0,
              "Height": 0
            }
          }
        }
      ]
    },

Reading confirmation

With the reading task a recipient must confirm reading the document to have the evidence that he/she was reading it.

Generally there are 3 basic ways concerning the range of the reading task:

Reading task for an area
Reading task for one page
Reading task for the document

Area read confirmation

"AreaReadConfirmations": [
      {
        "ElementId": "string",
        "Required": true,
        "DocumentNumber": 0,
        "DisplayName": "string",
        "GuidingOrder": 0,
        "Definition": {
          "Position": {
            "PageNumber": 0,
            "X": 0,
            "Y": 0
          },
          "Size": {
            "Width": 0,
            "Height": 0
          }
        }
      }
    ],

Page read confirmation

"PageReadConfirmations": [
      {
        "ElementId": "string",
        "Required": true,
        "DocumentNumber": 0,
        "DisplayName": "string",
        "PageNumber": 0,
        "GuidingOrder": 0
      }
    ],

Document read confirmation

 "DocumentReadConfirmations": {
      "ElementId": "string",
      "Required": true,
      "DocumentNumber": 0,
      "DisplayName": "string",
      "GuidingOrder": 0,
    }

Activities

This is the main part of the envelope configuration. The section activities can include one to many actions.

Action

Please note that additionally to the elements below you can add a visibility option to either show all documents to the recipient or just selected once:

Visibility option

 "VisibilityOptions": [
        {
          "DocumentNumber": 0,
          "IsHidden": true
        }
      ]

Those actions include the recipients of the envelope as well as the tasks for those recipients (signing, viewing etc.)

One action can either include one of the following tasks:

Automatic signing
Document viewing
P7M signing
Signing

Automatic signing

Please see the following sample for an automatic signing action:

{
	"Documents": [
		{
			"FileId": "1234ddc4-1234-1234-1234-3af31c131234",
			"DocumentNumber": 1
		}
	],
	"Name": "Test.pdf",
	"AddDocumentTimestamp": false,
	"ShareWithTeam": true,
	"LockFormFieldsOnFinish": false,
	"Activities": [
		{
			"Action": {
				"SignAutomatic": {
					"ProfileId": "12347562-1234-1234-1234-5a43184d1234",
					"RenderingLanguageCode": "EN",
					"VisibleSignatures": [
						{
							"DocumentNumber": 1,
							"UseExternalTimestampServer": false,
							"FieldDefinition": {
								"Position": {
									"PageNumber": 1,
									"X": 68.0,
									"Y": 631.8
								},
								"Size": {
									"Width": 190.0,
									"Height": 80.0
								}
							}
						}
					]
				}
			},
			"VisibilityOptions": [
				{
					"DocumentNumber": 1,
					"IsHidden": false
				}
			]
		}
	],
	"EmailConfiguration": {
		"Subject": "Please sign the enclosed envelope",
		"Message": "Dear #RecipientFirstName# #RecipientLastName#

#PersonalMessage#

Please sign the envelope #EnvelopeName#

Envelope will expire at #ExpirationDate#"
	},
	"ReminderConfiguration": {
		"Enabled": true,
		"FirstReminderInDays": 5,
		"ReminderResendIntervalInDays": 3,
		"BeforeExpirationInDays": 3
	},
	"ExpirationConfiguration": {
		"ExpirationInSecondsAfterSending": 2419200
	}
}

Document viewing

Please see the following sample for a document viewing action:

{
	"Documents": [
		{
			"FileId": "264addc4-1234-1234-1234-3af31c13b3c2",
			"DocumentNumber": 1
		}
	],
	"Name": "Test.pdf",
	"AddDocumentTimestamp": false,
	"ShareWithTeam": true,
	"LockFormFieldsOnFinish": false,
	"Activities": [
		{
			"Action": {
				"View": {
					"RecipientConfiguration": {
						"ContactInformation": {
							"Email": "john.doe@sample.com",
							"GivenName": "John",
							"Surname": "Doe",
							"LanguageCode": "EN"
						},
						"SendEmails": true,
						"AllowAccessAfterFinish": true
					},
					"ViewingGroup": "1"
				}
			},
			"VisibilityOptions": [
				{
					"DocumentNumber": 1,
					"IsHidden": false
				}
			]
		},
		{
			"Action": {
				"SendCopy": {
					"RecipientConfiguration": {
						"ContactInformation": {
							"Email": "jane.doe@sample.com",
							"GivenName": "Jane",
							"Surname": "Doe",
							"LanguageCode": "EN"
						}
					},
					"CopyingGroup": "2"
				}
			},
			"VisibilityOptions": [
				{
					"DocumentNumber": 1,
					"IsHidden": false
				}
			]
		}
	],
	"EmailConfiguration": {
		"Subject": "Please sign the enclosed envelope",
		"Message": "Dear #RecipientFirstName# #RecipientLastName#

#PersonalMessage#

Please sign the envelope #EnvelopeName#

Envelope will expire at #ExpirationDate#"
	},
	"ReminderConfiguration": {
		"Enabled": true,
		"FirstReminderInDays": 5,
		"ReminderResendIntervalInDays": 3,
		"BeforeExpirationInDays": 3
	},
	"ExpirationConfiguration": {
		"ExpirationInSecondsAfterSending": 2419200
	}
}

P7M signing

Please see the following sample for a P7M signing action (for more information please also see Using P7M (PKCS7) signature type):

{
    "Documents": [
        {
            "FileId": "a33f6f7d-1234-1234-1234-42cfbc3cad08",
            "DocumentNumber": 1
        }
    ],
    "Name": "test",
    "Activities": [
        {
            "Action": {
                "SignAsP7M": {
                    "RecipientConfiguration": {
                        "ContactInformation": {
                            "Email": "john.doe@sample.com",
                            "GivenName": "John",
                            "Surname": "Doe",
                            "LanguageCode": "EN"
                        },
                        "SendEmails": true
                    },
                    "SignatureMethods": {
                        "LocalCertificate": false,
                        "DisposableCertificate": {
                            "DocumentIssuingCountry": "AT",
                            "IdentificationIssuingCountry": "AT",
                            "IdentificationType": "DrivingLicense",
                            "PhoneNumber": "+##PhoneNumber##",
                            "DocumentType": "DriverLicense",
                            "DocumentIssuedBy": "##Issuer##",
                            "DocumentIssuedOn": "2023-02-15",
                            "DocumentExpiryDate": "2023-02-28",
                            "SerialNumber": "##SerialNumber##",
                            "DocumentNumber": "123"
                        }
                    },
                    "SignAsP7MGroup": "1"
                }
            }
        }
    ]
}

Signing

Lets have a detailed look into the signing task.

The signing task includes the following information:

Recipient configuration
- Contact information
Personal message (optional)
Authentication
- Access code
- SMS OTP
- Swedish bankId
- OAuth
- SAML
Elements
- same elements available as documented in the section "unassigned elements"
Signature data configuration
Batch configuration

Recipient configuration

"RecipientConfiguration": {
            "ContactInformation": {
              "Email": "string",
              "GivenName": "string",
              "Surname": "string",
              "PhoneNumber": "string",
              "LanguageCode": "AF"
            },

Personal message

 "PersonalMessage": "string",

Authentication

"AuthenticationConfiguration": {

Within this section you can place the different authentication methods:

Access code

 "AccessCode": {
                "Code": "string"
              },

SMS-OTP

 "SmsOneTimePassword": {
                "PhoneNumber": "string"
              },

Swedish Bank Id

 "SwedishBankId": {
                "PersonalNumber": "string",
                "AllowAnyPersonalNumber": true
              },

OAuth2

  "OAuthAuthentications": [
                {
                  "ProviderName": "string",
                  "Validations": [
                    {
                      "FieldReferenceId": "string",
                      "ExpectedValue": "string"
                    }
                  ]
                }
              ],

SAML

 "SamlAuthentications": [
                {
                  "ProviderName": "string",
                  "Validations": [
                    {
                      "FieldReferenceId": "string",
                      "ExpectedValue": "string"
                    }
                  ]
                }
              ]

Additionally to the those configuration referring the recipient also following settings are available. This setting include to disable the email and allowing the recipient to access the envelope again after it has been completed and closed. Furthermore, it is possible to include app links in the email and allowing delegation:

Additional recipient configuration

"DisableEmail": true,
            "AllowAccessAfterFinish": true,
            "IncludedEmailAppLinks": {
              "Android": true,
              "iOS": true,
              "Windows": true
            },
            "AllowDelegation": true

Elements

In this section you can add elements for the recipient which (if they are set required) must be finished in order to finish the envelope.

PDF Forms

Textbox

 "TextBoxes": [
              {
                "ElementId": "string",
                "Required": true,
                "Value": "string",
                "DocumentNumber": 0,
                "Validation": {
                  "Type": "None",
                  "DateValidationConfiguration": {
                    "Format": "string",
                    "Range": {
                      "From": "string",
                      "To": "string"
                    }
                  },
                  "NumberValidationConfiguration": {
                    "DecimalDigits": 0,
                    "Symbol": "string",
                    "SymbolLocation": "Start",
                    "GroupSeparator": "Comma",
                    "DecimalSeparator": "Comma",
                    "Range": {
                      "From": "string",
                      "To": "string"
                    }
                  },
                  "PhoneValidationConfiguration": {
                    "Type": "International"
                  },
                  "TimeValidationConfiguration": {
                    "Format": "string",
                    "Range": {
                      "From": "string",
                      "To": "string"
                    }
                  }
                },
                "FieldDefinition": {
                  "ReadOnly": true,
                  "MaxLength": 0,
                  "IsMultiline": true,
                  "IsPassword": true,
                  "IsFileSelect": true,
                  "IsScrollAllowed": true,
                  "IsCombined": true,
                  "TextFormat": {
                    "TextColor": "string",
                    "FontSizeInPt": 0,
                    "FontName": "string",
                    "Bold": true,
                    "Italic": true,
                    "TextAlign": "Left"
                  },
                  "Position": {
                    "PageNumber": 0,
                    "X": 0,
                    "Y": 0
                  },
                  "Size": {
                    "Width": 0,
                    "Height": 0
                  }
                },
                "TaskConfiguration": {
                  "GroupedOrderDefinition": {
                    "GroupId": "string",
                    "OrderIndex": 0
                  }
                }
              }
            ],

Checkbox

"CheckBoxes": [
              {
                "ElementId": "string",
                "RequiredEvalPolicy": "None",
                "DocumentNumber": 0,
                "Required": true,
                "IsChecked": true,
                "FieldDefinition": {
                  "ExportValue": "string",
                  "Position": {
                    "PageNumber": 0,
                    "X": 0,
                    "Y": 0
                  },
                  "Size": {
                    "Width": 0,
                    "Height": 0
                  },
                  "ReadOnly": true
                },
                "TaskConfiguration": {
                  "GroupedOrderDefinition": {
                    "GroupId": "string",
                    "OrderIndex": 0
                  }
                }
              }
            ],

Combobox

 "ComboBoxes": [
              {
                "ElementId": "string",
                "DocumentNumber": 0,
                "Required": true,
                "Value": "string",
                "FieldDefinition": {
                  "TextFormat": {
                    "TextColor": "string",
                    "FontSizeInPt": 0,
                    "FontName": "string",
                    "Bold": true,
                    "Italic": true,
                    "TextAlign": "Left"
                  },
                  "Items": [
                    {
                      "ExportValue": "string",
                      "DisplayValue": "string"
                    }
                  ],
                  "IsEditable": true,
                  "ReadOnly": true,
                  "Position": {
                    "PageNumber": 0,
                    "X": 0,
                    "Y": 0
                  },
                  "Size": {
                    "Width": 0,
                    "Height": 0
                  }
                },
                "TaskConfiguration": {
                  "GroupedOrderDefinition": {
                    "GroupId": "string",
                    "OrderIndex": 0
                  }
                }
              }
            ],

Radio button

 "RadioButtons": [
              {
                "GroupName": "string",
                "DocumentNumber": 0,
                "IsSelectUnison": true,
                "Required": true,
                "SelectedItem": "string",
                "FieldDefinitions": [
                  {
                    "ExportValue": "string",
                    "IsChecked": true,
                    "CheckBoxAppearance": true,
                    "ReadOnly": true,
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                ],
                "GroupTaskConfiguration": {
                  "GroupedOrderDefinition": {
                    "GroupId": "string",
                    "OrderIndex": 0
                  }
                }
              }
            ],

Listbox

 "ListBoxes": [
              {
                "ElementId": "string",
                "DocumentNumber": 0,
                "Required": true,
                "PreSelectedItems": [
                  "string"
                ],
                "FieldDefinition": {
                  "TextFormat": {
                    "TextColor": "string",
                    "FontSizeInPt": 0,
                    "FontName": "string",
                    "Bold": true,
                    "Italic": true,
                    "TextAlign": "Left"
                  },
                  "Items": [
                    {
                      "ExportValue": "string",
                      "DisplayValue": "string"
                    }
                  ],
                  "IsMultiSelect": true,
                  "ReadOnly": true,
                  "Position": {
                    "PageNumber": 0,
                    "X": 0,
                    "Y": 0
                  },
                  "Size": {
                    "Width": 0,
                    "Height": 0
                  }
                },
                "TaskConfiguration": {
                  "GroupedOrderDefinition": {
                    "GroupId": "string",
                    "OrderIndex": 0
                  }
                }
              }
            ],

Signatures

Signature information

"Signatures": [
              {
                "ElementId": "string",
                "Required": true,
                "DocumentNumber": 0,
                "DisplayName": "string",
                "FieldDescription": "string",
 				"AllowedSignatureTypes": {

TaskConfiguration

Before you add the signatures please add the following in the section "Signatures" . [ in order to set the order of the recipients (required), to set the timestamp (optional)

and to set the a batchgroup (optional)

:

TaskConfiguration

"TaskConfiguration": {
                  "StampImprintDateConfiguration": {
                    "UseLocalTimezone": true,
                    "DateTimeFormat": "string"
                  },
                  "UseExternalTimestampServer": true,
                  "BatchGroup": "string",
                  "OrderDefinition": {
                    "OrderIndex": 0
                  }
                }

In the "AllowedSignatureTypes" you can place the following available signature types:

Please note: The following configurations for the signature types do not include the field definition. Please add the following code to the choosen signature type in order to place the signature field on the document.

Field definition

"FieldDefinition": {
                  "Position": {
                    "PageNumber": 0,
                    "X": 0,
                    "Y": 0
                  },
                  "Size": {
                    "Width": 0,
                    "Height": 0
                  }
                },

ClickToSign

"ClickToSign": {
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

DrawToSign

 "DrawToSign": {
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

TypeToSign

 "TypeToSign": {
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

LocalCertificate

 "LocalCertificate": {
                    "EnforcePreferredHashAlgorithm": true,
                    "PreferredHashAlgorithm": "Sha256",
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

DisposableCertificate

"DisposableCertificate": {
                    "IsLongLived": false,
                    "ValidityInSeconds": 0,
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

Additionally to the signature type configuration the signature data configuration is needed. Please see the following sample:

DisposableCertificate

"SignatureDataConfiguration": {
    "DisposableCertificate": {
        "DocumentIssuingCountry": "AT",
        "IdentificationIssuingCountry": "AT",
        "IdentificationType": "AML",
        "PhoneNumber": "+...",
        "DocumentType": "Passport",
        "DocumentIssuedOn": "2024-09-10",
        "DocumentExpiryDate": "2024-09-24",
        "SerialNumber": "...",
        "DocumentNumber": "..."
    }
},

Referring to the identification type the following values are available:

None
ForeignTaxCode
PersonalNumber
Passport
NationalIdentityCard
ItalianTaxCode
NoSerialNumber
DrivingLicense
ResidencePermit
TemporaryResidencePermit
EmbassyDocument
AML*

*All disposable document data fields

Document Type
Document Number
Document Issued On
Document Issued By
Document Expiry Date and Document Issuing Country

are optional. However, if any one of the document fields is provided, then all of them must be completed, with the exception of Document Issued By, which remains optional in all cases.

Referring to the document type the following values are available:

IdentityCard
DriverLicense
Passport
ResidencePermit
NationalElectronicIdentityCard
TemporaryResidencePermit
EmbassyDocument

DisposableCertificate (Long-Lived)

Beside the disposable certificate, the solution can use a specific procedure called "Long-Lived Disposable" for scenarios where the signature becomes a valid qualified signature after signing. This can be useful where the identification is confirmed/approved after signing of the document.

Please note the following: It is not allowed to download the document or the audit trail for a long-lived disposable. Therefore, the policies must be set correctly (<AllowSaveDocument>0</AllowSaveDocument> and <AllowSaveAuditTrail>0</AllowSaveAuditTrail>)

General description

The Long-Lived Disposable Certificate (LLD) is a special variant of a Disposable certificate.

The main difference to the disposable certificate is, that it is not being activated immediately, but after the signatures have been applied. LLD are always active, no need to activate them.

Please see the following sample configuration for LLD:

DisposableCertificate (Long-Lived)

"DisposableCertificate": {
                    "IsLongLived": true,
                    "ValidityInSeconds": 0,
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

SwissComOnDemand

"SwissComOnDemand": {
                    "ValidityInSeconds": 0,
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

ATrustCertificate

 "ATrustCertificate": {
                    "TemplateId": "string",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

Biometric

Please note the following available values for the "SignaturePositioning":

Value	Description

Value	Description
intersects with field	The signing must intersect with the field but the signer is allowed to leave the boundaries of the signature field
within field	The signature must be completely within the boundaries of the signature field
on page	The signature can start anywhere on the page, even without intersecting with the signature field

Biometric

"Biometric": {
                    "BiometricVerification": true,
                    "AllowBiometricStoringOnly": true,
                    "StoreSignedResponseWithoutBioData": true,
                    "AllowSkipBiometricVerification": true,
                    "BiometricServerUserId": "string",
                    "SignaturePositioning": "WithinField",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

RemoteCertificate

"RemoteCertificate": {
                    "ValidityInSeconds": 0,
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

OneTimePassword

"OneTimePassword": {
                    "ValidityInSeconds": 0,
                    "UseExternalSignatureImage": "Optional",
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

SwedishBankId

 "SwedishBankId": {
                    "Preferred": true,
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayTransactionId": true,
                      "DisplayTransactionToken": true,
                      "DisplayPhoneNumber": true,
                      "UseCustomStampImprint": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontName": "string",
                      "FontSizeInPt": 0
                    }
                  },

SignaturePlugins

"SignaturePlugins": [
                    {
                      "PluginId": "string",
                      "Preferred": true,
                      "StampImprintConfiguration": {
                        "DisplayExtraInformation": true,
                        "DisplayEmail": true,
                        "DisplayTransactionId": true,
                        "DisplayTransactionToken": true,
                        "DisplayPhoneNumber": true,
                        "UseCustomStampImprint": true,
                        "DisplayIp": true,
                        "DisplayName": true,
                        "DisplaySignatureDate": true,
                        "FontName": "string",
                        "FontSizeInPt": 0
                      }
                    }
                  ]

Predefined Field Elements

You can also add predefined elements to the document. Please see the following configurations:

Textfields

"TextFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "Value": "string",
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

EmailFields

 "EmailFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

InitialsFields

"InitialsFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "IncludeMiddleNameInitials": true,
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

GivenNameFields

 "GivenNameFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

SurnameFields

"SurnameFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

FullNameFields

"FullNameFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ],

DataFields

 "DateFields": [
                {
                  "ElementId": "string",
                  "DocumentNumber": 0,
                  "DateFormat": "string",
                  "FieldDefinition": {
                    "TextFormat": {
                      "TextColor": "string",
                      "FontSizeInPt": 0,
                      "FontName": "string",
                      "Bold": true,
                      "Italic": true,
                      "TextAlign": "Left"
                    },
                    "Position": {
                      "PageNumber": 0,
                      "X": 0,
                      "Y": 0
                    },
                    "Size": {
                      "Width": 0,
                      "Height": 0
                    }
                  }
                }
              ]
            },

FinishActionConfiguration

Finish action configuration

"FinishActionConfiguration": {
            "SignAnyWhereViewer": {
              "RedirectUri": "string"
            },
            "SignificantClientSignatureCaptureForIos": {
              "RemoveDocumentFromRecentDocumentList": true,
              "CallClientActionOnlyAfterSuccessfulSync": true,
              "CloseApp": true,
              "RedirectUri": "string"
            },
            "SignificantClientSignatureCaptureForAndroid": {
              "RemoveDocumentFromRecentDocumentList": true,
              "CallClientActionOnlyAfterSuccessfulSync": true,
              "CloseApp": true,
              "RedirectUri": "string"
            },
            "SignificantClientSignatureCaptureForWindows": {
              "RemoveDocumentFromRecentDocumentList": true,
              "CallClientActionOnlyAfterSuccessfulSync": true,
              "CloseApp": true,
              "RedirectUri": "string"
            },
            "KioskSdk": {
              "RedirectUri": "string"
            }
          },

Additional envelope information

Additionally to the envelope information you can find above in the section "envelope configuration" you can configure the following:

Email configuration
Reminder configuration
Expiration configuration
Callback configuration
Agreement configuration

Email configuration

 "EmailConfiguration": {
    "Subject": "string",
    "Body": "string",
    "SenderDisplayName": "string"
  },

Reminder configuration

 "ReminderConfiguration": {
    "Enabled": true,
    "FirstReminderInDays": 0,
    "ReminderResendIntervalInDays": 0,
    "BeforeExpirationInDays": 0
  },

Expiration configuration

Note: The following information is valid for envelopes as well as for drafts: Settings for the relative time:

Envelope expiry as relative time, provided in seconds (or milliseconds) after sending the envelope
Envelope expiry as relative time, in days after sending the envelope

Settings for the absolute time:

Envelope expiry as absolute time, as timestamp in GMT (with Z in the timestamp text) or optional with defined timezone

Please note the following: Defining no option will lead to usage of the default value of 28 days. Moreover, if you configure an absolute expiry time which is already in the past at time of sending the envelope, an error message will be returned. For the draft, it is required to have both options - store absolute or relative time. For the envelopes, only an absolute timestamp is required to be set and considered while being in progress.

Expiration configuration

"ExpirationConfiguration": {
    "ExpirationInSeconds": 0,
    "ExpirationDate": "string"
  }

Callback configuration

 "CallbackConfiguration": {
    "CallbackUrl": "string",
    "StatusUpdateCallbackUrl": "string",
    "ActivityActionCallbackConfiguration": {
      "Url": "string",
      "ActionCallbackSelection": {
        "ConfirmTransactionCode": true,
        "DefaultEventType": true,
        "AgreementAccepted": true,
        "AgreementRejected": true,
        "RequestPrepareAuthenticationInformationSuccess": true,
        "PrepareAuthenticationSuccess": true,
        "AuthenticationFailed": true,
        "AuthenticationRejected": true,
        "AuthenticationSuccess": true,
        "ReAuthenticationFailed": true,
        "AuditTrailRequested": true,
        "AuditTrailXmlRequested": true,
        "CalledPage": true,
        "WhoIsInformation": true,
        "DocumentDownloaded": true,
        "FlattenedDocumentDownloaded": true,
        "AddedAnnotation": true,
        "AddedAttachment": true,
        "AppendedDocument": true,
        "FormsFilled": true,
        "ConfirmReading": true,
        "PageViewChanged": true,
        "SendTransactionCode": true,
        "PrepareSignWorkstepDocument": true,
        "SignWorkstepDocument": true,
        "UndoAction": true,
        "WorkstepCreated": true,
        "WorkstepFinished": true,
        "WorkstepRejected": true,
        "DisablePolicyAndValidityChecks": true,
        "EnablePolicyAndValidityChecks": true,
        "AppendFileToWorkstep": true,
        "AppendTasksToWorkstep": true,
        "SetOptionalDocumentState": true,
        "PreparePayloadForBatch": true
      }
    }
  },

Agreement configuration

 "AgreementConfiguration": {
    "UseOrganizationAgreementSettings": true,
    "Translations": [
      {
        "LanguageCode": "AF",
        "Text": "string",
        "Header": "string",
        "IsDefault": true
      }
    ]
  }

Sending envelope

After you have added all form fields and signatures you can send the envelope to the recipients. Therefor, add the file Id you received from the file/upload call and add the configuration. Then you can send the envelope with the envelope/send call.

Envelope structure

Upload a file

Configuration

Starting configuration

Envelope configuration

Unassigned elements

Attachments

Attachments

Link configuration

Link configuration

Reading confirmation

Area read confirmation

Area read confirmation

Page read confirmation

Page read confirmation

Document read confirmation

Document read confirmation

Activities

Action

Visibility option

Automatic signing

Document viewing

P7M signing

Signing

Recipient configuration

Recipient configuration

Personal message

Personal message

Authentication

Authentication

Access code

Access code

SMS-OTP

SMS-OTP

Swedish Bank Id

Swedish Bank Id

OAuth2

OAuth2

SAML

SAML

Additional recipient configuration

Elements

PDF Forms

Textbox

Textbox

Checkbox

Checkbox

Combobox

Combobox

Radio button

Radio button

Listbox

Listbox

Signatures

Signature information

TaskConfiguration

TaskConfiguration

Field definition

ClickToSign

ClickToSign

DrawToSign

DrawToSign

TypeToSign

TypeToSign

LocalCertificate

LocalCertificate

DisposableCertificate

DisposableCertificate

DisposableCertificate

DisposableCertificate (Long-Lived)

DisposableCertificate (Long-Lived)

SwissComOnDemand

SwissComOnDemand

ATrustCertificate

ATrustCertificate

Biometric

Biometric

RemoteCertificate

RemoteCertificate

OneTimePassword