The document extraction feature automatically creates all signatures and fields that exist in an uploaded PDF file. The positions and sizes of the signatures and fields in the PDF file are automatically retained in OneSpan Sign.

Configuring the PDF Form Fields

First, you will need a PDF with form fields, 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 form field names on the fields are shown in the image below.

As you can see, the two signers on the document will be “Signer1” and “Preparer1”. These will be the custom IDs 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, here.

The sample code below shows you how to setup your document package (transaction in the new UI) for document extraction. In each “withSigner” call, you will see that the custom IDs coincide with the ones 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 IDs and the associated form field names from the PDF.

DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("Test Document Extraction")
                .WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings())
                    .WithSigner(SignerBuilder.NewSignerWithEmail("signer.email@example.com")
                                .WithFirstName("John")
                                .WithLastName("Smith")
                                .WithCustomId("Signer1")
                    )
                    .WithSigner(SignerBuilder.NewSignerWithEmail("preparer.email@example.com")
                                .WithFirstName("Michael")
                                .WithLastName("Williams")
                                .WithCustomId("Preparer1")
                    )
                    .WithDocument(DocumentBuilder.NewDocumentNamed("testDocumentExtraction")
                                  .FromStream(fileStream1, DocumentType.PDF)
                                  .EnableExtraction()
                                 )
                    .Build();

What it looks like

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

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

Likewise, the preparer sees this:

Get the Code

The document extraction feature automatically creates all signatures and fields that exist in an uploaded PDF file. The positions and sizes of the signatures and fields in the PDF file are automatically retained in OneSpan Sign.

Configuring the PDF Form Fields

First, you will need a PDF with form fields, 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 form field names on the fields are shown in the image below.

As you can see, the two signers on the document will be “Signer1” and “Preparer1”. These will be the custom IDs 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, here.

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 IDs coincide with the ones in the image of the PDF form 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 IDs and the associated form field names 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="testDocumentExtraction.pdf"
Content-Type: application/pdf

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

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

{
    	"roles":[
    	{
            	"id":"Preparer1",
            	"type":"SIGNER",
            	"signers":[
            	{
                    	"firstName":"Michael",
                    	"lastName":"Williams",
                    	"phone":"",
                    	"email":"preparer.email@example.com",
                    	"delivery":
                    	{
                            	"email":true,
                            	"provider":false,
                            	"download":true
                    	},
                    	"id":"Preparer1"
            	}],
            	"name":"Sender"
    	},
    	{
            	"id":"Signer1",
            	"type":"SIGNER",
            	"signers":[
            	{
                    	"firstName":"John",
                    	"lastName":"Smith",
                    	"email":"signer.email@example.com",
                    	"delivery":
                    	{
                            	"email":false,
                            	"provider":false,
                            	"download":false
                    	},
                    	"id":"Signer1"
            	}],
            	"name":"Signer"
    	}],
    	"documents":[
    	{
            	"name": "testDocumentExtraction",
             	"extract": true
    	}],
    	"name": "Test Document Extraction",
    	"type":"PACKAGE",
    	"autoComplete":true,
    	"status":"SENT"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

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

Response Payload

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

What it looks like

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

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

Likewise, the preparer sees this:

Get the Code

JSON Properties

The document extraction feature automatically creates all signatures and fields that exist in an uploaded PDF file. The positions and sizes of the signatures and fields in the PDF file are automatically retained in OneSpan Sign.

Configuring the PDF Form Fields

First, you will need a PDF with form fields, 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 form field names on the fields are shown in the image below.

As you can see, the two signers on the document will be “Signer1” and “Preparer1”. These will be the Role Name used in the code section below to let OneSpan Sign know what fields to associate with each signer.
PDF used in this guide can be found here.

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, here.
The sample code below shows you how to setup your document package (transaction in the new UI) for document extraction.
In each Role object, you will see that the name attributes coincide with the ones in the image of the PDF form shown earlier in the guide.
In the Document object, extract attribute is also set 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 Role Names and the associated form field names from the PDF.

    	ESignLiveSDK sdk = new ESignLiveSDK();
         
        //Create package
        ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
        pkg.name = 'Test Document Extraction - ' + Datetime.now().format();
        pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;
        
        //Create Roles
        String roleId1 = 'Signer1';
        ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();
        role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', 'signer1@mailinator.com', 'CEO', 'ABC Bank');
        role1.id = roleId1;
        role1.name = roleId1;
        
        String roleId2 = 'Preparer1';
        ESignLiveAPIObjects.Role role2 = new ESignLiveAPIObjects.Role();
        role2.signers = sdk.createRolesSigner('sigenr2_firstname', 'signer2_lastname', 'signer2@mailinator.com', 'Applicant', 'ABC Company');
        role2.id = roleId2;
        role2.name = roleId2;
        
        pkg.roles = new List<ESignLiveAPIObjects.Role>{role1,role2};    //add role

        
        //Prepare Documents Blob
        String document1Name = 'Sample_Document_Extraction';
        StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_document_extraction' LIMIT 1];
        Map<String,Blob> documentBlobMap = new Map<String,Blob>();
        documentBlobMap.put(document1Name, sr.Body);
         
        //Create Document Metadata
        ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
        document1.name = document1Name;
        document1.id = document1Name;
        document1.extract = true;
        
        pkg.documents = new List<ESignLiveAPIObjects.Document>{document1};    //add document
        
    	//Send package One Step
        String packageId = sdk.createPackage(pkg,documentBlobMap);
        System.debug('PackageId: ' + packageId);

What it looks like

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

As you see, the required fields are highlighted for the user to fill out. The Name field will be filled in automatically by OneSpan Sign when the signing is complete.
Likewise, the Preparer sees this:

Get the Code