Position Extraction

Java SDK.NET SDKREST APIAPEX SDK

Java SDK

.withDocument(newDocumentWithName("First Document")
    .fromFile("DOC_FILE_PATH")
    .enableExtraction()
    .withSignature(signatureFor("john.smith@email.com")
        .withName("sig1")
        .withPositionExtracted()
    )
)

.NET SDK

.WithDocument(DocumentBuilder.NewDocumentNamed("First Document")
    .FromFile("C:/Users/hhaidary/Desktop/pdf/working.pdf")
    .EnableExtraction()
    .WithSignature(SignatureBuilder.SignatureFor("john.smith@email.com")
        .WithName("sig1")
        .WithPositionExtracted()
    )
)

REST API

To download the full code sample see our Code Share site.

The Position Extraction feature ensures that the exact position and size of a field or signature in an uploaded PDF file are automatically retained in OneSpan Sign.

The following sample code shows you how to edit the document block object with position extraction.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

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": "Signer1",
      "type": "SIGNER",
      "signers": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "email": "john.smith@example.com"
        }
      ],
      "name": "Signer1"
    }
  ],
  "documents": [
    {
      "approvals": [
        {
          "fields": [
            {
              "type": "INPUT",
              "extract": true,
              "subtype": "LABEL",
              "name": "name1",
              "binding": "{signer.name}"
            },
            {
              "type": "INPUT",
              "extract": true,
              "subtype": "TEXTFIELD",
              "name": "age1"
            },
            {
              "type": "INPUT",
              "extract": true,
              "subtype": "TEXTFIELD",
              "name": "address1"
            },
            {
              "type": "INPUT",
              "extract": true,
              "subtype": "TEXTFIELD",
              "name": "zip1"
            },
            {
              "type": "INPUT",
              "extract": true,
              "subtype": "TEXTFIELD",
              "name": "city1"
            },
            {
              "type": "SIGNATURE",
              "extract": true,
              "subtype": "FULLNAME",
              "name": "sig1"
            }
          ],
          "role": "Signer1"
        }
      ],
      "extract": true,
      "name": "Sample Contract"
    }
  ],
  "name": "Field Position Extraction Example",
  "type": "PACKAGE",
  "language": "en",
  "autoComplete": true,
  "status": "DRAFT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t-- 

Ensure that you have “extract” : true set at the document level and that your PDF document contains fields named name1, age1, address1, zip1, city1 and sig1. If you do not, an error will be thrown.

For a complete description of each field, see the Request Payload table below.

Response Payload

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

Results

Here is an example of what you can expect to see once you have run your code.

Request Payload Table

APEX SDK

// Prepare Documents Blob
String document1Name = 'Sample_Position_Extraction';
StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_position_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; // document level extraction: true

// Create Approval Metadata
ESignLiveAPIObjects.Approval approval1 = new ESignLiveAPIObjects.Approval();
approval1.role = roleId1;
approval1.id = 'approval1';

// Create Field Metadata
ESignLiveAPIObjects.Field field1 = new ESignLiveAPIObjects.Field();
field1.id = 'signature1';
field1.extract = true;
field1.name = 'sig1'; // match pdf field property name
field1.type = 'SIGNATURE';
field1.subtype = 'FULLNAME';

// Assign Fields to Approval
approval1.fields = new List<ESignLiveAPIObjects.Field>{field1};

// Assign Approvals to Document
document1.approvals = new List<ESignLiveAPIObjects.Approval>{approval1};

// Add Document to Package
pkg.documents = new List<ESignLiveAPIObjects.Document>{document1}; // add document