Developer Guide

How to Sign PDFs with TypeScript

3 steps to sign a PDF with TypeScript: Install the TurboDocx SDK (npm install @turbodocx/sdk), configure your API key with a typed HttpClientConfig, and call TurboSign.sendSignature() with a typed SendSignatureRequest listing recipients and Field objects. The compiler catches a missing signingOrder or an invalid field type before the code ever runs.

The SDK is TypeScript-first: type definitions ship in the package, so requests and responses are typed end to end with no @types install.

Last updated: September 23, 2026

Get API Key FreeGitHub SDKFull API Reference

5 min

Setup time

TypeScript

0 @types

Types ship with SDK

ESM + CJS

NodeNext ready

1

Installation and tsconfig

Install the TurboDocx SDK from npm. The package bundles its own .d.ts type definitions, so there is nothing extra to add for full type checking.

npm / yarn / pnpm
npm install @turbodocx/sdk

For modern ESM projects, use NodeNext module resolution and enable esModuleInterop. This lets you use import syntax in both Node and bundled apps.

tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "target": "ES2022"
  }
}

Requirements: Node.js 18+ and TypeScript 4.7+. No @types/turbodocx package is needed; the types ship inside @turbodocx/sdk.

2

Obtaining an API Key

Before you begin, you'll need your API credentials from the TurboDocx dashboard.

  1. Sign up for a free account at TurboDocx
  2. Navigate to Settings → API Keys
  3. Copy your API Key and Organization ID
.env
TURBODOCX_API_KEY=your_api_key_here
TURBODOCX_ORG_ID=your_org_id_here
TURBODOCX_SENDER_EMAIL=you@company.com
TURBODOCX_SENDER_NAME=Your Company Name
3

Sending a Signing Request

Import the SDK types alongside TurboSign so your configuration, recipients, and fields are checked at compile time. The recipient receives an email with a link to sign.

send-signature.ts
import { TurboSign, type HttpClientConfig, type Recipient, type Field, type SendSignatureResponse } from '@turbodocx/sdk';
import { readFileSync } from 'fs';

// Typed config. process.env values are string | undefined,
// which HttpClientConfig accepts.
const config: HttpClientConfig = {
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
  senderEmail: process.env.TURBODOCX_SENDER_EMAIL,  // REQUIRED
  senderName: process.env.TURBODOCX_SENDER_NAME,    // Recommended
};
TurboSign.configure(config);

// Read PDF file
const pdfBuffer: Buffer = readFileSync('contract.pdf');

// Typed recipients and fields
const recipients: Recipient[] = [
  { name: 'John Doe', email: 'john@example.com', signingOrder: 1 },
];

const fields: Field[] = [
  {
    type: 'signature',
    recipientEmail: 'john@example.com',
    template: {
      anchor: '{signature1}',
      placement: 'replace',
      size: { width: 100, height: 30 },
    },
  },
];

// Send document for signature (fully typed response)
const result: SendSignatureResponse = await TurboSign.sendSignature({
  file: pdfBuffer,
  documentName: 'Partnership Agreement',
  recipients,
  fields,
});

console.log('Document ID:', result.documentId);

Type safety: Because Recipient and Field are imported types, a missing signingOrder or an invalid field type fails to compile instead of failing at runtime. The senderEmail remains required and is used as the reply-to address.

4

Processing Results with Webhooks

Configure webhooks to receive real-time notifications when documents are signed. Verify the typed X-TurboDocx-Signature header with verifyWebhookSignature(); it needs the raw request body, so mount the route with express.raw() instead of express.json().

webhook-handler.ts
import express, { type Request, type Response } from 'express';
import { TurboSign, verifyWebhookSignature } from '@turbodocx/sdk';

const app = express();

app.post(
  '/webhooks/turbosign',
  express.raw({ type: 'application/json' }),
  async (req: Request, res: Response) => {
    const valid: boolean = verifyWebhookSignature(
      req.body as Buffer,
      req.headers['x-turbodocx-signature'] as string,
      req.headers['x-turbodocx-timestamp'] as string,
      process.env.TURBODOCX_WEBHOOK_SECRET!,
    );
    if (!valid) return res.status(401).json({ error: 'invalid signature' });

    const { event, data } = JSON.parse(req.body.toString());

    if (event === 'signature.document.completed') {
      console.log('Document signed:', data.document_id);

      // Download the signed PDF
      const signedPdf = await TurboSign.download(data.document_id);

      // Save to your storage
      await saveToStorage(signedPdf, `signed-${data.document_id}.pdf`);
    }

    res.status(200).json({ received: true });
  }
);
5

Conclusion

You now have everything you need to integrate type-safe document signing into your TypeScript application using the TurboDocx e-signature API. It handles authentication, document delivery, signature collection, and legally-binding audit trails, all with types that ship in the package.

What you can do next:

  • Add multiple recipients with sequential signing order
  • Use different field types: initials, dates, text, checkboxes
  • Poll TurboSign.getStatus(), typed as DocumentStatusResponse
  • Get audit trails and compliance certificates

Related Guides

JavaScript Guide

Sign Documents with JavaScript

The plain Node.js walkthrough using the same SDK, without TypeScript annotations.

Read Guide
Python Guide

Sign Documents with Python

Integrate document signing into Django, FastAPI, or Flask applications.

Read Guide

Resources

Full API Reference

Complete SDK documentation with all methods and types.

GitHub Repository

View source code, examples, and contribute.

Webhook Setup

Configure real-time notifications for your app.

Developer Hub

All TurboDocx SDKs, API docs, and quickstarts.

Frequently Asked Questions

How do I sign a PDF with TypeScript?

To sign a PDF with TypeScript, install the TurboDocx SDK (npm install @turbodocx/sdk), configure it with your typed API credentials, then call TurboSign.sendSignature() with a typed request. The SDK ships its own type definitions, so the request and response are fully typed.

Do I need a separate @types package for the TurboDocx SDK?

No. The TurboDocx SDK ships its own TypeScript definitions, so types for TurboSign.configure(), sendSignature(), Recipient, and Field work out of the box with no extra @types install.

How do I track PDF signature status in a typed TypeScript app?

Call the typed TurboSign.getStatus(documentId) to poll for a DocumentStatusResponse, or verify webhook deliveries with the typed verifyWebhookSignature() helper for a push notification on signature.document.completed.

Does the TurboDocx SDK work with ESM and NodeNext?

Yes. The SDK ships a CommonJS build with bundled type definitions. With "module": "NodeNext" and "esModuleInterop": true in your tsconfig, you can use import { TurboSign } from "@turbodocx/sdk" in both Node and bundled applications.

Ready to Get Started?

Create a free account and get your API key. Start sending documents for signature in minutes.

Get API Key FreeLearn More About the e-signature API