v5 Beginner Guide REST

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

  1. Upload a file
  2. Workstep configuration
  3. Send an envelope

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

Upload a file

You can upload a file with the following URL:

https://demo.xyzmo.com/Api/v4.0/sspfile/uploadtemporary

The result of the API call is the SspFileId which we need for the sending call.

Workstep configuration

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

  • Viewer preferences
  • Policy
  • Sender and receiver information
  • Workstep tasks
  • Authentication
  • PdfForms

Empty workstep configuration

Lets start with an empty workstep first and then fill it step by step with the settings above. In the next collapse you can find an empty workstep (change ##EMAIL## to the email-address you want to send the envelope):

 Configuration
{
  "SspFileIds": [
    "##FileId##"
  ],
"SendEnvelopeDescription": {
  "Name": "test",
  "EmailSubject": "Please sign the enclosed envelope",
  "EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope will expire at #ExpirationDate#",
  "DisplayedEmailSender": "",
  "EnableReminders": true,
  "FirstReminderDayAmount": 5,
  "RecurrentReminderDayAmount": 3,
  "BeforeExpirationDayAmount": 3,
  "DaysUntilExpire": 28,
  "CallbackUrl": "",
  "StatusUpdateCallbackUrl": "",
  "Steps": [
    {
      "OrderIndex": 1,
      "Recipients": [
        {
          "Email": "##EMAIL##",
          "FirstName": "##NAME##",
          "LastName": "##NAME##",
          "LanguageCode": "en",
          "EmailBodyExtra": "",
          "DisableEmail": false,
          "AddAndroidAppLink": false,
          "AddIosAppLink": false,
          "AddWindowsAppLink": false,
          "AllowDelegation": true,
          "SkipExternalDataValidation": false,
          "AuthenticationMethods": []
        }
      ],
      "EmailBodyExtra": "",
      "RecipientType": "Signer",
      "WorkstepConfiguration": {
        "WorkstepLabel": "test",
        "SmallTextZoomFactorPercent": 100,
        "FinishAction": {
          "ServerActions": [],
          "ClientActions": []
        },
        
          "TransactionCodePushPluginData": [],
        
       
        "TransactionCodeConfigurations": [
          {
          }
        ],
        "SignatureConfigurations": [],
        "ViewerPreferences": {
          "FinishWorkstepOnOpen": false,
          "VisibleAreaOptions": {
            "AllowedDomain": "*",
            "Enabled": false
          }
        },
        "Policy": {
          
          "WorkstepTasks": {
            "PictureAnnotationMinResolution": 0,
            "PictureAnnotationMaxResolution": 0,
            "PictureAnnotationColorDepth": "Color16M",
            "SequenceMode": "NoSequenceEnforced",
            "PositionUnits": "PdfUnits",
            "ReferenceCorner": "Lower_Left",
            "Tasks": []
          }
        }
      },
      "DocumentOptions": [
        {
          "DocumentReference": "1",
          "IsHidden": false
        }
      ],
      "UseDefaultAgreements": true
    },
    {
      "OrderIndex": 2,
      "Recipients": [
        {
          "Email": "##EMAIL##",
          "FirstName": "##NAME##",
          "LastName": "##NAME##",
          "LanguageCode": "en",
          "EmailBodyExtra": "",
          "DisableEmail": false,
          "AddAndroidAppLink": false,
          "AddIosAppLink": false,
          "AddWindowsAppLink": false,
          "AllowDelegation": false,
          "SkipExternalDataValidation": false,
          "AuthenticationMethods": []
        }
      ],
      "EmailBodyExtra": "",
      "RecipientType": "Cc",
      "DocumentOptions": [],
      "UseDefaultAgreements": false
    }
  ],
  "AddFormFields": {
    "Forms": {}
  },
  "OverrideFormFieldValues": {
    "Forms": {}
  },
  "AttachSignedDocumentsToEnvelopeLog": false
}
}


The next screenshot shows the document after sending the workstep configuration:

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

Policy

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

"Policy": {

Within this brace you can add the following policies:

 "GeneralPolicies": {
            "AllowSaveDocument": false,
            "AllowSaveAuditTrail": false,
            "AllowRotatingPages": false,
            "AllowEmailDocument": false,
            "AllowPrintDocument": false,
            "AllowFinishWorkstep": false,
            "AllowRejectWorkstep": false,
            "AllowRejectWorkstepDelegation": false,
            "AllowUndoLastAction": false,
            "AllowAdhocPdfAttachments": false,
            "AllowAdhocSignatures": false,
            "AllowAdhocStampings": false,
            "AllowAdhocFreeHandAnnotations": false,
            "AllowAdhocTypewriterAnnotations": false,
            "AllowAdhocPictureAnnotations": false,
            "AllowAdhocPdfPageAppending": false
          },

In this case all policies are disabled. The table will show you the differences on the document if you enable all policies and if you disable all policies:


Policies disabledPolicies enabled



As you can see on the right screenshot the recipient of the envelope can now print the document as well as reject the envelope and more.

Sender and receiver information

Sender information:

"SenderInformation": {
          "UserInformation": {
            "FirstName": "Manuel",
            "LastName": "Gierlinger",
            "EMail": "##EMAIL##"
          }
        },

Receiver information:

"ReceiverInformation": {
          "UserInformation": {
            "FirstName": "manuel",
            "LastName": "gierlinger",
            "EMail": "##EMAIL##"
	    }
          },

The next section shows you where you can place the sender and receiver information.

"EmailBodyExtra": "",
      "RecipientType": "Signer",
      "WorkstepConfiguration": {
        "WorkstepLabel": "test",
        "SmallTextZoomFactorPercent": 100,
        "FinishAction": {
          "ServerActions": [],
          "ClientActions": []
        },
        "ReceiverInformation": {
          "UserInformation": {
            "FirstName": "manuel",
            "LastName": "gierlinger",
            "EMail": "##EMAIL##"
          },
          "TransactionCodePushPluginData": []
        },
        "SenderInformation": {
          "UserInformation": {
            "FirstName": "Manuel",
            "LastName": "Gierlinger",
            "EMail": "##EMAIL##"
          }
        },

We will need the sender and receiver information for the section “TypeWriterAnnotation”.

Workstep tasks

In this section you can define the signature fields. In the next collapses you can find some examples of the signature fields configuration.

 Click2Sign
"WorkstepTasks": {
            "PictureAnnotationMinResolution": 0,
            "PictureAnnotationMaxResolution": 0,
            "PictureAnnotationColorDepth": "Color16M",
            "SequenceMode": "NoSequenceEnforced",
            "PositionUnits": "PdfUnits",
            "ReferenceCorner": "Lower_Left",
            "Tasks": [
              {
                "PositionPage": 1,
                "Position": {
                  "PositionX": 69.0,
                  "PositionY": 529.92
                },
                "Size": {
                  "Height": 80.0,
                  "Width": 190.0
                },
                "AdditionalParameters": [
                  {
                    "Key": "enabled",
                    "Value": "1"
                  },
                  {
                    "Key": "positioning",
                    "Value": "onPage"
                  },
                  {
                    "Key": "req",
                    "Value": "1"
                  },
                  {
                    "Key": "fd",
                    "Value": ""
                  },
                  {
                    "Key": "fd_dateformat",
                    "Value": "dd-MM-yyyy HH:mm:ss"
                  },
                  {
                    "Key": "fd_timezone",
                    "Value": "datetimeutc"
                  }
                ],
                "AllowedSignatureTypes": [
                  {
                    "AllowedCapturingMethod": "Click2Sign",
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontFamily": "Times New Roman",
                      "FontSize": 11.0
                    },
                    "Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
                    "DiscriminatorType": "SigTypeClick2Sign",
                    "Preferred": true
                  }
                ],
                "UseTimestamp": false,
                "IsRequired": true,
                "Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
                "DisplayName": "",
                "DocRefNumber": 1,
                "DiscriminatorType": "Signature"
              }
            ]
          }
        }
      },
 Type2Sign
