Document model

The OneSpan Identity Verification Document model is a section of the Transaction model. It defines documents that are included in an instance of the OneSpan Identity Verification workflow. This workflow can include different types of documents:

  • Documents that will be presented to the user for review and acceptance.
  • Documents that will be presented for signing.
  • Raw data collected from the ID validation process (OneSpan Identity Verification module).
  • ...

The Document model contains information that is required for the following document actions:

  • Pre-process electronic document(s):

    • Splitting / joining
    • Signature location extraction
    • Customization (forms, annotations)
    • Watermarking
  • Apply signatures associated with the users’ intent to sign.
  • Apply tamper seals.
  • Render documents for viewing.
  • Add documents to the single evidence pack.

Document properties

Document properties lists the document properties in OneSpan Identity Verification.

Document resource definition: .../properties/transaction/properties/documents/items

Document properties
Property Type Description
content String

URL referencing the binary content of a document.

Schema: ../common/common.schema.3.0.sfs-url.json
description String

The description captures relevant information about the purpose of a document, as well as any instructions that need to be displayed to signers.

  • Maximum length: 1024
  • Minimum length: 1
document_template_id String

The UUID of the document template, which is a reference to the agreement configuration in the tenant’s profile. If provided, all the document properties will be copied from the agreement configuration .

  • Maximum length: 64
  • Minimum length: 36

  • Pattern:

    ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

groups Array

List of groups to which the document is assigned.

  • Maximum number of items: 8
  • Minimum number of items: 1

Items:

  • The group name. It has to be valid in the context of the workflow assigned to the transaction.
  • Type: string
  • Maximum length: 32
  • Minimum length: 1

To enable print document per role, the groups for a document need to be modified to include the role to which it will be visible as part of the groups. This will work only if the workflow has been configured to use this feature.
id String

The unique human-readable name that identifies the document.

  • Maximum length: 64
  • Minimum length: 1
  • Pattern: ^[a-zA-Z0-9_-]*$
number_of_pages Integer

Number of pages in the document. This property is used to indicate how many rendered pages to show to a user. Must be provided during the create transaction request.

signatures Array
  • Maximum number of items: 64
  • Minimum number of items: 1
  • Schema: transaction.schema.3.0.signature.json

For more information, see Signature properties.
title String

The title of the document.

  • Maximum length: 256
  • Minimum length: 1
version Integer

The version identifier and name. The version references the correct instance of the document in the workflow.

  • Maximum length: 64
  • Minimum length: 1

Default value: 1
watermark  

A watermark will be added to all document pages if the watermark operation is found in the list of pre-processing operations.

schema: transaction.schema.3.0.watermark.json

For more information, see Watermark properties.

Example document properties

  1. {

  2.   "id": "ee02adab-4946-4fae-884f-d8990aaf776a",
  3.   "version": 1,

  4.   "title": "Agreement to sign",

  5.   "description": "Electronic retail credit agreement.",

  6.   "document_template_id": "babdf419-6144-4e01-b8fb-98c863c9a2f2",

  7.   "content": "TWFuIGlzIG...VyZS4=",

  8.   "groups":["agreements"],

  9.   "signatures": [{

  10.     "id": "922b4d10-beb1-4120-b642-2ecb040411d2",

  11.     "status": "signed",
  12.     "role": "signer1",
  13.     "...": "..."
  14.     }, {
  15.     "id": "922b4d10-beb1-4120-b642-2ecb040411d2",
  16.     "status": "signed",
  17.     "role": "signer2",
  18.     "...": "..."
  19.     }
  20. },
  21.   "watermark": [{
  22.     "text": "COPY"
  23.     "font-name": "Arial",
  24.     "font-size": "12"
  25.     }
  26.   ],
  27.   "number_of_pages": "3"
  28. }

Signature properties

The signature defines the location, the type, and the role associated with the document signing. The role determines which signer is required to sign or accept the document.

Signatures can have a predefined location in the document, or they can be anchored to a particular text tag in the document. The signature location is only required for visible signatures (type signature). Signatures of the types acceptance and tamperseal do not visibly appear in the document.

Signature properties lists the signature properties in OneSpan Identity Verification.

Signature properties
Property Type Description
anchor_offset_x Integer

