--- title: "Document Model" slug: "document-model" updated: 2025-06-27T20:09:31Z published: 2025-06-27T20:09:31Z canonical: "docs.onespan.com/document-model" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/document-model#Tab_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](/v1/docs/document-model#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](/v1/docs/document-model#watermark-properties). | ### Example document properties ```json {  "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](/docs/document-model#Tab_Signature_properties) lists the signature properties in OneSpan Identity Verification. - Path: [http://dealflo.com/transaction.3.0.signature.json](http://dealflo.com/transaction.3.0.signature.json) - Signature object JSON schema - Type: object

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 ```json [  {    "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](/docs/document-model#Tab_Watermark_properties) lists the watermark properties in OneSpan Identity Verification. - Path: [http://dealflo.com/transaction.3.0.watermark.json](http://dealflo.com/transaction.3.0.watermark.json) - Watermark object JSON schema - Type: object

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 ```json {  "text": "COPY",  "font_name": "Arial",  "font_size": "12" } ```