Text Tags Extraction

The following guide shows you how to use the Text Tag extraction feature.

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names in the documentation. Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be “signer1”. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Developer Community Code Share.

The sample code below shows you how to setup your document package (transaction in the new UI) for Text Tag extraction. In the “withSigner” call, you will see that the custom ID coincides with the one in the image of the PDF form shown earlier in the guide. The .withDocument also has a call to “enableExtraction”. Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

DocumentPackage pkg = PackageBuilder.newPackageNamed("Text Tag Example Package")
     .withStatus(PackageStatus.SENT)
     .withSigner(SignerBuilder.newSignerWithEmail("mail32@mailinator.com")
                .withFirstName("John")
                .withLastName("Smith")
                .withCustomId("signer1"))
     .withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
                .fromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
                .withExtractionType(ExtractionType.TEXT_TAGS_ONLY)
                .enableExtraction())
     .build();

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names in the documentation. Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be “signer1”. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Developer Community Code Share.

The sample code below shows you how to setup your document package (transaction in the new UI) for Text Tag extraction. In the “withSigner” call, you will see that the custom ID coincides with the one in the image of the PDF form shown earlier in the guide. The .withDocument also has a call to “enableExtraction”. Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Text Tag Example Package")
    .WithStatus(DocumentPackageStatus.SENT)
    .WithSigner(SignerBuilder.NewSignerWithEmail("mail32@mailinator.com")
            .WithFirstName("John")
            .WithLastName("Smith")
            .WithCustomId("signer1"))
    .WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
            .FromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
            .WithExtractionType(ExtractionType.TEXT_TAGS_ONLY)
            .EnableExtraction())
    .Build();

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo

The Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document, and replace every text that matches the Text Tag pattern with the appropriate signature or field.

Adding Text Tags

First, you will need a PDF with text tags, named how OneSpan Sign can recognize them. You can see more about the proper format of the form field names in the documentation. Below is the PDF document that is used in this guide. The text tags are shown in the image below.

capture

As you can see, the signer on the document will be “signer1”. This will be the custom ID used in the code section below to let OneSpan Sign know what fields to associate with each signer.

The Code

You can download the full sample code from the Developer Community Code Share.

Typically, you will probably build your JSON string dynamically versus having a giant static string, like this. This is to give a good representation of the structure of the JSON you will need to create your package (transaction in the new UI) properly. The JSON below is formatted for readability.

In each “roles” object, you will see that the custom ID coincides with the one in the image of the text tags shown earlier in the guide. The “documents” object also has “extract” to true. Because this is done, you might notice that you do not have to define the signature locations and who needs to sign the document. This is already taken care of with the ID and the associated text tags from the PDF.

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="sample-contract.pdf"
Content-Type: application/pdf

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

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

{
  "documents": [
    {
      "id": "sample-contract",
      "name": "Test Document",
      "extract": true,
      "data": {
        "esl_doc_extract_type": 1
      }
    }
  ],
  "status": "DRAFT",
  "type": "PACKAGE",
  "roles": [
    {
      "id": "signer1",
      "type": "SIGNER",
      "signers": [
        {
          "email": "mail32@mailinator.com",
          "firstName": "John",
          "lastName": "Smith",
          "id": "signer1"
        }
      ],
      "name": "signer1"
    }
  ],
  "name": "Text Tags Example Package"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

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

Response Payload

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

Running Your Code

After running your code, the package is created with the appropriate fields for each signer. This is what signer1 will see:

capture

Get the Code | See this feature in action in our Interactive Demo

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a Text Tags Example Package
documents
id string Yes No n/a sample-contract
name string Yes No n/a Test Document
extract boolean Yes No false true / false
esl_doc_extract_type integer Yes No 0 0 / 1 / 2
roles
id string Yes No n/a signer1
name string Yes No n/a signer1
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a mail32@mailinator.com
firstName string Yes Yes n/a John
lastName string Yes Yes n/a Smith
id string Yes No n/a signer1