5.5 Set Process Information (v3.1)
5.5.1 Description
This webservice method updates the people involved in the process, i.e. the stakeholders, and assigns them the steps that need to be taken.
A stakeholder can either be a person (default), a list of persons, or a contact group. The type of stakeholder is defined by the Type parameter. When you set the type to Person, or don’t pass a type at all, the API call will function exactly as in previous versions.
If you want one of multiple persons to be able to approve or sign the package for the entire group, set the Type parameter to PersonGroup, pass a PersonGroupName and list the different persons in the Persons array. Each person of the group will receive a unique URL to approve/sign their document. Attention: as soon as one member of the group has taken action, the others no longer can.
If you don’t want to list the different persons in each API call, you can also define a contact group in the eSignatures WebPortal. In that case you set the Type to ContactGroup and only need to pass the ContactGroupCode in the call.
Important notes:
- The API v.3.1 version of this call allows you to set multiple legal notices within a single signing session. You can, for instance, set a certain legal notice on one location (i.e. document), and a different legal notice on another location. Or you can set a general legal notice on Actor level which will be applied to all locations where that actor must sign, unless a different legal notice is set for specific locations.
- All stakeholders must be specified each time this call is made, otherwise they will get deleted.
- Any new Set Process Information features that are added to the API in the future will be introduced on this API v3.1 call.
- This is the only call which has v3.1 in the URL, all others will keep using v3.
5.5.2 URL
https://[servername]:[port]/webportalapi/v3.1/packages/{id}/process
5.5.3 HTTP Method
PUT
5.5.4 Template parameters
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| id | Required | Unique id for the signing package | String |
5.5.5 Request parameters
The root level has currently only one parameter: 'Stakeholders'.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
5.5.5.1 Parameters when Stakeholder Type is set to Person
The parameters below apply when the Stakeholder Type is set to Person, or not passed at all. The Set Process Information call will function exactly as in previous versions.
When the Stakeholder Type is set to another value, these parameters are forbidden.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholder (array of objects) | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
| Actors | Required (1-n) | Array with more information about what the stakeholder must do. | Array of objects |
| Type | Optional | Stakeholder type: Person | String |
| EmailAddress | Required | Email address | String |
| FirstName | Required | First name | String |
| Language | Required | UI language of this stakeholder. Currently supported: en, nl, de, fr, es, da, nb, sv, fi, lv, pl. | String |
| LastName | Required | Last name | String |
| BirthDate | Conditional | Date of birth in format: YYYY-MM-DD Note: activating mandated signer validation in the API or configuration might make this required. See section 5.4.12. |
String |
| Phonenumber | Conditional | Phone number to receive an SMS OTP. Note: always add the country code in front of the phone number. E.g. +32xxxxxxxxx. It is recommended to use the plus sign as international dialing prefix instead of using “00”. Important: never use spaces in the phone number format. |
String |
| ExternalStakeholderReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
5.5.5.2 Parameters when Stakeholder Type is set to PersonGroup
The parameters below apply when the Stakeholder Type is set to PersonGroup. When the Type is set to another value, these parameters are forbidden.
When the Stakeholder Type is set to PersonGroup any of the persons listed in the Persons array is allowed to sign the package for the entire group. All persons listed in the Persons array will receive a unique URL to sign their document.
Attention: As soon as one person has signed the document, the others no longer can.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholder (array of objects) | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
| Actors | Required (1-n) | Array with more information about what the stakeholder must do. | Array of objects |
| Type | Required | Stakeholder type: PersonGroup | String |
| PersonGroupName | Required | Name of the PersonGroup | String Max value: 128 characters |
| Persons | Required | This object provides information about all persons who are allowed to sign. | Array of objects |
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders --> Persons (array of objects) | Required if Type is set to PersonGroup. Otherwise forbidden. | This object provides information about all persons who are allowed to take action. | Array of objects |
| EmailAddress | Required | Email address. | String |
| FirstName | Required | First name. | String |
| Language | Required | UI language of this person. Currently supported: en, nl, de, fr, es, da, nb, sv, fi, lv, pl. |
String |
| LastName | Required | Last name. | String |
| BirthDate | Conditional | Date of birth in format: YYYY-MM-DD Note: activating mandated signer validation in the API or Configuration Index might make this required. See section 5.4.12. |
String |
| Phonenumber | Conditional | Phone number to receive an SMS OTP. Note: always add the country code in front of the phone number. E.g. +32xxxxxxxxx. It is recommended to use the plus sign as international dialing prefix instead of using "00". Important: never use spaces in the phone number format. |
String |
| ExternalReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
5.5.5.3 Parameters when Stakeholder Type is set to ContactGroup
The parameters below apply when the Stakeholder Type is set to ContactGroup. When the Type is set to another value, these parameters are forbidden.
Before you can use the ContactGroup type, you must first create a contact group in the eSignatures WebPortal and add the required contacts to it. Once you’ve created a contact group, a code is generated which must be passed as ContactGroupCode.
Any contacts that were added to the group will be allowed to the sign the package and will receive a unique signing URL.
Attention: As soon as one person has signed the document, the others no longer can.
| Stakeholders (array of objects) | Required (1-n) | Information about the people who are involved with this package | Array of objects |
|---|---|---|---|
| Actors | Required (1-n) | Array with more information about what the stakeholder must do. | Array of objects |
| Type | Required | Stakeholder type: ContactGroup | String |
| ContactGroupCode | Required | Code that was generated when creating a contact group in the eSignatures WebPortal. | Integer |
5.5.5.4 Actor
Parameters when Actor Type is set to Approver
In eSignatures 5.5, a new actor type is available: Approver.
By adding an actor of the type “Approver”, API users can set up an approval flow in which the package if first sent to one or more approvers, before being sent to any signers. Like signers, an approver can be of the Stakeholder Type Person, PersonGroup or ContactGroup. When using multiple approvers, the order in which they must approve is defined by the (mandatory) OrderIndex parameter. Important: the OrderIndex applied to approvers must be lower than the one applied to any signers.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders --> Actors (array of objects) | Required (1-n) | This object gives information about what the stakeholder must do. | Array of objects |
| Type | Required | Actor Type: Approver | String |
| OrderIndex | Required | This number specifies in which order the actors need to execute their action. If this number is the same for all approver actors, then the order in which they approve doesn’t matter. Incrementing numbers indicate a sequential flow: the actor with the lowest OrderIndex value must take action first, then the one with the second lowest value and so on. You can also design a complex flow: assign the same OrderIndex value to multiple actors who may approve in parallel and assign a different OrderIndex value to actors who must approve before or after the parallel approval. Important: the OrderIndex applied to approvers must be lower to the one applied to signers. Note: OrderIndex value is also used to sort the different approvers in the Document Details in the WebPortal. Approvers with the lowest OrderIndex value are listed first. If different approvers have the same OrderIndex value, they are listed alphabetically by last name, and then by first name. |
Int |
| RedirectURL | Optional Required if IsBackButtonEnabled is set to false in the Configuration Index. |
Url to which the end user is redirected after approving, or rejecting. This field must be a valid absolute url. See section 5.4.14 Redirect Details below. |
String |
| SendNotifications | Optional | eSignatures can send e-mails to all the people who are allowed to approve. Such notifications can be enabled or suppressed by setting this parameter as ‘true’ or ‘false’ (the default is ‘false’). | Boolean |
Parameters when Actor Type is set to Signer
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders --> Actors (array of objects) | Required (1-n) | This object gives information about what the stakeholder must do. | Array of objects |
| Type | Required | Actor Type: Signer Note: actor of type Signer will become a receiver as well. |
String |
| OrderIndex | Required | This number specifies in which order actors need to execute their action. If this number is the same for all actors, then the order in which they sign doesn’t matter. Incrementing numbers indicate a sequential signing flow: the actor with the lowest OrderIndex value must sign first, the one with the second lowest must sign second and so on. You can also design a complex signing flow: assign the same OrderIndex value to multiple actors who may sign in parallel and assign a different OrderIndex value to actors who must sign before or after the parallel signing. Note: OrderIndex value is also used to sort the different signers in the Face to face signing modal and in the Document Details in the WebPortal. Signers with the lowest OrderIndex value are listed first. If different signers have the same OrderIndex value, they are listed alphabetically by last name, and then by first name. |
Int |
| Locations | Required | The locations where a signature must be placed by this person. | Array of string |
| SigningTypes | Required | One or more signing type info objects. See section 9. | Array of objects |
| Phonenumber | Conditional | Phone number to receive an SMS OTP. Note: always add the country code in front of the phone number. E.g. +32xxxxxxxxx. It is recommended to use the plus sign as international dialing prefix instead of using "00". Important: never use spaces in the phone number format. |
String |
| RedirectURL | Optional Required if IsBackButtonEnabled is set to false in the Configuration Index. |
Url to which the end user is redirected after signing, or rejecting. This field must be a valid absolute url. See section 5.4.14 Redirect Details below. |
String |
| RedirectType | Conditional Forbidden if no RedirectUrl has been set. |
This parameter defines when exactly actors are redirected when using an asynchronous signing method and when a RedirectUrl has been defined. Note that this parameter does not apply to F2FRedirectUrl. Possible values: AfterSession (default), AfterDelay, Immediately. By default, actors are redirected AfterSession. This means they cannot close the signing session and have to wait for all documents to be signed before being redirected. For actors to be redirected immediately, enter immediately as value. For actors to be redirected after 5 seconds, enter AfterDelay as value. |
String |
| SendNotifications | Optional | eSignatures can send e-mails to all the people who can sign. Such notifications can be enabled or suppressed by setting this parameter as ‘true’ or ‘false’ (the default is ‘false’). | Boolean |
| UserRoles | Conditional Forbidden for XML signing |
Information about the signer’s function. This field must match the language used in the documents to be legally valid. Can currently only be passed when signature policy is used, as seen in section 5.4.13. | Array of strings |
| LegalNoticeCode | Optional Forbidden for XML signing |
LEGALNOTICE1 LEGALNOTICE2 LEGALNOTICE3 The 3 values will point to the 3 legal notices built into the application. These can be altered in the Configuration Index. The language in which the legal notice is displayed depends on the DocumentLanguage. Note: a LegalNoticeCode or LegalNoticeText set on Location level takes precedence over this value. |
String |
| LegalNoticeText | Optional Forbidden for XML signing. |
Custom legal notice text in case none of the three predefined legal notices apply. The text should be written in the same language as the one used in the documents of the package. Note: a LegalNoticeCode or LegalNoticeText set on Location level takes precedence over this value. |
String |
Parameters when Actor Type is set to Receiver
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders --> Actors (array of objects) | Required (1-n) | This object gives information about what the stakeholder must do. | Array of objects |
| Type | Required | Actor Type: Receiver | String |
| SendNotifications | Optional | eSignatures can send e-mails to all the people who should receive a copy of the signed package. Such notifications can be enabled or suppressed by setting this parameter as ‘true’ or ‘false’ (the default is ‘false’). | Boolean |
5.5.5.5 Location
This object must only be used when Actor Type is set to Signer.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders => Actors => Locations (array of objects) | Required (1 n) | This object specifies the locations where a signature must be placed. | Array of objects |
| Id | Required | The id of the location where a signature must be placed by this person. | String |
| LegalNoticeCode | Optional | LEGALNOTICE1 LEGALNOTICE2 LEGALNOTICE3 The 3 values will point to the 3 legal notices built into the application. These can be altered in the Configuration Index. |
String |
| LegalNoticeText | Optional | Custom legal notice text in case none of the three predefined legal notices apply. The text should be written in the same language as the one used in the documents of the package. | String |
5.5.5.6 Signing Type Specific Information
This object must only be used when Actor Type is set to Signer. It defines what kinds of signing types are allowed and it can define extra validation steps for that signing type.
Note: when any of the optional parameters are specified, all signing type objects need to contain the same values for those parameters. This is especially important for MandatedSignerValidation. When you are using choice of signing (i.e. when the signer may choose from different signing types), and you set the MandatedSignerValidation parameter to MatchId or NameAndBirthDate for one signing type, you must also set that parameter to the same value for all the other signing types for that actor, even though those signing types may not support MandatedSignerValidation.
This restriction will be solved in a future version of eSignatures, making all kinds of combinations possible.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholders --> Actors --> SigningTypes (array of objects) |
Required (1-n) | This object specifies the signing type and its related properties. | Array of objects |
| SigningType | Required | The signing type. See section 9. |
String |
| CommitmentTypes | Conditional Forbidden for XML signing |
One or more OIDs of commitment types. Can only be passed when signature policy is used. See section 5.4.13. | Array of strings |
| MandatedSignerValidation | Optional | Type of validation to execute during eID or other smart card signing session. See section 5.4.12. Values: Disabled NameAndBirthDate MatchId |
String |
| MandatedSignerIds | Conditional | Defines which eID or other smart cards are allowed to sign during this session. See section 5.4.12. Required when mandated signer validation is of type MatchId. | Array of strings |
| MatchLevel | Conditional | Can only be passed when NameAndBirthDate is used as MandatedSignerValidation. This parameter determines how accurately the actor’s FirstName and LastName must match the data retrieved from the signing certificate or signing service. Important: do not add the percentage sign to the value. A value between 90 and 95 usually produces good results. See section 5.4.12 Mandated Signer Validation for more information. |
Integer between 50 and 100 |
| SignaturePolicyId | Optional | Signing policy details for the signature. The default SignaturePolicyId is set by Connective in the Configuration Index. See section 5.4.13 for more information. If clients want to use a custom Signature Policy, they need to log a service request at Connective. | String |
5.5.6 Example request 1
In this example request, one actor named John Doe will sign on two locations (i.e. 2 documents) using BeId or Manual as signing type.
For location 1, a specific legal notice is defined which takes precedence over the legal notice set on Actor level. For location 2, no specific legal notice is defined, and the legal notice set on Actor level will be used. Note that the legal notice set on Location level will take precedence over the legal notice set on Actor level.
{
"Stakeholders": [
{
"FirstName": "John",
"LastName": "Doe",
"EmailAddress": "john.doe@example.org",
"Language": "en",
"BirthDate": "1972-09-24",
"ExternalStakeholderReference": "C0004105",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"Locations": [
{
"Id": "68f35693-5530-4770-b8d8-76284719e524",
"LegalNoticeCode": "LEGALNOTICE1"
},
{
"Id": "2e000002-fae3-46e1-ba01-5b592bf8dc32",
"LegalNoticeCode": "LEGALNOTICE2"
}
],
"SigningTypes": [
{
"SigningType": "beid"
},
{
"SigningType": "manual"
}
],
"SendNotifications": true
}
]
}
]
}
5.5.7 Example request 2
This example request displays a complex signing use case: John Doe will use BeId to sign his recruitment contract at MyCompany. Once he has signed, Jane Jefferson (the CEO of MyCompany) and Bob Smith (the HR Officer of MyCompany) must countersign the contract. The OrderIndex value determines John Doe must sign first; he has the lowest OrderIndex value. Then, the two other actors must sign. The order in which they do has no importance – since the OrderIndex value is the same for both, but higher than the one for John Doe.
{
"Stakeholders": [
{
"FirstName": "John",
"LastName": "Doe",
"EmailAddress": "john.doe@example.org",
"Language": "en",
"ExternalStakeholderReference": "Employee",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"Locations": [
{
"Id": "68f35693-5530-4770-b8d8-76284719e524"
},
{
"Id": "2e000002-fae3-46e1-ba01-5b592bf8dc32"
}
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
},
{
"FirstName": "Jane",
"LastName": "Jefferson",
"EmailAddress": "jane.jefferson@mycompany.org",
"Language": "en",
"ExternalStakeholderReference": "CEO",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"Locations": [
{
"Id": "76284719e524-5530-4770-b8d8-68f35693"
}
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
},
{
"FirstName": "Bob",
"LastName": "Smith",
"EmailAddress": "bob.smith@mycompany.org",
"Language": "en",
"ExternalStakeholderReference": "HR Officer",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"Locations": [
{
"Id": "55304486e524-5530-4770-b8d8-68f35748"
}
],
"SigningTypes": [
{
"SigningType": "BeId",
"MandatedSignerValidation": "Disabled"
}
],
"SendNotifications": true
}
]
}
]
}
5.5.8 Example request 3
In this example request, a PersonGroup containing 3 persons has been created. Any of the listed persons will be able to sign the package using either beid or manual signing.
{
"Stakeholders": [
{
"Type": "PersonGroup",
"PersonGroupName": "APIGroup",
"Persons": [
{
"FirstName": "John",
"LastName": "Smith",
"EmailAddress": "John.Smith@email.com",
"Language": "nl",
"BirthDate": "1980-10-21",
},
{
"FirstName": "Jane",
"LastName": "Jefferson",
"EmailAddress": "Jane.Jefferson@email.com",
"Language": "nl",
"BirthDate": "1985-05-05",
},
{
"FirstName": "Joe",
"LastName": "Doe",
"EmailAddress": "Joe.Doe@email.com",
"Language": "nl",
"BirthDate": "1990-07-05",
},
],
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"Locations": [
{
"Id": "68f35693-5530-4770-b8d8-76284719e524",
"LegalNoticeCode": "LEGALNOTICE1"
}
],
"SigningTypes": [
{
"SigningType": "beid"
},
{
"SigningType": "manual"
}
],
"SendNotifications": true
}
]
}
]
}
5.5.9 Example request 4
This example is the same as Example request 1, with the difference that the package is first sent to approver Jane Jefferson before being sent signer John Doe.
If the package is approved, the signer will receive a signing invitation email. If the approver rejects the package, the signer won’t be notified, since there is no package to sign. The initiator who sent the package will be notified however.
{
"Stakeholders": [
{
"FirstName": "Jane",
"LastName": "Jefferson",
"EmailAddress": "jane.jefferson@example.org",
"BirthDate": "1980-09-23",
"Language": "en",
"Actors": [
{
"Type": "Approver",
"OrderIndex": 1,
“SendNotifications": true,
}
]
},
{
"FirstName": "John",
"LastName": "Doe",
"EmailAddress": " john.doe@example.org ",
"Language": "en",
"BirthDate": "1972-09-24",
"ExternalStakeholderReference": "C0004105",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 2,
"Locations": [
{
"Id": "68f35693-5530-4770-b8d8-76284719e524",
"LegalNoticeCode": "LEGALNOTICE1"
},
{
"Id": "2e000002-fae3-46e1-ba01-5b592bf8dc32",
"LegalNoticeCode": "LEGALNOTICE2"
}
],
"SigningTypes": [
{
"SigningType": "beid"
},
{
"SigningType": "manual"
}
],
"SendNotifications": true
}
]
}
]
}
5.5.10 Response parameters
| Parameter | Content / Description | Type |
|---|---|---|
| None | Empty object |
5.5.11 Example response
{ }
5.5.12 Response codes
| Response status code | Description |
|---|---|
| 200 OK | The process information has successfully been added to the package. |
| 400 Bad Request | There are invalid parameters in the request. |
| 404 Not Found | When an unknown package id is passed. |
| 409 Conflict | Some parameters conflict with the data found in the database or configuration. |
5.5.13 Error codes
| HHTP Code | Code |
|---|---|
| 400 | Request.RequiredFieldIsMissing |
| 400 | Request.ShouldBeEmpty:[Data field] |
| 400 | Stakeholder.BirthDayInFuture |
| 400 | Stakeholder.UnsupportedLanguage |
| 400 | SigningField.InvalidPage |
| 400 | SigningType.Invalid |
| 400 | Stakeholder.EmailAddressInvalid |
| 400 | SignaturePolicy.MissingUserRole |
| 400 | SignaturePolicy.MissingCommitmentType |
| 400 | Signer.ParameterCannotBeUsedWithoutSignaturePolicy |
| 400 | Actor.TypeInvalid |
| 400 | Actor.MissingPhoneNumber |
| 409 | MandatedSigner.BirthDateMissing |
| 409 | MandatedSigner.MandatedSignerIdMissing |
| 409 | SignaturePolicy.NotFound |
| 409 | CommitmentType.NotAllowed |
| 409 | PhoneNumber.Invalid |
| 409 | Location.NotFound |
| 409 | SignaturePolicy.ShouldBeSameForActor |
| 409 | CommitmentType.ShouldBeSameForActor |
| 409 | SigningType.Disabled |
5.5.14 Mandated signer validation
These parameters haven't changed. See section 5.4.12.
5.5.15 Signature Policies and Commitment Types
These parameters haven't changed. See section 5.4.13.
5.5.16 Redirect URL Details
These parameters haven't changed. See section 5.4.14.