The signature element enables you to propose documents to be signed using an external e-signature provider (default is Connective)

In order to kick-start the addition of a signature element, I invite you to have a look at our signature element:

{
  "type": "signature",
  "key": "signatures.documents_to_sign",
  "title": "Documents to sign",
  "name": "Signed-documents",
  "items": [
    {
      "uri": "https://mydomain.com/Document_to_sign_01.pdf",
      "name": "User friendly name",
      "fill": {
        "first_name": "{user.given_name}",
        "last_name": "{user.last_name}",
        "location": "{data.address_city}",
        "today": { ":format-date": "now", ":pattern": "Y-M-D" },
        "some_checkbox": false
      },
      "signatures": [
        { "field": "SIG001" },
        { "page": 1, "top": 300, "left": 50 }
      ]
    },
    {
      "uri": "https://mydomain.com/Document_to_sign_02.pdf",
      "name": "Second document"
    }
  ],
  "merge": true,
  "method": "email",
  "required": true
}

Options

In this chapter we will focus on the different options related to our Signature element.

Specifying the name of the signature package (`name`)

This will be displayed to the user during the signature process and will be used as the name of the signed file (".pdf"). If no value is provided, the title option will be used as default. If neither name nor title are specified, "Documents" will be used as fallback.

{"name": "Signed-documents"}

Specifying the files to sign (`items`)

This will be a list of documents to be signed. It can be generated in one of two ways: from a URI or using files uploaded in a Penbox form.

Signing a file from a URI (`item.uri`)

Using a PDF or IMAGE (png / jpeg) file located on a publicly available HTTP endpoint.

{
  "type": "signature",
  // ...
  "items": [
    {
      "uri": "https://testingpenbox.s3.amazonaws.com/file_resources/files/Document_to_sign.pdf"
    }
    
    // ... more items
  ]
}

Signing a Penbox file (`item.attachment`)

Specify a (list of) file(s) to sign from a "file upload" element from a Penbox form.

Note: Only PDF and IMAGES are supported here so make sure that the file element has an "accept" option as described in the section bellow. Invalid files will be ignored.

{
  "type": "signature",
  // ...
  "items": [
    // If the file was uploaded when creating the request, use "option."
    {
      "attachments": "{ options.files_to_sign }",
    },

    // If the file was uploaded while filling the form, use "data."
    {
      "attachments": "{ data.files_to_sign }",
    },

    // ... more items
  ]
}

Specifying signature locations (`item.signatures`)

When the item to sign is defined using a "uri", the locations of the signatures within that document can also be specified.

{
  "type": "signature",
  // ...
  "items": [
    {
      "uri": "https://testingpenbox.s3.amazonaws.com/file_resources/files/Document_to_sign.pdf",
      
      // Optionnal: allows defining the locations of the signatures in the document.
      "signatures": [

        // A signature location can be described using its exact coordinates
        { "page": 1, "top": 300, "left": 50 },
        
        // A signature location can be described using a PDF FORM field of type "signature"
        { "field": "PDF_FORM_SIGNATURE_FIELD_A" },
        
        // A signature location can be described using a (list of) text strings to find on the page.
        // The signature will be place right bellow the first field matching any of the provided "hint".
        { "hint": ["Sign here", "Please apply you signature bellow" ] },

      ]
    }
  ]
}

Tip: Any "hash" specified in an HTTP(S) uri will be interpreted as an PDF FORM field of type "signature" to sign. The following:
{
  "uri": "https://example.com/my.pdf#PDF_FORM_SIGNATURE_FIELD_A"
}
Will result in:
{
  "uri": "https://example.com/my.pdf",
  "signatures": [ { "field": "PDF_FORM_SIGNATURE_FIELD_A" } ]
}

It is not possible to specify the signature locations in the case of attachment items (because it is not possible to know in advance what files will be uploaded by users). It is however possible to enable signature detection in the uploaded attachments using the find-signatures meta described bellow.

If no item contains a signature location, a default "signature page" will be added to the file to be signed. The signature page to use will depend on the language of the generated document and is not configurable.

Specifying an item name (`item.name`)

When the item is described using a uri, a custom name can also be provided. This will be displayed to the user so that he knows what he is about to sign.

