Signing quickstart

Upload a PDF, add a recipient and signature field, then send a signing request through the API.

Quick Start

1. Get Your API Credentials

First, create an API key from your Korala admin dashboard. You’ll receive:

API Key ID: A public identifier for your key
API Secret: Signs your requests. Keep it out of client-side code.

2. Install the API Client

TypeScript


npm install @korala/api-client

3. Send Your First Document

For TypeScript, run this on your server with Node.js 20 or later and place contract.pdf in the working directory. The cURL example requests an upload URL; follow Creating a document for the remaining REST calls.

TypeScript


import { FieldType, KoralaClient } from '@korala/api-client';
import { readFile } from 'node:fs/promises';
 
const pdfBuffer = await readFile('contract.pdf');
 
const korala = new KoralaClient({
  apiKeyId: 'your-api-key-id',
  apiSecret: 'your-api-secret',
});
 
// Create a document and get upload URL
const { documentId, uploadUrl } = await korala.documents.createUploadUrl({
  filename: 'contract.pdf',
  contentType: 'application/pdf',
});
 
// Upload your PDF
const upload = await fetch(uploadUrl, {
  method: 'PUT',
  body: pdfBuffer,
  headers: { 'Content-Type': 'application/pdf' },
});
if (!upload.ok) throw new Error(`Upload failed: ${upload.status}`);
 
// Confirm the upload
await korala.documents.confirmUpload(documentId);
 
// Add a signer
const signer = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'John Doe',
});
 
// Add a signature field
await korala.fields.create(documentId, {
  signerId: signer.id,
  fieldType: FieldType.Signature,
  pageNumber: 1,
  xPosition: 100,
  yPosition: 500,
  width: 200,
  height: 50,
});
 
// Send for signing
await korala.documents.send(documentId);

Core Concepts

Document Lifecycle

Draft - Document is created but not yet sent
Pending - Document has been sent and is awaiting signatures
Completed - All signers have signed; document is cryptographically sealed
Voided - Document was cancelled before completion
Expired - Document expired before all signatures were collected

Authentication

Korala uses HMAC-SHA256 signature authentication for API requests. Each request must include:

Header	Description
`X-API-Key`	Your API key ID
`X-Timestamp`	Current Unix timestamp (seconds)
`X-Signature`	HMAC-SHA256 signature

The signature is computed as:


HMAC-SHA256(SHA256_HEX(secret), "{timestamp}.{METHOD}.{path}.{body}")

See the Authentication Guide for details.

Webhooks

Korala sends webhook notifications for document events:

document_created - Document was created
document_sent - Document was sent for signing
document_viewed - A signer viewed the document
document_signed - A signer completed signing
document_completed - All signatures collected, document sealed
document_voided - Document was voided
document_declined - A signer declined to sign

See the Webhooks Guide for setup instructions.

Next Steps

Example App - Full Next.js example with single-signer, multi-signer, and batch countersign demos
Authentication Guide - HMAC authentication in detail
Documents Guide - Document management
API Reference - Complete API documentation