"WorkstepTasks": {
            "PictureAnnotationMinResolution": 0,
            "PictureAnnotationMaxResolution": 0,
            "PictureAnnotationColorDepth": "Color16M",
            "SequenceMode": "NoSequenceEnforced",
            "PositionUnits": "PdfUnits",
            "ReferenceCorner": "Lower_Left",
            "Tasks": [
              {
                "PositionPage": 1,
                "Position": {
                  "PositionX": 69.0,
                  "PositionY": 529.92
                },
                "Size": {
                  "Height": 80.0,
                  "Width": 190.0
                },
                "AdditionalParameters": [
                  {
                    "Key": "enabled",
                    "Value": "1"
                  },
                  {
                    "Key": "positioning",
                    "Value": "onPage"
                  },
                  {
                    "Key": "req",
                    "Value": "1"
                  },
                  {
                    "Key": "fd",
                    "Value": ""
                  },
                  {
                    "Key": "fd_dateformat",
                    "Value": "dd-MM-yyyy HH:mm:ss"
                  },
                  {
                    "Key": "fd_timezone",
                    "Value": "datetimeutc"
                  }
                ],
                "AllowedSignatureTypes": [
                  {
                    "AllowedCapturingMethod": "Type2Sign",
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontFamily": "Times New Roman",
                      "FontSize": 11.0
                    },
                    "Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
                    "DiscriminatorType": "SigTypeType2Sign",
                    "Preferred": true
                  }
                ],
                "UseTimestamp": false,
                "IsRequired": true,
                "Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
                "DisplayName": "",
                "DocRefNumber": 1,
                "DiscriminatorType": "Signature"
              }
            ]
          }
        }
      },
 Draw2Sign
