Document Model
- 07 Oct 2024
- 4 Minutes to read
- DarkLight
- PDF
Document Model
- Updated on 07 Oct 2024
- 4 Minutes to read
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
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
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.
|
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 .
|
groups | Array | List of groups to which the document is assigned.
Items:
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.
|
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 |
For more information, see Signature properties. |
title | String | The title of the document.
|
version | Integer | The version identifier and name. The version references the correct instance of the document in the workflow.
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
{
"id": "ee02adab-4946-4fae-884f-d8990aaf776a",
"version": 1,
"title": "Agreement to sign",
"description": "Electronic retail credit agreement.",
"document_template_id": "babdf419-6144-4e01-b8fb-98c863c9a2f2",
"content": "TWFuIGlzIG...VyZS4=",
"groups":["agreements"],
"signatures": [{
"id": "922b4d10-beb1-4120-b642-2ecb040411d2",
"status": "signed",
"role": "signer1",
"...": "..."
}, {
"id": "922b4d10-beb1-4120-b642-2ecb040411d2",
"status": "signed",
"role": "signer2",
"...": "..."
}
},
"watermark": [{
"text": "COPY"
"font-name": "Arial",
"font-size": "12"
}
],
"number_of_pages": "3"
}
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 object JSON schema
Type: object
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.
|
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.
|
signature_block_text | String | The text that will appear on an accepted/signed signature field. The field supports substitution elements such as:
The field supports new line characters ‘ ‘. Default text: Signed by: {$signer} on {$date_time} |
status | String | The current status of the signature. Possible values:
Default value: unsigned |
type | String | The type of signature. Possible values:
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
[
{
"id": "922b4d10-beb1-4120-b642-2ecb040411d2",
"status": "unsigned",
"role": "signer1",
"anchor_text": "SignHere:",
"anchor_offset_x": "5"
"anchor_offset_y": "10",
"page_number": "1",
"x": "1000",
"y":"2000",
"x_percent": "65",
"y_percent": "35",
"width": "250",
"height": "50",
"percent_width": "0.251",
"percent_height": "0.082",
"signature_block_text": "Signedby:{$signer}\non{$date_time}",
"type": "signature"
},
{
"id": "922b4d10-beb1-4120-b642-2ecb040411d2",
"status": "signed",
"role": "signer2",
"anchor_text": "SignHere:",
"anchor_offset_x": "5"
"anchor_offset_y": "10",
"page_number": "3",
"x": "1000",
"y": "2000",
"x_percent": "65",
"y_percent": "35",
"width": "250",
"height": "50",
"percent_width": "0.251",
"percent_height": "0.082",
"signature_block_text": "Signedby:{$signer}\non{$date_time}",
"type": "tamperseal"
}
]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 object JSON schema
Type: object
Property | Type | Description |
|---|---|---|
font_name | String | The font used for the watermark.
Default value: Helvetica |
font_size | Integer | The font size used for the watermark. Default value: 10 |
text | String | The watermark text. |
Example watermark properties
{
"text": "COPY",
"font_name": "Arial",
"font_size": "12"
}Was this article helpful?