5.1 Create Package
5.1.1 Description
This call creates an empty package, allowing documents to be added to it.
Notes:
- A package must not exceed 150 MB.
- A package must not contain more than 15 documents and each document must not exceed 30 MB.
- An .xml file must not contain more than 2 million characters per file. A package must not contain more than 15 .xml files.
- Large files might affect signing performance depending on the user's Internet connection.
5.1.2 URL
https://[servername]:[port]/webportalapi/v3/packages
5.1.3 HTTP Method
POST
5.1.4 MIME Type
application/json
5.1.5 Request parameters
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Initiator | Required | Email address of a registered user. | String |
PackageName | Required | Package name, seen in the eSignatures Portal and when downloading as zip file. Note: do not add an extension to the PackageName value. Important: Pay attention when choosing a package name. Don’t use forbidden file name characters such as slash (/), backslash (), question mark (?), percent (%), asterisk (*), colon (:), pipe (), quote (‘), double quote ("), less than (<), greater than (>). Note however, that is list is not exhaustive. Don’t use characters that are HTML-sensitive such as ampersand (&) or apostrophe (‘). Note: when using itsme signing, only use characters that are supported by ISO 8859-15. This character set supports most usual characters, but some software-generated characters like curly apostrophes and long dashes are not supported. |
String |
CallBackUrl | Optional | REST API URL that will be called each time an action has been completed for this package, if no URL is supplied no call back is performed. See section 5.1.11 Package Callback Details below. | String |
CorrelationId | Optional | Id that indicates which packages are correlated. The CorrelationId can be used in a GET call to retrieve the Audit proof file (a signed .xml file) about all correlated packages. See section 7. Audit proofs for more information about the audit proofs and the corresponding calls. Important: the Audit proofs setting must be enabled in the Configuration Index to use this parameter. If it is disabled, entering the CorrelationId will return an error. |
String |
DocumentGroupCode | Optional | The ‘Code’ which identifies a document group in which the package should be shown. Default is “00001” to signify “My Documents”. See section 6.1: Get DocumentGroups. | String |
ThemeCode | Optional | Theme that must be applied to the package. | String |
DownloadUnsignedFiles | Optional | This parameter determines whether packages can be downloaded from the WYSIWYS before approving/signing. Enter ‘true’ if you want actors to be able to download the package before approving/signing. This way they can print it and read it on paper for instance. Enter ‘false’ to hide the download icon and prevent actors to be able to download packages from the WYSIWYS. When no value is entered, this parameter takes it value from the Config Index setting IsDownloadUnsignedFilesEnabled under Customization Settings. |
Boolean |
ReassignEnabled | Optional | This parameter determines whether packages can be reassigned from the WYSIWYS to another approver/signer. Enter ‘true’ if you want actors to be able to reassign the package. Enter ‘false’ to hide the reassign button and prevent actors to be able to reassign packages from the WYSIWYS. When no value is entered, this parameter takes it value from the Config Index setting IsReassignEnabled under Customization Settings. |
Boolean |
ActionUrlExpirationPeriodInDays | Optional | This parameter determines after how many days the action URLs must expire when they are not used. When no value is entered, this parameter takes its value from the Config Index setting IsActionUrlExpirationEnabled under Customization Settings. |
Integer |
ExpiryTimestamp | Optional | The date and time when this package expires and can no longer be approved/signed. Documents in packages all use the value given here. Format is ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z |
String with Date+Time +Offset |
ExternalPackage Reference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
ExternalPackageData | Optional | This field is reserved for future use. It can be used for customer-specific extensions to integrate with third-party services, such as Debit Card signing. It is not part of a standard eSignatures installation and should not be used in calls. | String |
F2FRedirectUrl | Optional | URL to which the end user is redirected after all fields have been signed with 'face to face' signing, or when all fields have been rejected. The redirect occurs immediately after signing or rejected. This field must be a valid absolute url. Attention: don't confuse the F2FRedirectUrl with the 'regular' RedirectUrl. The F2FRedirectUrl only applies to face to face signing. The RedirectUrl applies to regular signing and is set in the Set Process Information call. See section 5.4 Set Process Information > 5.4.14: Redirect URL Details for more info. Note: during asynchronous signing, the signer has the possibility to close the signing session - by means of a Close button - while the signing continues in the background. The purpose of a redirect url however is to redirect the signer to a new url after the signing has finished. Therefore, when a F2FRedirectUrl is configured, the Close button will be unavailable, and a message is displayed informing the signers they will be redirected. |
String |
NotificationCallBackUrl | Optional | REST API URL that will be called when an end user requests to be notified. If no URL is supplied, no call back is performed. See section 5.1.12 Notification Callback Details below. |
String |
5.1.6 Response parameters
Parameter | Content / Description | Type |
---|---|---|
PackageId | Unique identifier of the package. | String |
CreationTimestamp | Date and time when the package was created according to the server. Format is ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z |
String |
5.1.7 Example request
{
"PackageName": "Contracts Mr. Doe",
"Initiator": "info@mail.com",
"DocumentGroupCode": "00001",
"ExternalPackageReference": "2019-CR-5891"
}
5.1.8 Example response
{
"PackageId": "25892e17-80f6-415f-9c65-7395632f0223",
"CreationTimestamp" : "2019-02-28T14:05:11+00:00"
}
5.1.9 Response codes
Response status code | Description |
---|---|
201 Created | The package was created successfully. The URL for the new package is available in the Location header. |
400 Bad request | The package could not be created due to invalid parameters in the request. |
409 Conflict | The package could not be created due to an invalid document group code or unknown email address for the initiator. |
5.1.10 Error codes
HTTP Code | Code |
---|---|
400 | Request.RequiredFieldIsMissing |
400 | Package.ExpiryTimestampInvalid |
400 | Package.ExpiryTimestampInPast |
400 | Url.Invalid |
409 | DocumentGroup.NotFoundWithCode |
409 | User.NotFound |
5.1.11 Package Callback Details
The Callback URL is used to contact external systems. When certain status changes happen, the given URL will be used to send an HTTP POST request, informing the external system that a change has taken place.
A callback may happen in the following cases:
- The package has its status changed to “Pending” through the eSignatures Portal
- The package is revoked through the eSignatures Portal
- One of the signers completed signing all their fields
- All signers have finished signing
- The package is rejected by one of the signers
- The package has its status changed to "Failed" through the eSignatures Portal
Note: API requests explained in this document will never trigger a callback. It is only when an end user triggers an action in the eSignatures Portal or signing screen that a callback will happen. Other triggers might be added in the future.
Currently the POST request sends an empty body with content type text/json. The external system must then fetch the current state of the package by inspecting the query parameters of the POST request and invoking the "Get Package Status" call from section 5.8 with the provided package id.
The base URL (without parameters) is appended with the following query parameter:
- PackageId (the id of the package as returned by the Create Package call)
The callback url must contain a valid, absolute URL with no parameters.
For example, if the CallBackUrl parameter contains the following URL:
https://myhost.example.org/services/callback
then the effective callback URL will be:
https://myhost.example.org/services/callback?PackageId=6aaa6664-22f8-4a4e-8b02-a1babd8eabb1
Important: For performance and scalability purposes, a Callback timeout has been introduced and is set to 100 seconds. This way, if the driving application doesn’t respond to eSignatures’ callback, a timeout will be forced, and the rest of the flow will be finished as if the expected 200 OK message were received. If eSignatures were to wait indefinitely for a response to finish the package, its performance would drop drastically.
For this reason, it’s highly recommended that the client’s callback service is developed in such a way that it sends its response as soon as possible. Any other actions done by the callback service must not depend on the response being sent but should function asynchronously.
Note: in case a Callback error should occur, eSignatures now by default retries to do the callback 3 times, during 3 retry cycles. System administrators may customize this retry mechanism in the Worker config file. See Connective - eSignatures 5.5.x - Installation Documentation - Limited Public – OP for more information.
5.1.12 Notification Callback Details
The Notification Callback parameter, if specified, will in certain cases override the usual behavior of sending out emails and triggers a remote service instead. The remote service must then retrieve information about the package and choose what to do (see section 5.8 for the Get Package Status call).
While the normal callback is called for major state changes, the notification callback can be called multiple times without any apparent change. For that reason, the callback includes information about the type of notification which was requested.
The remote server is called only once per user action; there is no retry unless the end user requests a new notification.
Note: this callback system may at one point be superseded by a more generic extension mechanism for notifications. At that point only the more generic mechanism will receive improvements.
Note: eSignatures waits for this remote service to complete its job before returning control to the end user. Therefore the remote service needs to give a response within seconds.
A callback consists of a POST request to the specified URL with content-type application/json. The following parameters are available in the JSON body:
Parameter | Content / Description | Type |
---|---|---|
packageId | Unique identifier of the package | String |
actorId | Identifier of the actor for which the notification was triggered | String |
language | The language which the end user was told to use (see the Language parameter in the Stakeholder object of the Set Process Information call). | String |
notificationType | Which kind of notification was requested | Integer |
notificationTypeKey | Which kind of notification was requested | String |
A callback may currently happen in the following cases:
(Note that the number in the left column is the id.)
NotificationTypeKey | NotificationType | Use Case |
---|---|---|
SendSignerUrl | 0 | The single-use signing link has been used already and the end user requested a new link. |
SendDownloadUrl | 1 | The single-use download link has been used already and the end user requested a new link. |
Note: since this list may grow in the future, the remote service will need to ignore other types without returning an error response.
Note: other use cases will not send a callback until explicitly listed in the table above. The existing emails sent when a package is created, revoked, etc. will depend on the SendNotifications parameter which is separate from the NotificationCallbackUrl.
Note: due to circumstances, the notification type ended up being a number rather than a string. The current numeric values will remain supported until eSignatures 6, but know that eSignatures 5.1 has included a new parameter NotificationTypeKey which contains a string-typed identifier.
Note: in case a Callback error should occur, eSignatures now by default retries to do the callback 3 times, during 3 retry cycles. System administrators may customize this retry mechanism in the Worker config file. See Connective - eSignatures 5.5.x - Installation Documentation - Limited Public – OP for more information.