"WorkstepTasks": {
            "PictureAnnotationMinResolution": 0,
            "PictureAnnotationMaxResolution": 0,
            "PictureAnnotationColorDepth": "Color16M",
            "SequenceMode": "NoSequenceEnforced",
            "PositionUnits": "PdfUnits",
            "ReferenceCorner": "Lower_Left",
            "Tasks": [
              {
                "PositionPage": 1,
                "Position": {
                  "PositionX": 69.0,
                  "PositionY": 529.92
                },
                "Size": {
                  "Height": 80.0,
                  "Width": 190.0
                },
                "AdditionalParameters": [
                  {
                    "Key": "enabled",
                    "Value": "1"
                  },
                  {
                    "Key": "positioning",
                    "Value": "onPage"
                  },
                  {
                    "Key": "req",
                    "Value": "1"
                  },
                  {
                    "Key": "fd",
                    "Value": ""
                  },
                  {
                    "Key": "fd_dateformat",
                    "Value": "dd-MM-yyyy HH:mm:ss"
                  },
                  {
                    "Key": "fd_timezone",
                    "Value": "datetimeutc"
                  }
                ],
                "AllowedSignatureTypes": [
                  {
                    "AllowedCapturingMethod": "Draw2Sign",
                    "StampImprintConfiguration": {
                      "DisplayExtraInformation": true,
                      "DisplayEmail": true,
                      "DisplayIp": true,
                      "DisplayName": true,
                      "DisplaySignatureDate": true,
                      "FontFamily": "Times New Roman",
                      "FontSize": 11.0
                    },
                    "Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
                    "DiscriminatorType": "SigTypeDraw2Sign",
                    "Preferred": true
                  }
                ],
                "UseTimestamp": false,
                "IsRequired": true,
                "Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
                "DisplayName": "",
                "DocRefNumber": 1,
                "DiscriminatorType": "Signature"
              }
            ]
          }
        }
      },
 Biometric
 "WorkstepTasks": {
            "PictureAnnotationMinResolution": 0,
            "PictureAnnotationMaxResolution": 0,
            "PictureAnnotationColorDepth": "Color16M",
            "SequenceMode": "NoSequenceEnforced",
            "PositionUnits": "PdfUnits",
            "ReferenceCorner": "Lower_Left",
             "Tasks": [
              {
                "PositionPage": 1,
                "Position": {
                  "PositionX": 67.0,
                  "PositionY": 521.92
                },
                "Size": {
                  "Height": 80.0,
                  "Width": 190.0
                },
                "AdditionalParameters": [
                  {
                    "Key": "enabled",
                    "Value": "1"
                  },
                  {
                    "Key": "positioning",
                    "Value": "intersectsWithField"
                  },
                  {
                    "Key": "req",
                    "Value": "1"
                  },
                  {
                    "Key": "fd",
                    "Value": ""
                  },
                  {
                    "Key": "fd_dateformat",
                    "Value": "dd-MM-yyyy HH:mm:ss"
                  },
                  {
                    "Key": "fd_timezone",
                    "Value": "datetimeutc"
                  }
                ],
                "AllowedSignatureTypes": [
                  {
                    "IsBio": false,
                    "AllowSkipBiometricVerification": false,
                    "AllowBiometricStoringOnly": false,
                    "SignedResponseWithoutBioData": false,
                    "Id": "6fa90b47-847f-47b1-b73a-9c3802aa077d",
                    "DiscriminatorType": "SigTypeBiometricSignature",
                    "Preferred": true
                  }
                ],
                "UseTimestamp": false,
                "IsRequired": true,
                "Id": "1#XyzmoDuplicateIdSeperator#Signature_532f40e1-0583-8285-fc50-c2a76dc2fa44",
                "DisplayName": "",
                "DocRefNumber": 1,
                "DiscriminatorType": "Signature"
              }
            ]
          }
        }
      },