The horizontal offset from the anchor.

Default value: 0
anchor_offset_y Integer

The vertical offset from the anchor.

Default value: 0
anchor_text String

Text string for the text anchor method to extract the signature location. This field will be used if the extract operation is one of the pre-processing operations.

If both the anchor_text and field_name properties are provided, the text anchor extraction is attempted first. If text anchor extraction fails, the signature field extraction is carried out.

  • Maximum number of items: 128
  • Minimum number of items: 1
height Integer The height of the signature field.
id String

The UUID of the signature.

Pattern: ^[w]+$
page_number Integer

The page number where the signature is inserted.
percent_height Number The height of the signature field relative to the corresponding dimension of the document where it appears.
percent_width Number The width of the signature field relative to the corresponding dimension of the document where it appears.
role String

The role to which this signature is assigned.

  • Maximum length: 32
  • Minimum length: 1
signature_block_text String

The text that will appear on an accepted/signed signature field. The field supports substitution elements such as:

  • {$signer}
  • {$date_time}
  • {$date}
  • {$time}
  • {$company}

The field supports new line characters ‘ ‘.

Default text: Signed by: {$signer} on {$date_time}
status String

The current status of the signature.

Possible values:

  • unsigned
  • unaccepted
  • accepted
  • confirmed
  • signed

Default value: unsigned
type String

The type of signature.

Possible values:

  • acceptance
  • signature
  • tamperseal
  • initials

Default value: signature
width Integer The width of the signature field.
x Integer

The X-coordinate (in PDF points) on the page where the signature is inserted.
x_percent Number

The offset in percent by the X- coordinate (relative to the page width) on the page where the signature is inserted.

This property is used for positioning the signature on the screen.
y Integer

The Y-coordinate (in PDF points) on the page where the signature is inserted.
y_percent Number

The offset in percent by the Y-coordinate (relative to the page height) on the page where the signature is inserted.

This property is used for positioning the signature on the screen.

Example signature properties

  1. [

  2.   {
  3.     "id": "922b4d10-beb1-4120-b642-2ecb040411d2",
  4.     "status": "unsigned",

  5.     "role": "signer1",

  6.     "anchor_text": "SignHere:",

  7.     "anchor_offset_x": "5"

  8.     "anchor_offset_y": "10",
  9.     "page_number": "1",

  10.     "x": "1000",

  11.     "y":"2000",

  12.     "x_percent": "65",

  13.     "y_percent": "35",

  14.     "width": "250",

  15.     "height": "50",
  16.     "percent_width": "0.251",
  17.     "percent_height": "0.082",
  18.     "signature_block_text": "Signedby:{$signer}\non{$date_time}",
  19.     "type": "signature"
  20. },
  21. {
  22.     "id": "922b4d10-beb1-4120-b642-2ecb040411d2",
  23.     "status": "signed",

  24.     "role": "signer2",

  25.     "anchor_text": "SignHere:",

  26.     "anchor_offset_x": "5"

  27.     "anchor_offset_y": "10",
  28.     "page_number": "3",

  29.     "x": "1000",

  30.     "y": "2000",

  31.     "x_percent": "65",

  32.     "y_percent": "35",

  33.     "width": "250",

  34.     "height": "50",
  35.     "percent_width": "0.251",
  36.     "percent_height": "0.082",
  37.     "signature_block_text": "Signedby:{$signer}\non{$date_time}",
  38.     "type": "tamperseal"
  39.   }
  40. ]

Watermark properties

With watermarks, you can mark a copy of a document as review only, or a printable copy that should not be signed. Watermark text can be defined for a given transaction instance. The watermark font can be configured to match the typography of a document.

A watermark is added to all pages of the document if the watermark operation is found in the list of pre-processing operations.

Watermark properties lists the watermark properties in OneSpan Identity Verification.

Watermark properties
Property Type Description
font_name String

The font used for the watermark.

  • Maximum length: 256
  • Minimum length: 1

Default value: Helvetica
font_size Integer

The font size used for the watermark.

Default value: 10
text String

The watermark text.

Example watermark properties

  1. {

  2.   "text": "COPY",
  3.   "font_name": "Arial",

  4.   "font_size": "12"

  5. }