Documents
Documents are the core resource in Korala. This guide covers creating documents, managing their lifecycle, and retrieving signed copies.
Document Lifecycle
| Status | Description |
|---|---|
draft | Document created but not sent for signing |
pending | Sent to signers, awaiting signatures |
completed | All signatures collected, document sealed |
voided | Cancelled before completion |
expired | Expiration date passed before completion |
Creating a Document
Document creation is a two-step process:
- Get an upload URL - Request a pre-signed URL for uploading your PDF
- Confirm the upload - Tell Korala the upload is complete
TypeScript
import { KoralaClient } from '@korala/api-client';
import fs from 'fs';
const korala = new KoralaClient({
apiKeyId: 'your-api-key-id',
apiSecret: 'your-api-secret',
});
// Step 1: Get upload URL
const { documentId, uploadUrl, key } = await korala.documents.createUploadUrl({
filename: 'contract.pdf',
contentType: 'application/pdf',
});
// Step 2: Upload the file
const pdfBuffer = fs.readFileSync('contract.pdf');
await fetch(uploadUrl, {
method: 'PUT',
body: pdfBuffer,
headers: { 'Content-Type': 'application/pdf' },
});
// Step 3: Confirm the upload
const document = await korala.documents.confirmUpload(documentId);
console.log(`Document created: ${document.id}`);
console.log(`Status: ${document.status}`); // 'draft'Sending for Signatures
Once you’ve added signers and fields, send the document:
TypeScript
// Add signers first
const signer = await korala.signers.create(documentId, {
email: '[email protected]',
name: 'John Doe',
});
// Add signature fields
await korala.fields.create(documentId, {
signerId: signer.id,
fieldType: 'signature',
pageNumber: 1,
xPosition: 100,
yPosition: 500,
width: 200,
height: 50,
});
// Send for signing
const document = await korala.documents.send(documentId);
console.log(`Status: ${document.status}`); // 'pending'Retrieving Documents
Get a Single Document
TypeScript
const document = await korala.documents.get(documentId);
console.log(`Name: ${document.name}`);
console.log(`Status: ${document.status}`);
console.log(`Original PDF: ${document.originalFileUrl}`);
if (document.status === 'completed') {
console.log(`Signed PDF: ${document.signedFileUrl}`);
console.log(`Certificate: ${document.certificateFileUrl}`);
console.log(`Completed: ${document.completedAt}`);
}List All Documents
TypeScript
// List all documents
const documents = await korala.documents.list();
// Filter by status
const pendingDocs = await korala.documents.list({ status: 'pending' });
// Pagination
const page2 = await korala.documents.list({ limit: 10, offset: 10 });Downloading Files
Completed documents have three files:
| File | Description |
|---|---|
originalFileUrl | The original uploaded PDF |
signedFileUrl | PDF with visual signatures and cryptographic seal |
certificateFileUrl | Certificate of Completion (audit trail) |
TypeScript
const document = await korala.documents.get(documentId);
if (document.status === 'completed') {
// Download signed PDF
const signedPdf = await fetch(document.signedFileUrl);
fs.writeFileSync('signed-contract.pdf', await signedPdf.buffer());
// Download certificate
const certificate = await fetch(document.certificateFileUrl);
fs.writeFileSync('certificate.pdf', await certificate.buffer());
}Voiding a Document
Cancel a document before it’s completed:
TypeScript
const document = await korala.documents.void(documentId);
console.log(`Status: ${document.status}`); // 'voided'Voiding a document is permanent and cannot be undone. Signers will be notified that the document has been cancelled.
Response Format
{
"id": "doc_abc123",
"name": "contract.pdf",
"status": "completed",
"originalFileUrl": "https://storage.example.com/original.pdf",
"signedFileUrl": "https://storage.example.com/signed.pdf",
"certificateFileUrl": "https://storage.example.com/certificate.pdf",
"expiresAt": null,
"completedAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-14T09:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}Last updated on