Field Validators

This guide covers how to validate fields in OneSpan Sign.

Field validators enable you to require and restrict the range of acceptable values for an unbounded field. When building a field validator, you must first select the field’s desired data type (e.g. numeric, alphabetic). Optionally, you can then add other parameters (e.g. maximum length). A field may only have one validator.

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

The sample code below shows you how to add field validation to a field that is bound to a signature. If you need a comparison to the basic signature object creation or if this is your first time creating a package (transaction in the new UI) with the Java SDK, see this guide.

.withSignature(SignatureBuilder.captureFor("signer@example.com")
		.withName("client_signature")
		.withId(new SignatureId("client"))
		.withPositionExtracted()
		.withField(FieldBuilder.signatureDate()
				.withId(new FieldId("signature_date"))
				.withName("client_date")
				.withPositionExtracted())
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_first"))
				.withName("first_name")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid first name.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_last"))
				.withName("last_name")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid last name.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_address"))
				.withName("address")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.basic().required().withErrorMessage("Please enter a valid address.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_city"))
				.withName("city")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid city.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_state"))
				.withName("state")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().maxLength(2).minLength(2).withErrorMessage("Please enter a valid state.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_zip"))
				.withName("zip")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.numeric().required().maxLength(5).minLength(5).withErrorMessage("Please enter a valid zip.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_country"))
				.withName("country")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid country.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_phone"))
				.withName("phone_number")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.regex("^[2-9]\\d{2}-\\d{3}-\\d{4}$").required().withErrorMessage("Please enter a valid phone number (XXX-XXX-XXXX)")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_email"))
				.withName("email")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.email().required().withErrorMessage("Please enter a valid email.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_company"))
				.withName("company")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.alphabetic().required().withErrorMessage("Please enter a valid company.")))
		.withField(FieldBuilder.textField()
				.withId(new FieldId("client_policy"))
				.withName("policy_number")
				.withPositionExtracted()
				.withValidation(FieldValidatorBuilder.numeric().required().withErrorMessage("Please enter a valid policy number.")))

In this guide, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the withName() method and use the withPositionExtracted() method to ensure that the exact position and size are retained in OneSpan Sign. Note that currently using position extraction in OneSpan Sign can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to pass a field validator type to the FieldValidatorBuilder. You can either use the pre-defined validators that come with the API/SDKs or you can create your own customized validator using regular expression. You can find a complete list of field validator types here. The required() method makes a field mandatory and the withErrorMessage() method customizes the error message that will appear if your user enters invalid format data or if the required field is left empty. You can also restrict the length of an input using the maxLength() and minLength() methods.

Running Your Code

The PDF used in this guide is included in the Developer Community Code Share link. Once you’ve send your document package for signing, this is what your signer will see:

Capture

As you can see, the required fields are highlighted for the user to fill out. The “Signing Date” field will be filled in automatically by OneSpan Sign when the signing is complete.

Get the Code

Field validators enable you to require and restrict the range of acceptable values for an unbounded field. When building a field validator, you must first select the field’s desired data type (e.g. numeric, alphabetic). Optionally, you can then add other parameters (e.g. maximum length). A field may only have one validator.

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

The sample code below shows you how to add field validation to a field that is bound to a signature. If you need a comparison to the basic signature object creation or if this is your first time creating a package (transaction in the new UI) with the .NET SDK, see this guide.

.WithSignature(SignatureBuilder.CaptureFor("john.smith@gmail.com")
		.WithName("client_signature")
		.WithPositionExtracted()
		.WithField(FieldBuilder.SignatureDate()
			.WithName("client_date")
			.WithPositionExtracted())
		.WithField(FieldBuilder.TextField()
			.WithName("first_name")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid first name.")))
		.WithField(FieldBuilder.TextField()
			.WithName("last_name")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid last name.")))
		.WithField(FieldBuilder.TextField()
			.WithName("address")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Basic().Required().WithErrorMessage("Please enter a valid address.")))
		.WithField(FieldBuilder.TextField()
			.WithName("city")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid city.")))
		.WithField(FieldBuilder.TextField()
			.WithName("state")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().MaxLength(2).MinLength(2).WithErrorMessage("Please enter a valid state.")))
		.WithField(FieldBuilder.TextField()
			.WithName("zip")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Numeric().Required().MaxLength(5).MinLength(5).WithErrorMessage("Please enter a valid zip.")))
		.WithField(FieldBuilder.TextField()
			.WithName("country")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid country.")))
		.WithField(FieldBuilder.TextField()
			.WithName("phone_number")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Regex("^[2-9]\\d{2}-\\d{3}-\\d{4}$").Required().WithErrorMessage("Please enter a valid phone number (XXX-XXX-XXXX)")))
		.WithField(FieldBuilder.TextField()
			.WithName("email")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Email().Required().WithErrorMessage("Please enter a valid email.")))
		.WithField(FieldBuilder.TextField()
			.WithName("company")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Alphabetic().Required().WithErrorMessage("Please enter a valid company.")))
		.WithField(FieldBuilder.TextField()
			.WithName("policy_number")
			.WithPositionExtracted()
			.WithValidation(FieldValidatorBuilder.Numeric().Required().WithErrorMessage("Please enter a valid policy number."))))

In this guide, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the withName() method and use the withPositionExtracted() method to ensure that the exact position and size are retained in OneSpan Sign. Note that currently using position extraction in OneSpan Sign can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to pass a field validator type to the FieldValidatorBuilder. You can either use the pre-defined validators that come with the API/SDKs or you can create your own customized validator using regular expression. You can find a complete list of field validator types here. The required() method makes a field mandatory and the withErrorMessage() method customizes the error message that will appear if your user enters invalid format data or if the required field is left empty. You can also restrict the length of an input using the maxLength() and minLength() methods.

