---
title: "Position Extraction"
slug: "position-extraction"
updated: 2025-07-02T18:41:53Z
published: 2025-07-02T18:41:53Z
canonical: "docs.onespan.com/position-extraction"
---
> ## 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.
# Position Extraction
[Java SDK](/v1/docs/position-extraction#java-sdk) [.NET SDK](/v1/docs/position-extraction#net-sdk) [REST API](/v1/docs/position-extraction#rest-api) [APEX SDK](/v1/docs/position-extraction#apex-sdk)
## Java SDK
To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/position-extraction-java-sdk/) site. For information on using Position Extraction with Conditional Fields, see [Position Extraction + Conditional Fields](https://community.onespan.com/documentation/codeshare/position-extraction-conditional-fields).
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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk).
```java
.withDocument(newDocumentWithName("First Document")
.fromFile("DOC_FILE_PATH")
.enableExtraction()
.withSignature(signatureFor("john.smith@email.com")
.withName("sig1")
.withPositionExtracted()
)
)
```
Ensure that you have the enableExtraction() call set at the document level and that your PDF document contains a field named sig1. Otherwise, an error will be thrown.
### Results
Here is an example of what you can expect to see once you have run your code.
## .NET SDK
To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/position-extraction-net-sdk/) 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/docs/qsg%20-%20creating%20and%20sending%20a%20package.htm#tab-header-1).
```csharp
.WithDocument(DocumentBuilder.NewDocumentNamed("First Document")
.FromFile("C:/Users/hhaidary/Desktop/pdf/working.pdf")
.EnableExtraction()
.WithSignature(SignatureBuilder.SignatureFor("john.smith@email.com")
.WithName("sig1")
.WithPositionExtracted()
)
)
```
Ensure that you have the enableExtraction() call set at the document level and that your PDF document contains a field named sig1. Otherwise, an error will be thrown.
### Results
Here is an example of what you can expect to see once you have run your code.
## REST API
To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/position-extraction-rest-api/) 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
```http
Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key
```
#### Request Payload
```http
------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
```http
{
"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
| Property | | | Type | Editable | Required | Default | Sample Values |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 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 | Field Position Extraction Example |
| documents | | | | | | | |
| name | | | string | Yes | No | n/a | Sample Contract |
| extract | | | boolean | Yes | No | false | true / false |
| approvals | | | | | | | |
| | role | | string | Yes | No | n/a | Signer1 |
| | fields | | | | | | |
| | | type | string | Yes | Yes | n/a | SIGNATURE / INPUT |
| | | extract | boolean | Yes | No | false | true / false |
| | | subtype | string | Yes | Yes | n/a | FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST |
| | | name | string | Yes | No | n/a | sig1 |
| | | value | string | Yes | No | n/a | FULLNAME / INITIALS / CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / RADIO / LIST |
| | | binding | string | Yes | No | null | {approval.signed} / {signer.title} / {signer.name} / {signer.company} |
| roles | | | | | | | |
| id | | | string | Yes | No | n/a | Signer1 |
| name | | | string | Yes | No | n/a | Sender |
| type | | | string | Yes | No | SIGNER | SIGNER / SENDER |
| signers | | | | | | | |
| | email | | string | Yes | Yes | n/a | john.smith@example.com |
| | firstName | | string | Yes | Yes | n/a | John |
| | lastName | | string | Yes | Yes | n/a | Smith |
## APEX SDK
To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/position-extraction-apex-sdk/) 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 [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk).
```plaintext
// Prepare Documents Blob
String document1Name = 'Sample_Position_Extraction';
StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_position_extraction' LIMIT 1];
Map documentBlobMap = new Map();
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{field1};
// Assign Approvals to Document
document1.approvals = new List{approval1};
// Add Document to Package
pkg.documents = new List{document1}; // add document
```
Ensure that you have the enableExtraction() call set at the document level and that your PDF document contains a field named sig1. Otherwise, an error will be thrown.
### Results
Here is an example of what you can expect to see once you have run your code.
