Skip to Content
GuidesFields

Fields

Fields define where signers need to sign, initial, or fill in information on a document.

Field Types

TypeDescription
signatureFull signature (drawn or typed)
initialsInitials only
dateAuto-filled signing date
textFree-form text input
checkboxBoolean checkbox

Field Properties

PropertyTypeDescription
idstringUnique identifier
signerIdstringWhich signer fills this field
fieldTypeenumType of field
pageNumbernumberPDF page (1-indexed)
xPositionnumberX coordinate from left edge (points)
yPositionnumberY coordinate from top edge (points)
widthnumberField width (points)
heightnumberField height (points)
requiredbooleanWhether field must be filled
valuestringFilled value (null until signed)

Adding Fields

// Add a signature field
const signatureField = await korala.fields.create(documentId, {
  signerId: signer.id,
  fieldType: 'signature',
  pageNumber: 1,
  xPosition: 100,  // 100 points from left
  yPosition: 500,  // 500 points from top
  width: 200,
  height: 50,
});
 
// Add initials field
const initialsField = await korala.fields.create(documentId, {
  signerId: signer.id,
  fieldType: 'initials',
  pageNumber: 1,
  xPosition: 400,
  yPosition: 700,
  width: 80,
  height: 40,
});
 
// Add date field (auto-fills when signed)
const dateField = await korala.fields.create(documentId, {
  signerId: signer.id,
  fieldType: 'date',
  pageNumber: 1,
  xPosition: 300,
  yPosition: 500,
  width: 150,
  height: 30,
});

Coordinate System

PDF coordinates use points (1 point = 1/72 inch):

  • Origin is at the top-left corner of the page
  • xPosition increases going right
  • yPosition increases going down
  • A standard US Letter page is 612 x 792 points
(0,0) ────────────────────────────► x (612)
  │
  │     ┌─────────────────┐
  │     │   PDF Content   │
  │     │                 │
  │     │   ┌─────────┐   │
  │     │   │ Field   │   │
  │     │   │(100,500)│   │
  │     │   └─────────┘   │
  │     │                 │
  │     └─────────────────┘
  ▼
  y (792)

When placing fields programmatically, you can use the document viewer to find coordinates visually, or calculate positions relative to page dimensions.

Field TypeWidthHeight
signature20050
initials8040
date15030
text20030
checkbox3030

Listing Fields

const fields = await korala.fields.list(documentId);
 
for (const field of fields) {
  console.log(`${field.fieldType} on page ${field.pageNumber}`);
  console.log(`  Position: (${field.xPosition}, ${field.yPosition})`);
  console.log(`  Assigned to: ${field.signerId}`);
  if (field.value) {
    console.log(`  Value: ${field.value}`);
  }
}

Removing Fields

await korala.fields.delete(documentId, fieldId);

Fields can only be removed from documents in draft status.

Multiple Signers Example

Placing fields for multiple signers on the same document:

// Create document and add signers
const alice = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Alice (Seller)',
  signingOrder: 1,
});
 
const bob = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Bob (Buyer)',
  signingOrder: 2,
});
 
// Alice's fields (left side)
await korala.fields.create(documentId, {
  signerId: alice.id,
  fieldType: 'signature',
  pageNumber: 2,
  xPosition: 50,
  yPosition: 650,
  width: 200,
  height: 50,
});
 
await korala.fields.create(documentId, {
  signerId: alice.id,
  fieldType: 'date',
  pageNumber: 2,
  xPosition: 50,
  yPosition: 710,
  width: 100,
  height: 25,
});
 
// Bob's fields (right side)
await korala.fields.create(documentId, {
  signerId: bob.id,
  fieldType: 'signature',
  pageNumber: 2,
  xPosition: 350,
  yPosition: 650,
  width: 200,
  height: 50,
});
 
await korala.fields.create(documentId, {
  signerId: bob.id,
  fieldType: 'date',
  pageNumber: 2,
  xPosition: 350,
  yPosition: 710,
  width: 100,
  height: 25,
});

Response Format

{
  "id": "fld_abc123",
  "documentId": "doc_xyz789",
  "signerId": "sig_def456",
  "fieldType": "signature",
  "pageNumber": 1,
  "xPosition": 100,
  "yPosition": 500,
  "width": 200,
  "height": 50,
  "required": true,
  "value": null,
  "signatureImageUrl": null,
  "filledAt": null,
  "createdAt": "2024-01-14T09:00:00Z",
  "updatedAt": "2024-01-14T09:00:00Z"
}
Last updated on
SignersTemplates