Running Your Code

The PDF used in this guide is included in the Developer Community Code Share link. Once you’ve send your document package for signing, this is what your signer will see:

Capture

As you can see, the required fields are highlighted for the user to fill out. The “Signing Date” field will be filled in automatically by OneSpan Sign when the signing is complete.

Get the Code

Field validators enable you to require and restrict the range of acceptable values for an unbounded field. When building a field validator, you must first select the field’s desired data type (e.g. numeric, alphabetic). Optionally, you can then add other parameters (e.g. maximum length). A field may only have one validator.

The Code

Full example code for this guide can be found in the Developer Community Code Share, here.

The sample code below shows you how to add field validation to a field that is bound to a signature. If you need a comparison to the basic signature object creation or if this is your first time creating a package (transaction in the new UI) with the REST API, see this guide.

HTTP Request
POST /api/packages

HTTP Headers
Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"

{
  "autocomplete": true,
  "documents": [
    {
      "approvals": [
        {
          "role": "manager",
          "fields": [
            {
              "subtype": "LABEL",
              "binding": "{approval.signed}",
              "extract": true,
              "type": "INPUT",
              "name": "manager_date"
            },
            {
              "subtype": "CAPTURE",
              "extract": true,
              "type": "SIGNATURE",
              "name": "manager_signature"
            }
          ],
          "name": ""
        },
        {
          "role": "client",
          "fields": [
            {
              "subtype": "LABEL",
              "binding": "{approval.signed}",
              "extract": true,
              "type": "INPUT",
              "name": "client_date"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid first name.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "first_name"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid last name.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "last_name"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid address.",
                "pattern": ""
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "address"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid city.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "city"
            },
            {
              "validation": {
                "maxLength": 2,
                "required": true,
                "minLength": 2,
                "errorMessage": "Please enter a valid state.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "state"
            },
            {
              "validation": {
                "maxLength": 5,
                "required": true,
                "minLength": 5,
                "errorMessage": "Please enter a valid zip.",
                "pattern": "^[-+]?[0-9]*\\.?[0-9]*$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "zip"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid country.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "country"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid phone number (XXX-XXX-XXXX)",
                "pattern": "^[2-9]\\d{2}-\\d{3}-\\d{4}$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "phone_number"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid email.",
                "pattern": "^([a-z0-9_\\.-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "email"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid company.",
                "pattern": "^[\\sa-zA-Z]+$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "company"
            },
            {
              "validation": {
                "required": true,
                "errorMessage": "Please enter a valid policy number.",
                "pattern": "^[-+]?[0-9]*\\.?[0-9]*$"
              },
              "subtype": "TEXTFIELD",
              "extract": true,
              "type": "INPUT",
              "name": "policy_number"
            },
            {
              "subtype": "CAPTURE",
              "extract": true,
              "type": "SIGNATURE",
              "name": "client_signature"
            }
          ],
          "name": ""
        }
      ],
      "extract": true,
      "name": "Contract"
    }
  ],
  "status": "SENT",
  "type": "PACKAGE",
  "roles": [
    {
      "id": "client",
      "type": "SIGNER",
      "signers": [
        {
          "lastName": "Smith",
          "email": "client@gmail.com",
          "firstName": "John",
          "id": "client"
        }
      ],
      "name": "client"
    },
    {
      "id": "manager",
      "type": "SENDER",
      "signers": [
        {
          "lastName": "Haidary",
          "email": "manager@gmail.com ",
          "firstName": "Haris",
          "id": "manager"
        }
      ],
      "name": "manager"
    }
  ],
  "name": "Sample Contract"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the JSON Properties section below.

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

In this guide, the form fields are extracted from the PDF. To extract each form field in your PDF, you will need to pass the exact name of your PDF form field to the “name” object and set the “extract” object to true to ensure that the exact position and size are retained in OneSpan Sign. Note that currently using position extraction in OneSpan Sign can only be done when uploading your document and only through the API/SDKs.

To create a field validator, you will need to a “validation” object. Inside your “validation” object, you will need to define a regular expression for the “pattern” object. Setting the “required” object to true makes a field mandatory and the “errorMessage” object customizes the error message that will appear if your user enters invalid format data or if the required field is left empty.

Running Your Code

The PDF used in this guide is included in the Developer Community Code Share link. Once you’ve send your document package for signing, this is what your signer will see:

Capture

As you can see, the required fields are highlighted for the user to fill out. The “Signing Date” field will be filled in automatically by OneSpan Sign when the signing is complete.

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoComplete boolean Yes No true true / false
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a Sample Contract
documents
name string Yes No n/a sample doc
extract boolean Yes No false false / true
approvals
fields
subtype string Yes No n/a FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
type string Yes No n/a SIGNATURE / INPUT
extract boolean Yes No false true / false
binding string Yes No null {approval.signed} / {signer.title} / {signer.name} / {signer.company}
name string Yes No n/a manager_date
validation
required boolean Yes No false false / true
errorMessage string Yes No n/a Please enter a valid first name.
pattern string Yes No n/a ^[\\sa-zA-Z]+$
role string Yes No n/a Client1
roles
id string Yes No n/a client
name string Yes No n/a Client1
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a client@gmail.com
firstName string Yes Yes n/a John
lastName string Yes Yes n/a Smith
phone string Yes No n/a 514-555-8888
id string Yes No n/a client
company string Yes No n/a Acme Inc.
title string Yes No n/a Managing Director