# Signicat forms

Page contents

Introduction
Detailed description
- Creating the signing order
Creating a form
End-user signing ceremony
Retrieving the result
- Example of output parameters in the document-status element

# Introduction

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

The document element must contain the form element 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 form element is not included.
The id attribute of the form element must be set to the string interactive. Optionally, the form element may contain one or more input-param elements. This is detailed further down.

# Example of a `document`element containing the `form` element

<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
- checkbox
- radio button
- choice
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).

Note

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="jimmy@hyperion.com"/>
  </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.

Important

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` element

<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="james.raynor@hyperion.com"/>
  <form-output-param name="mood" value="grumpy"/>
  <form-output-param name="drunk" value="yes"/>
</document-status>

← The document presenter Signed statement →