5.7 Instant Package Creation
5.7.1 Description
This call creates a package with a single document in it and instantly prepares it for approval/signing.
The response is nearly the same as Get Package Status (with the addition of the package id), saving an extra call.
Notes:
- A document must not exceed 30 MB.
- A document must not contain more than 30 signing fields.
- A document’s physical dimensions must not exceed 3.99 m by 3.99 m.
- An .xml document must not contain more than 2 million characters per file.
- Large files might affect signing performance depending on the user’s internet connection.
Signature field locations can be set either using coordinates in the document or the id of an object in the document. See section 10 for more info.
The supported upload document formats are docx, doc, pdf, plain text, and xml.
Note: some of these formats might be disabled in the eSignatures configuration.
Remarks:
Uploading PDF/A documents is only allowed if the format is PDF/A_2A or PDF/A_1A. When using itsme as signing method, it is mandatory to use PdfA1A or PdfA2A as TargetType. Note however that Connective does not perform any checks whether this TargetType has been selected.
Rotated PDFs should not be used together with text markers. Detected signing fields will not be rotated to match the PDF text direction but will be placed near the text marker on a best-effort approach.
When you upload PDF documents that contain Text Fields of which the name/id complies with the Text Field format you have configured in the Configuration Index, the Text Fields will be converted to empty signature fields in the output document and the original Text Field will not be displayed. This is intended behavior.
Note: in case you upload a document that already contains one or more signatures – whether they have been created in eSignatures or another signing application – the remark above does not apply.
When uploading PDF documents that already contain signature fields - which you created in a PDF solution such as Adobe Acrobat Pro DC - make sure the signature field names only contain letters and numbers, or a combination of both. Any special characters such as accented letters, slashes, dots, etc. are not supported and must not be used. The same limitations apply when uploading PDF documents that contain text fields.
5.7.2 URL
https://[servername]:[port]/webportalapi/v3/packages/instant
5.7.3 HTTP Method
POST
5.7.4 MIME Type (JSON + Base64)
application/json
5.7.5 MIME Type (Multipart)
multipart/form-data
This call expects the same input and will deliver the same output as the non-multipart version above, but the Document or Representation parameter in the JSON must not contain base-64 encoded file data. Instead the call will expect the document to be included as a different “part” of the request.
| Request entity | Content type | Description |
|---|---|---|
| Data | application/json;charset=utf 8 | Json request |
| Document | application/octet-stream | Document that needs to be signed |
| Representation | application/octet-stream | A PDF to be shown together with the document to be signed. See the Representation parameter below for its restrictions. |
Note: eSignatures v5.1 and earlier looked for a part named 'pdf'. This is deprecated but still works.
5.7.6 Request parameters
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Document | Conditional | Attached document in base64 encoded format. Required unless Multipart format is used. |
String |
| DocumentLanguage | Required | Language to use in signature texts. Currently supported: en, nl, de, fr, es. This is also the language that will be used for legal notices when LegalNoticeCode is filled. |
String |
| DocumentName | Required | Name of the document and package to be shown in the eSignatures Portal. Note: do not add an extension to the DocumentName 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 |
| Initiator | Required | Email address of a registered user | String |
| Stakeholders | Conditional | Information about the people who are involved in the process. See section 5.7.6.1. below Normally required, but using a template will make this parameter forbidden. |
Array of objects |
| 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. | String |
| CorrelationId | Optional | Id that indicates which packages or documents are correlated. The CorrelationId can later be used to retrieve all related Audit proofs. See section 7 for more info. In this request the parameter will be used as packaged and document correlation id. Important: the Audit proofs setting must be enabled in the Configuration Index to use this parameter. |
String |
| DocumentGroupCode | Optional | The ‘Code’ which identifies a document group in which the document 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 signing. Enter ‘true’ if you want signers to be able to download the package before signing. This way they can print it and read it on paper for instance. Enter ‘false’ to hide the download icon and prevent signers 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 signed. Note that this must be an ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z | Date+Time+Offset |
| ExternalDocumentReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. Make sure to use a unique value. |
String |
| ExternalPackageReference | Optional | Reference given by the calling application, this parameter will not be used by the eSignatures Portal. Make sure to use a unique value. |
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 rejecting. 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.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. |
String |
| PdfErrorHandling | Optional | How to deal with PDFs containing minor flaws. See section 4 for more info. Values: Ignore DetectWarn DetectFail DetectFixWarn DetectFixFail |
String |
| Representation | Optional Only allowed for XML signing |
Attached representation document in base64 format. This must be PDF data. | String |
| RepresentationType | Conditional | Type of the representation document, must be present when Representation is filled. Only “application/pdf” is supported. | String |
| SigningTemplateCode | Optional Forbidden for XML signing |
The template configured in the portal will provide all necessary information. The SigningTemplateCode can either be retrieved in the portal or via the Get signing templates call. See 6.2 Getting Signing Templates (Paginated) for more info. When you use this parameter, further use of the StakeHolders parameter will be forbidden. |
String |
| TargetType | Optional | The TargetType defines if an extra conversion to PDF/A needs to be done before signing. Values: PdfA1A PdfA2A Notes This will only work when the Document Conversion settings have been enabled in the Configuration Index. When using itsme as signing method, it is mandatory to use PdfA1A or PdfA2A as TargetType. Note however that Connective does not perform any checks whether this TargetType has been selected. |
String |
5.7.6.1 Stakeholder information
The following parameters specify which stakeholder will sign or receive this package.
Since eSignatures 5.4.2, 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/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.
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 |
|---|---|---|---|
| Stakeholders (array of objects) | Required (1-n) | Information about the people who are involved in the process. | Array of objects |
| Actors | Required (1-n) | Array of actor objects. See below. | Array of objects |
| Type | Optional | Stakeholder type: Person | String |
| EmailAddress | Required | Email address of the signer. | String |
| FirstName | Required | First name | String |
| Language | Required | UI language of the stakeholder. Currently supported: en, nl, de, fr, es. |
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. |
|
| ExternalReference | Optional | Reference given by the calling application, this parameter will not be used by the eSignatures Portal. | String |
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 approve/sign the package for the entire group. All persons listed in the Persons array will receive a unique URL to approve/sign their document.
Attention: As soon as one person has taken action on 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 sign. | 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. | 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 |
| ExternalReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
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. | String |
5.7.6.2 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 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 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. |
Boolean |
| 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. |
Strin |
| 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 automatically 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 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 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. |
Integer |
| SigningFields | Required | Define the locations where this actor should sign. See section 5.7.6.3 below. | Array of objects |
| SigningTypes | Required (1-n) for Signer | 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: AfterCompletion (default), AfterDelay, Immediately. By default, actors are redirected AfterCompletion. 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 are allowed to sign. Such notifications can be enabled or suppressed by setting this parameter as ‘true’ or ‘false’ (the default is ‘false’). | Boolean |
| UserRoles | Conditional | Role or function of the signer. Note: only allowed if signature policy id is present. See section 5.4.13 below. | Array of strings |
| LegalNoticeCode | Optional Forbidden for XML signing |
LEGALNOTICE1 LEGALNOTICE2 LEGALNOTICE3 The 3 values will point to the 3 notices built into the application. These can be altered in the Configuration Index. Important: it is highly recommended not to combine legal notices and signature policies in API calls. This is not compliant with the ETSI standard. Should you still want to do this, to combine itsme signing with a legal notice for instance, the setting CombineLegalNoticeAndSigningPolicy must be enabled in the Configuration Index. |
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. Important: it is highly recommended not to combine legal notices and signature policies in API calls. This is not compliant with the ETSI standard. Should you still want to do this, to combine itsme signing with a legal notice for instance, the setting CombineLegalNoticeAndSigningPolicy must be enabled in the Configuration Index. |
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.7.6.3 Signing Field Position
PDF Signing
Signature field locations can be set on PDFs either using coordinates in the document or using the id of an object in the document. See section 10 for more info. When placing a field on a PDF it should at least be 112 points wide and 70 points high. Note: it is recommended to use slightly higher values than the minimum ones. E.g. 75 points x 120 points. Using the absolute minimum values may lead to round-off errors during conversions.
If no MarkerOrFieldId parameter is specified, then all the other fields will be required. When the MarkerOrFieldId parameter is specified then all other parameters are forbidden.
Invisible PDF Signing
When the SigningType parameter is set to Server for all actors, it is possible to sign the document without adding a visible signing field. In this case, the PDF will be signed, and the signature can be checked but it will not be visible on the document.
To leave the visible signing field out, all parameters of the SigningFields parameter must be omitted.
Note that this feature is only available in Instant Packages
XML Signing
XML signing does not allow for coordinates or markers to form a visual signature, instead all signature data will become part of the XML document and be added at the end. Therefore, this parameter should be empty when signing XML. The API will make one location for each actor in the call.
| Parameter | Occurrence | Content / Description | Type |
|---|---|---|---|
| Stakeholder--> Actors--> SigningFields (array of objects) |
Required (1-n) | One or more signing locations in the document | Array of objects |
| PageNumber | Conditional | Number of the page on which to add a signing location. First page is number 1. Negative page numbers work as described in section 10.1. | Integer |
| Width | Conditional | Width Minimum value is 112. It is recommended to use slightly higher values than the minimum ones. |
String |
| Height | Conditional | Height Minimum value is 70. It is recommended to use slightly higher values than the minimum ones. |
String |
| Left | Conditional | Position from the left of the page. Minimum value is 1. Negative values are not supported. |
String |
| Top | Conditional | Position from top of the page. Minimum value is 1. Negative values are not supported. |
String |
| MarkerOrFieldId | Conditional | Unique reference to a signing field, text marker or textfield. See section 10.2 for more details. | String |
5.7.6.4 SigningType Specific Information
The following object 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.
Important: because of this restriction, it is not possible to combine BeLawyer and itsme signing in choice of signing when using MandatedSignerValidation. This is because BeLawyer requires MatchId as value, while itsme requires NameAndBirthDate as value.
| 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 used in this actor's session. 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 other smart card, or itsme signing session. See section 5.4.12. Values: Disabled NameAndBirthDate MatchId Note that MatchId is not supported for itsme. |
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 string |
| 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 Forbidden for XML signing |
Signing policy details for the signature. See section 5.4.13. Important: it is highly recommended not to combine legal notices and signature policies in API calls. This is not compliant with the ETSI standard. Should you still want to do this, to combine itsme signing with a legal notice for instance, the setting CombineLegalNoticeAndSigningPolicy must be enabled in the Configuration Index. |
String |
5.7.7 Example Request
5.7.7.1 Regular Request
{
"DocumentLanguage": "en",
"DocumentName": "instant package",
"Initiator": "john.smith@mail.com",
"ExternalPackageReference": "reference",
"Stakeholders": [
{
"FirstName": "John",
"LastName": "Smith",
"EmailAddress": "john.smith@mail.com",
"BirthDate": "1974-04-12",
"Language": "en",
"Type": "Person",
"ExternalStakeholderReference": "stakeref",
"Actors": [
{
"Type": "Signer",
"OrderIndex": 1,
"SigningFields": [{//"Width": "110", "Height": "50", "PageNumber": 1, "Left": "391", "Top": "741",
"MarkerOrFieldId": "SIG01",
},
],
//"legalnoticetext": "custom[draft]",
"SigningTypes":
[
{
"SigningType": "manual",
//"MandatedSignerValidation": "matchid",
//"MandatedSignerIds": ["ee32ee8e-deed-4605-a2e5-fbeed3cbd82a","c488d53fb75f466eaaf4f130426d407a","94092339579"],
//"MatchLevel": 80,
//"CommitmentTypes": ["1.2.840.113549.1.9.16.6.5"],
//"SignaturePolicyId": "1.3.6.1.4.1.35390.10.2.3.2.0"
},
],
"Phonenumber": "+32465232553",
"SendNotifications": true,
},
]
},
],
"Document":""
}
5.7.7.2 Request with SigningTemplateCode
In this example you'll notice that the stakeholder block is not present (since that info is covered by the template).
{
"Document": “ Base64 of your document”,
"DocumentLanguage": "en",
"DocumentName": "Instant doc",
"Initiator": "Jon.Doe@mail.com",
"DocumentGroupCode": "00052",
"ExpiryTimestamp": "2019-06-25T15:00:28+00:00",
"ExternalDocumentReference": "MyDocument",
"RedirectUrl": "https://www.mycompany.com",
"TargetType": "PdfA2A"
"PdfErrorHandling": "DetectFixFail",
“SigningTemplateCode": "00001",
}
5.7.8 Example Response
"PackageId": "3bb6a2d1-35db-4a3a-a434-868c01bcca9d",
"PackageName": "instant package",
"Initiator": "john.smith@mail.com",
"ExpiryTimestamp": null,
"ExternalPackageReference": "reference",
"F2FSigningUrl": "https://yourFTFSignUrl",
"PackageStatus": "Pending",
"PackageDocuments": [
{
"DocumentId": "97cfc102-70c2-4c17-9fb7-74b29360d53f",
"DocumentType": "application/pdf",
"ExternalDocumentReference": null,
"DocumentName": "instant package",
"Locations": [
{
"Id": "e3ba68ac-e737-4e15-b61f-229034cf0797",
"Label": "d28d483a-824d-43c9-93d1-026117d8ebaf",
"PageNumber": 2
}
]
}
],
"Stakeholders": [
{
"Type": "Person",
"EmailAddress": "john.smith@mail.com",
"ContactGroupCode": null,
"ExternalStakeholderReference": "stakeref",
"StakeholderId": "7aa76f03-7981-44c1-8b91-598256edf260",
"Actors": [
{
"Type": "Signer",
"Reason": null,
"CompletedBy": null,
"CompletedTimestamp": null,
"Locations": [
{
"Id": "e3ba68ac-e737-4e15-b61f-229034cf0797",
"UsedSigningType": null
}
],
"ActorId": "db4a380f-fbd8-4bd7-b9e3-23507e986f66",
"ActionUrl": "https://ActionUrl",
"ActionUrls": [],
"ActorStatus": "Available"
},
],
"PersonGroupName": null
}
],
"CreationTimestamp": "2019-10-24T11:20:55Z",
"Warnings": []
}
5.7.9 Response parameters
| Parameter | Content / Description | Type |
|---|---|---|
| PackageId | Unique id of the package | String |
| PackageName | Description for the Package shown to the eSignatures Portal user as file name. | 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 |
| Initiator | Initiator field of the package as it was passed in at creation time. | String |
| ExpiryTimestamp | UTC formatted time at which the document expires. Can be null. | String |
| ExternalPackageReference | Returns the external reference id of the package as it was passed in at creation time. | String |
| F2FSigningUrl | Link to the package which allows to pick from all the signing session at once. | String |
| PackageStatus | Status of the package as a whole: Draft Pending Finished Rejected Revoked Expired Failed Note: a package has the status Failed when a background operation has failed and left a message on the Poison Queue. | String |
| PackageDocuments | Details for each of the documents in the package. | Array of objects |
| Stakeholders | Details for each of the people who will interact with the package. | Array of objects |
| Parameter | Content / Description | Type |
|---|---|---|
| PackageDocuments (array of object) | Details for each of the documents in the package. In case of an instant package there is always 1 document. | Array of objects |
| DocumentId | Unique id of the document | String |
| ExternalDocumentReference | Returns the external reference of this document as it was passed in through the Add document to package call. | String |
| DocumentName | Name of the document | String |
| DocumentType | Type of the document | String |
| Locations | See table below. | Array of objects |
| Parameter | Content/Description | Type |
|---|---|---|
| Locations (array of objects) | Represents a possible location for a signature | Array of objects |
| Id | Unique id for this location | String |
| Label | Value you entered as Request parameter | String |
| PageNumber | Number of the page on which the signature can be found | Int |
| Parameter | Content / Description | Type |
|---|---|---|
| Stakeholders (array of objects) | Details for each of the persons which will interact with the package. | Array of objects |
| Type | Type of stakeholder: Person, PersonGroup or ContactGroup. | String |
| PersonGroupName | Name of the person group. Only returned if Type was set to PersonGroup in the request. | String |
| ContactGroupCode | Code of the contact group. Only returned if Type was set to ContactGroup in the request. | String |
| EmailAddress | Email address of the signer. | String |
| ExternalStakeholderReference | External reference identifying this person in the external system. | String |
| StakeholderId | Unique id | String |
| Actors | See below | Array |
| Parameter | Content / Description | Type |
|---|---|---|
| Stakeholders => Actors (object) | Details of all steps to take. | Array of objects |
| ActorId | Unique id for this combination of action, stakeholder and document. | String |
| ActionUrl | URL that this person can open to interact with the package. This parameter is only used when Stakeholder Type is set to Person, or not passed at all. When the Stakeholder Type is set to PersonGroup or ContactGroup, the ActionUrl will be null and the different Urls sent to the different persons are listed in the ActionsUrls array. Exception: if the PersonGroup or ContactGroup only contains 1 person, the ActionUrl parameter will still be returned instead of the ActionUrls. |
String |
| ActionUrls | Array of URLs that the different persons of the PersonGroup or ContactGroup can open to interact with the package. See the table below. |
String |
| ActorStatus | Draft (package has status Draft) Inprogress (package is being signed) Available (ready for execution) Finished Rejected (signing cannot continue) Failed (signing has failed) Skipped (Initiator skipped the actor) | String |
| Type | Signer Receiver |
String |
| CompletedBy | The name of the end user who completed the action. This can only be properly filled when an authenticated signing method is used like BeId or Idin. Can be null, will never be present for a Receiver. | |
| CompletedTimestamp | Timestamp of the moment on which this action was completed. Format is ISO 8601 date-time. E.g. 2018-01-23T12:34:00.000Z Can be null, will never be present for a Receiver | |
| Reason | Returns the text entered by the person who changed the status of a package to a final state (e.g. a reject). Can be null, will never be present for a Receiver. | String |
| Locations | See table below. | Array of objects |
| Parameter | Content / Description | Type |
|---|---|---|
| Locations (array of objects) | Represents a possible location for a signature. | Array of objects |
| Id | Unique id for this location. | String |
| UsedSigningType | Returns the signing type that was used to sign the document. See section 9 for an overview of the available signing types. If no signing type was used (i.e. if the document isn’t signed yet), this parameter returns “null”. |
String |
| Parameter | Content / Description | Type |
|---|---|---|
| Stakeholders => Actors => ActionUrls (array of objects) | Array of URLs that the different persons can open to interact with the package. The ActionURLs array is only used when the Stakeholder Type was set to PersonGroup or ContactGroup. Each person receives a unique URL only they can use. Exception: if the PersonGroup or ContactGroup only contains 1 person, the ActionUrl parameter will still be returned instead of the ActionUrls. | Array of objects |
| EmailAddress | Email address of the person. | String |
| Url | URL that this person can open to interact with the package. | String |
5.7.10 Response codes
| Response status code | Description |
|---|---|
| 201 Created | The package can be made ready for signing. The response contains more information about the locations where a signer can place a signature. |
| 400 Bad request | The request contained parameters which could not be accepted. |
| 404 Not Found | The package id could not be found in the database. |
| 409 Conflict | When certain document conversions are forbidden, when the input document has issues, or when marker ids are not matched. |
5.7.11 Error codes
| HTTP Code | Code |
|---|---|
| 400 | Request.RequiredFieldIsMissing |
| 400 | Document.UnsupportedLanguage |
| 400 | Package.ExpiryTimestampInPast |
| 400 | Document.InvalidTargetFileType |
| 400 | SigningField.LabelNotUnique |
| 400 | SigningField.MarkerAndCoordinatesCannotBeMixed |
| 400 | SigningField.MarkerNotUnique |
| 400 | SigningField.InvalidHeightCoordinate |
| 400 | SigningField.InvalidWidthCoordinate |
| 400 | Document.PasswordProtected |
| 400 | Pdf.UploadDoesNotComplyToSpec |
| 400 | Actor.TypeInvalid |
| 400 | SigningType.Invalid |
| 400 | Stakeholder.EmailAddressInvalid |
| 400 | Stakeholder.BirthDayInFuture |
| 400 | Stakeholder.UnsupportedLanguage |
| 400 | PdfErrorHandling.InvalidType |
| 400 | Actor.MissingPhoneNumber |
| 400 | SigningField.InvalidPhoneNumber |
| 400 | Signer.ParameterCannotBeUsedWithoutSignaturePolicy |
| 400 | SignaturePolicy.MissingCommitmentType |
| 400 | SignaturePolicy.MissingUserRole |
| 400 | SigningType.MissingSignaturePolicy |
| 400 | SigningTemplate.ForbiddenParameter |
| 400 | Url.Invalid |
| 400 | Package.ExpiryTimestampInvalid |
| 400 | Package.ExpiryTimestampInThePast |
| 409 | SigningTemplate.NotFoundWithCode |
| 409 | MandatedSigner.MandatedSignerIdMissing |
| 409 | MandatedSigner.BirthDateMissing |
| 409 | DocumentGroup.NotFoundWithCode |
| 409 | User.NotFound |
| 409 | SigningType.Disabled |
| 409 | SignaturePolicy.NotFound |
| 409 | Document.InvalidSourceFileType |
| 409 | SigningField.InvalidHeightMarker |
| 409 | SigningField.InvalidPage |
| 409 | SigningField.InvalidWidthMarker |
| 409 | Document.InvalidTargetFileType |
5.7.12 Signing Template Restrictions
Customer-specific integrations may want to avoid continuously specifying signer and receiver information by reusing a previously saved template.
Using these templates requires that there is a one-time setup in the eSignatures Template Portal. Templates can be edited by users of the eSignatures Portal when they have the appropriate permission. If that is done, the unique id of the template needs to be looked up in the UI or through the Getting Signing Templates call so that it can be passed through the SigningTemplateCode parameter in the call documented above.
When a template contains multiple signers with the same email address then the end user will see all those fields in the same package signing session. If those signers had different signing types then the end user will at signing time be able to choose one of the signing types for the entire session.
Note: signing templates work based on markers PDF documents. Because XML has no such options the use of signing templates cannot be combined with XML signing.
Note that no Signers, Receivers, or their locations can be passed to the API when a template code is specified. Doing so will make this call return an error response.