@korala/api-client

TypeScript API client for the Korala document signing platform.

Installation

npm install @korala/api-client

Authentication

Korala uses HMAC signature authentication. You'll need an API key ID and secret from your Korala dashboard.

import { KoralaClient } from '@korala/api-client';

const client = new KoralaClient({
  apiKeyId: 'your-api-key-id',
  apiSecret: 'your-api-secret',
  baseUrl: 'https://api.korala.ai/api/v1', // optional, defaults to production
});

Usage

Create and send a document

// Upload a PDF
const { documentId, uploadUrl } = await client.documents.createUploadUrl({
  fileName: 'contract.pdf',
  contentType: 'application/pdf',
});

// Upload the file to the presigned URL
await fetch(uploadUrl, { method: 'PUT', body: pdfBuffer });

// Confirm the upload
await client.documents.confirmUpload(documentId);

// Add a signer
const signer = await client.signers.create(documentId, {
  name: 'John Doe',
  email: '[email protected]',
});

// Add a signature field
await client.fields.create(documentId, {
  signerId: signer.id,
  fieldType: 'signature',
  pageNumber: 1,
  xPosition: 100,
  yPosition: 500,
  width: 200,
  height: 50,
});

// Send for signing
await client.documents.send(documentId);

Create a document from a template

const document = await client.templates.createDocument(templateId, {
  name: 'Sales Agreement - Acme Corp',
  signers: {
    buyer: { name: 'Jane Smith', email: '[email protected]' },
  },
  variables: {
    company_name: 'Acme Corporation',
    contract_date: '2026-03-16',
  },
});

Bulk sign (countersign)

Sign multiple documents at once using a saved signature:

// Create a saved signature for the signer
await client.signatures.create({
  email: '[email protected]',
  name: 'Jane Smith',
  signatureImageUrl: 'https://example.com/signature.png',
  isDefault: true,
});

// Bulk sign all pending documents
const result = await client.documents.bulkSign({
  documentIds: ['doc-1', 'doc-2', 'doc-3'],
  signerEmail: '[email protected]',
});

console.log(`${result.signed} signed, ${result.failed} failed`);

Webhooks

const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks/korala',
  events: ['document.completed', 'document.signed'],
});

API Reference

| Resource | Methods | |----------|---------| | client.documents | createUploadUrl, confirmUpload, list, get, send, void, getAuditTrail, bulkSign | | client.signers | list, create | | client.fields | list, create, update, delete | | client.signatures | list, get, create, delete | | client.templates | list, get, createDocument, generate | | client.webhooks | list, get, create, update, delete |

License

MIT