{
  "uri": "https://example.com/013c534b-3b44-4e09-9c3b-043fdbdb31a6.pdf",
  "name": "User friendly name"
}

Filling a PDF file dynamically (`item.fill`)

Each item can also be sent with information to fill. This will only work if the item is a PDF file that contains a PDF Form. Each of the FORM field in the PDF will be replaced with the respective value specified in the fill option.

{
  "attachments or uri": "...",
  // ...

  "fill": {
    // Depending on the type of the PDF FORM field, the behaviour will differ:

    // Text fields will be filled with the string representation of the value
    "TEXT_FIELD": "Any text value",
    "TEXT_FIELD": "", // Text box will be cleared/emptied
    "TEXT_FIELD": null, // This will result in "<void>" (localized) being printed
    "TEXT_FIELD": { ":format-date": "now", ":pattern": "Y-M-D" }, // "2023-04-17"

    // Checkboxes will be checked/unchekced according to the "truhiness" of the value
    "CHECKBOX_FIELD": false, // true for "checked", false for "unchecked"

    // Fields where one of multiple value should be selected can be used too. Note that only available values are allowed.
    "OPTION_FIELD": "option_1",
    "RADIO_FIELD": "option_1",
    "DROPDOWN_FIELD": "option_1",

    // Button fields will be "filled" with the image specified at the given URI
    "BUTTON_FIELD": "https://example.com/image.png",
    "BUTTON_FIELD": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",      
  }
}

Merging all items into a single file (`"merge"`)

By default, all items will be merged into 1 PDF before sending for signature to the provider.

{
  "type": "signature",
  // ...

  "merge": false // defaults to true
}

Specifying a signature method (`"method"`)

Current supported methods is one of the email, sms, handwritten, id-card

{
  "type": "signature",
  // ...

  "method": "sms" // "sms" is the default
}

Note: All methods require that the user.email key was properly filled. The "sms" signing method also requires that the user.phone key was provided.

Specifying the language of the file (`locale`)

Some operations require to know which is the language of the document being signed:

Filling fields with null (<void>in english, <Néant> in french, etc.) or numbers (1,000.23 in english, 1 000,23 in french, etc.)
Automatic detection of the signatures in the document
If no signature locations are detected, adding a signature page in any of the items (or individual items when merge is false)

This will default the the value of user.locale. If you need to force the language to some other value (e.g. if all the documents to sign are in english), use the locale option:

{
  "type": "signature",
  // ...

  "locale": "en"
}

Adding Files from the options

We can easily add in the options an element that will collect the PDF to be send for signature using a file element

{
  "key": "options.files_to_sign",
  "type": "file",
  "title": "Fiels to sign",
  "accept": "application/pdf,.pdf,image/png,.png,image/jpeg,.jpg,.jpeg",
  "multiple": true
},

The `find-signature` meta

In order to enable the ability to specify the signature location manually when uploading a file (upon request creation only), the file element must contain the following meta option:

{
  "type": "file",

  // ...

  "meta": {
    "find-signatures": true
  }
}

This meta option can also contain options allowing to automatically find the signatures upon upload. To do so, you should specify a hint that is a an array of string after which a signature location will be automatically added. The hint will generate a "match" if, and only if, the full text box in the PDF matches the entire string of the hint. If you need a more powerful mechanism, regular expressions can also be used.

{
  "type": "file",

  // ...

  "meta": {
    "find-signatures": {
      "hint": [
        "Signature,",
        "Sign here:",
        "I agree to these terms",
        "/^regular expression(s)? (is|are) supported here$/i"
      ]
    }
  }
}

And if you want to force that at least one signature location was automatically found, you can use the required option:

{
  "type": "file",

  // ...

  "meta": {
    "find-signatures": {
      "required": true
    }
  }
}

All the locations automatically found using this option can be adjusted in the user interface after the file was uploaded.

Options

Specifying the name of the signature package (name)

Specifying the files to sign (items)

Signing a file from a URI (item.uri)

Signing a Penbox file (item.attachment)

Specifying signature locations (item.signatures)

Specifying an item name (item.name)

Filling a PDF file dynamically (item.fill)

Merging all items into a single file ("merge")

Specifying a signature method ("method")

Specifying the language of the file (locale)