Document model

The OneSpan Identity Verification Document model is a section of the Transaction model that defines documents 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 necessary for the following document actions:

  • Preprocessing electronic document(s)
    • splitting / joining
    • signature location extraction
    • customization (forms; annotations)
    • watermarking
  • Applying signatures associated with the users’ intent to sign
  • Applying tamper-seals
  • Rendering documents for viewing
  • Adding 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
id String

The unique human-readable name identifying the document.

Maximum length: 64

Minimum length: 1

Pattern: ^[a-zA-Z0-9_-]*$

version Integer

The version identifier and name; the version allows referencing the correct instance of the document in the workflow.

Maximum length: 64

Minimum length: 1

Default value: 1

title String

The title of the document.

Maximum length: 256

Minimum length: 1

description String

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

Maximum length: 1024

Minimum length: 1

document_template_id String

UUID; 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}$

content String

URL referencing the binary content of the document.

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

groups Array

List of groups the document is assigned to.

 

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

Maximum number of items: 8

Minimum number of items: 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.

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.

watermark  

A watermark is added to all document pages if the watermark operation is found in the pre_processing operations list.

schema: transaction.schema.3.0.watermark.json

For more information, see Watermark properties.

number_of_pages Integer

Number of pages in the document. This is used to indicate how many rendered pages to show to a user. Should be provided during the Create Transaction request.

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, type, and 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 be anchored to a particular text tag in the document. The signature location is only required for visible signatures (signature type). Signatures of the types acceptance and tamper seal do not visibly appear in the document.

Signature properties lists the signature properties in OneSpan Identity Verification.

Signature properties
Property Type Description
id String

UUID identifying the signature.

Pattern: ^[w]+$

status String

Reflects the current status of the signature.

Possible values:

  • unsigned
  • unaccepted
  • accepted
  • confirmed
  • signed

Default value: unsigned

role String

Role to which this signature is assigned.

Maximum length: 32

Minimum length: 1

anchor_text String

Text string for the text anchor signature location extraction method. 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 this fails, the signature field extraction is carried out.

Maximum number of items: 128

Minimum number of items: 1

anchor_offset_x Integer

Horizontal offset from the anchor.

Default value: 0

anchor_offset_y Integer

Vertical offset from the anchor.

Default value: 0

page_number Integer

Page number where the signature is inserted.

x Integer

x-coordinate (in PDF points) on the page where the signature is inserted.

y Integer

y-coordinate (in PDF points) on the page where the signature is inserted.

x_percent Number

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_percent Number

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.

width Integer The width of the signature field .
height Integer The height of the signature field .
percent_width Number The width of the signature field relative to the corresponding dimension of the document where it appears.
percent_height Number The height of the signature field relative to the corresponding dimension of the document where it appears.
signature_block_text String

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 should support new line characters ‘ ‘.

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

type String

The type of signature.

Possible values:

  • acceptance
  • signature
  • tamperseal
  • initials

Default value: signature

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

Watermarks allow to clearly mark a copy of a document as a review only copy, 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
text String

The watermark text.

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

Example watermark properties

  1. {

  2.   "text": "COPY",
  3.   "font_name": "Arial",
  4.   "font_size": "12"

  5. }