For the biometric signature you have to define the "positioning" property, as a key-value pair with key "positioning", in the AdditionalParameters array:

Enum valueequivalent text option in designerDescription
intersectsWithFieldintersects with fieldThe signature has to start within the signature field, but the signer is allowed to leave the boundaries of the box while signing
withinFieldwithin fieldThe signature must be completely within the boundaries of the signature field
onPageon pageThe signature can start anywhere on the page, even without intersecting with the signature field

Authentication

You can add different authentications for the recipient to ensure that only the one who has the code/phone number can open the envelope. Following list shows the different authentications:

  • Pin
  • SMS
  • WindowsLive

In the next two sections you can find the configuration for the Pin-authentication and for the SMS-authentication:

Place the authentication within the recipient in the authentication methods.

PIN:

{
              "Method": "Pin",
              "Parameter": "1234"
}

SMS:

 {
              "Method": "Sms",
              "Parameter": "+0123456789"
 }

The next lines of code show you where you have to place the authentication. (In this case we used a pin authentication)

"Steps": [
    {
      "OrderIndex": 1,
      "Recipients": [
        {
          "Email": "##EMAIL##",
          "FirstName": "##NAME##",
          "LastName": "##NAME##",
          "LanguageCode": "en",
          "EmailBodyExtra": "",
          "DisableEmail": false,
          "AddAndroidAppLink": false,
          "AddIosAppLink": false,
          "AddWindowsAppLink": false,
          "AllowDelegation": false,
          "SkipExternalDataValidation": false,
          "AuthenticationMethods": [
            {
              "Method": "Pin",
              "Parameter": "1234"
            }
          ]
        }
      ],

PdfForms

The following list shows you all different form fields which can be placed on the document:

  • Textfield
  • Radiobutton
  • Checkbox
  • Listbox
  • Combobox

To add the form fields we have to add them within the WorkstepTasks and within the AddFormFields.

The next collapse show you how to configure the workstep tasks for all form fields:

 Textfield
"Forms": [
                  {
                    "Id": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245",
                    "PositionPage": 1,
                    "DocRefNumber": 1,
                    "Position": {
                      "PositionX": 77.0,
                      "PositionY": 590.0
                    },
                    "Size": {
                      "Height": 20.0,
                      "Width": 124.0
                    },
                    "DiscriminatorType": "TextBox"
                  }
                ],
                "IsRequired": false,
                "Id": "f390ebd3-4b9c-4554-ab61-4d1234bad681",
                "DisplayName": "",
                "DocRefNumber": 1,
                "DiscriminatorType": "FormGroup"
      },	
 RadioButton
{
                    "RadioButtonGroupId": "RadioButton_942fca6a-5e0e-7694-b858-b5ded711ed0b",
                    "Id": "0",
                    "PositionPage": 1,
                    "DocRefNumber": 1,
                    "Position": {
                      "PositionX": 77.0,
                      "PositionY": 553.0
                    },
                    "Size": {
                      "Height": 20.0,
                      "Width": 20.0
                    },
                    "DiscriminatorType": "RadioButton"
                  },
 Checkbox
{
                    "IsRequired": false,
                    "RequiredEvalPolicy": "None",
                    "Id": "CheckBox_41371eaf-6e1a-0d9a-58a9-0705fd8d08d1",
                    "PositionPage": 1,
                    "DocRefNumber": 1,
                    "Position": {
                      "PositionX": 77.0,
                      "PositionY": 520.0
                    },
                    "Size": {
                      "Height": 20.0,
                      "Width": 20.0
                    },
                    "DiscriminatorType": "CheckBox"
                  },
 Listbox
{
                    "Items": [],
                    "Id": "ListBox_d51c4e55-2497-8ab4-f2c8-6f60ac6a2cfd",
                    "PositionPage": 1,
                    "DocRefNumber": 1,
                    "Position": {
                      "PositionX": 79.0,
                      "PositionY": 475.0
                    },
                    "Size": {
                      "Height": 30.0,
                      "Width": 150.0
                    },
                    "DiscriminatorType": "ListBox"
                  },
 Combobox
{
                    "IsRequired": false,
                    "Items": [],
                    "Id": "ComboBox_67a8d39f-3a49-65e0-0d5d-88ac97b387ea",
                    "PositionPage": 1,
                    "DocRefNumber": 1,
                    "Position": {
                      "PositionX": 79.0,
                      "PositionY": 424.0
                    },
                    "Size": {
                      "Height": 30.0,
                      "Width": 150.0
                    },
                    "DiscriminatorType": "ComboBox"
                  }

After this configuration we have to add the form fields within the following section:

 "AddFormFields": {
   "Forms": {##Fields##}
  },

In the next collapses you can find the configuration for all form fields.

Add this line within the “Forms” section:

 "1": [

Then you can place the form fields within this tag.

 Textfield
 {
          "Value": "",
          "MaxLength": -1,
          "IsMultiline": false,
          "IsPassword": false,
          "IsComb": false,
          "TextColor": "0, 0, 0",
          "FontSize": 11.0,
          "FontName": "Times New Roman",
          "Bold": false,
          "Italic": false,
          "TextAlign": "Left",
          "Name": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245",
          "ReadOnly": false,
          "Required": false,
          "X": 77.0,
          "Y": 590.92,
          "Width": 124.0,
          "Height": 20.0,
          "Page": 1,
          "DiscriminatorType": "AddTextBoxFormFieldDescriptor"
        },
 RadioButton
{
          "ExportValue": "1b6c204b-0642-5566-f526-a725e16737a5",
          "IsChecked": false,
          "Name": "RadioButton_18d57bcd-6a82-ebde-a2ab-c4557a720bfe",
          "ReadOnly": false,
          "Required": false,
          "X": 77.0,
          "Y": 550.92,
          "Width": 20.0,
          "Height": 20.0,
          "Page": 1,
          "DiscriminatorType": "AddRadioButtonFormFieldDescriptor"
        },
 Checkbox
 {
          "IsChecked": true,
          "Name": "CheckBox_e5ba8ea4-8c39-324f-0170-a83dd3fb3aeb",
          "ReadOnly": false,
          "Required": false,
          "X": 79.0,
          "Y": 516.92,
          "Width": 20.0,
          "Height": 20.0,
          "Page": 1,
          "DiscriminatorType": "AddCheckBoxFormFieldDescriptor"
        }
 Listbox
{
          "Items": [],
          "TextColor": "",
          "FontSize": 11.0,
          "FontName": "Times New Roman",
          "Bold": false,
          "Italic": false,
          "TextAlign": "Left",
          "Name": "ListBox_e4076d02-c636-0138-fe54-03d19fe10a7d",
          "ReadOnly": false,
          "Required": false,
          "X": 79.0,
          "Y": 468.92,
          "Width": 150.0,
          "Height": 30.0,
          "Page": 1,
          "DiscriminatorType": "AddListBoxFormFieldDescriptor"
        },
 Combobox
{
          "Value": "",
          "Items": [],
          "TextColor": "",
          "FontSize": 11.0,
          "FontName": "Times New Roman",
          "Bold": false,
          "Italic": false,
          "TextAlign": "Left",
          "Name": "ComboBox_6936c368-b465-6355-0367-bdfe042c8ec7",
          "ReadOnly": false,
          "Required": false,
          "X": 79.0,
          "Y": 418.92,
          "Width": 150.0,
          "Height": 30.0,
          "Page": 1,
          "DiscriminatorType": "AddComboBoxFormFieldDescriptor"
        },

Sending envelope

After you have added all form fields and signatures you can send the envelope to recipients. Therefor, add the file Id and the workstep configuration to the REST call basicURL/envelope/send and send the envelope to the recipients.