# Signicat forms
It is possible to create a signing order containing a PDF document with an interactive form. You specify the presence of a form when you create the signing order. Optionally, you can set pre-filled values for some or all fields. Pre-filled fields are usually used in combination with read-only fields, so the end-user can see the information but not modify it.
When you create the PDF document, you define form fields and their properties, such as fonts and sizes and whether a field should be read-only.
The end-user completes the signing ceremony through the signing interface, just like with a regular signature request. Note that documents that contain interactive forms can only have one signer.
You can then retrieve the original PDF containing the interactive form, the generated/merged/flattened version and the signed result, as well as the values used in the merging/flattening. One difference to regular signature requests is that the response of the
getStatus API call will contain the names and values of the fields. You can use these to validate the provided data.
# Detailed description
# Creating the signing order
To activate forms functionality, you will need to fulfil prerequisites to both the specification of the signing order and the PDF document.
# Signing order prerequisites
documentelement must contain the
formelement for the given document to be treated as a document containing a form. In other words, even if you suppliy a PDF containing an interactive form, this form will be ignored if the
formelement is not included.
idattribute of the
formelement must be set to the string
interactive. Optionally, the form element may contain one or more
input-paramelements. This is detailed further down.
# Example of a
documentelement containing the
<document id="doc-1" type="provided-document" mime-type="application/pdf"> <description>Simple form document</description> <data>[REMOVED FOR BREVITY]</data> <form id="interactive"/> </document>
# PDF document prerequisites
The supplied PDF document must contain interactive form fields (AcroForm fields). The supported field types are:
- text field
- radio button
All fields must be empty, i.e. text fields must be empty, checkboxes and radio buttons must be unchecked and choice fields cannot have an initial option set as selected. To set initial values, you must use form input parameters (as described below).
You can mark fields as read-only, in which case the end-user will not be able to edit the field. You should typically combine this with a form input parameter, to avoid empty read-only fields.
# Optional form input parameters
Fields can have an initial value set by supplying it as a form input parameter. You can do this by adding an
input-param element to the
form element for the given field.
The name of the field is given in the
name attribute and the value is given in the
value attribute. These values will be pre-filled in the given fields when the PDF is presented to the end-user.
The end-user will be able to change these values before submitting/saving the form, unless the field is marked as read-only.
# Example of a
document element containing input parameters
<document id="doc-1" type="provided-document" mime-type="application/pdf"> <description>Form document with input params</description> <data>[REMOVED FOR BREVITY]</data> <form> <input-param name="first-name" value="James"/> <input-param name="last-name" value="Raynor"/> <input-param name="email" value="firstname.lastname@example.org"/> </form> </document>
# Form validation
You can specify form fields as
required in the PDF. If a document contains one or more required form fields, the end-user will not be allowed to complete the signing process before the required fields have been filled in.
Form fields can contain up to 256 characters. This applies both to fields completed by the end-user and to pre-filled values that you supplied as part of the signing order.
The end-user will not be allowed to complete the signing process if any form fields exceed the character limit.
# Creating a form
The below screenshots show an example of the creation of a form using the Prepare form (opens new window) functionality in Adobe Acrobat.
# End-user signing ceremony
The below screenshots show an example for an end-user signing ceremony where the end-user fills in a form and signs with Norwegian BankID and Signed statement. The final screenshot is an example of the flattened result.
# Retrieving the result
As with any other signing order, once the end-user has completed the signing process,you can obtain the result via a
getStatus call. For each document, the response will contain URLs for both the original document as well as the SDO (signed data object).
In addition, if the document is a form document, all form parameters used in the flattening process will be returned as
form-output-param elements. This way, you can obtain the data values that the end-user has supplied in a structured format for further processing.
Values supplied by the end-user will take precedence over pre-filled values supplied by you.
# Example of output parameters in the
<document-status id="doc-1"> <original-uri>[URL TO ORIGINAL DOCUMENT]</original-uri> <result-uri>[URL TO SIGNED DATA OBJECT]</result-uri> <form-output-param name="first-name" value="James"/> <form-output-param name="last-name" value="Raynor"/> <form-output-param name="email" value="email@example.com"/> <form-output-param name="mood" value="grumpy"/> <form-output-param name="drunk" value="yes"/> </document-status>