Skip to main content

JavaScript / TypeScript SDK

The official TurboDocx SDK for JavaScript and TypeScript applications. Build document generation and digital signature workflows with full TypeScript support, async/await patterns, and comprehensive error handling. Available on npm as @turbodocx/sdk.

Installation​

npm install @turbodocx/sdk

Requirements​

  • Node.js 18+ or modern browser
  • TypeScript 4.7+ (optional, for type checking)

Configuration​

const { TurboSign } = require("@turbodocx/sdk");

// Configure globally (recommended for server-side)
TurboSign.configure({
  apiKey: process.env.TURBODOCX_API_KEY, // Required : Your TurboDocx API key
  orgId: process.env.TURBODOCX_ORG_ID, // Required: Your organization ID
  // Optional: override base URL for testing
  // baseUrl: 'https://api.turbodocx.com'
});
Authentication

Authenticate using apiKey. API keys are recommended for server-side applications.

Environment Variables​

# .env
TURBODOCX_API_KEY=your_api_key_here
TURBODOCX_ORG_ID=your_org_id_here

Quick Start​

Send a Document for Signature​

const { TurboSign } = require("@turbodocx/sdk");

TurboSign.configure({
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
});

// Send document with coordinate-based fields
const result = await TurboSign.sendSignature({
  fileLink: "https://example.com/contract.pdf",
  documentName: "Service Agreement",
  senderName: "Acme Corp",
  senderEmail: "contracts@acme.com",
  recipients: [
    { name: "Alice Smith", email: "alice@example.com", signingOrder: 1 },
    { name: "Bob Johnson", email: "bob@example.com", signingOrder: 2 },
  ],
  fields: [
    // Alice's signature
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 650,
      width: 200,
      height: 50,
      recipientEmail: "alice@example.com",
    },
    {
      type: "date",
      page: 1,
      x: 320,
      y: 650,
      width: 100,
      height: 30,
      recipientEmail: "alice@example.com",
    },
    // Bob's signature
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 720,
      width: 200,
      height: 50,
      recipientEmail: "bob@example.com",
    },
    {
      type: "date",
      page: 1,
      x: 320,
      y: 720,
      width: 100,
      height: 30,
      recipientEmail: "bob@example.com",
    },
  ],
});

console.log(JSON.stringify(result, null, 2));

Using Template-Based Fields​

// Use text anchors instead of coordinates
const result = await TurboSign.sendSignature({
  fileLink: "https://example.com/contract-with-placeholders.pdf",
  recipients: [
    { name: "Alice Smith", email: "alice@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      recipientEmail: "alice@example.com",
      template: {
        anchor: "{SIGNATURE_ALICE}",
        placement: "replace",
        size: { width: 200, height: 50 },
      },
    },
    {
      type: "date",
      recipientEmail: "alice@example.com",
      template: {
        anchor: "{DATE_ALICE}",
        placement: "replace",
        size: { width: 100, height: 30 },
      },
    },
  ],
});

console.log(JSON.stringify(result, null, 2));
Template Anchors Required

Important: The document file must contain the anchor text (e.g., {SIGNATURE_ALICE}, {DATE_ALICE}) that you reference in your fields. If the anchors don't exist in the document, the API will return an error.

Alternative: Use a TurboDocx template with pre-configured anchors:

const result = await TurboSign.sendSignature({
  templateId: "template-uuid-from-turbodocx", // Template already contains anchors
  recipients: [
    { name: "Alice Smith", email: "alice@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      recipientEmail: "alice@example.com",
      template: {
        anchor: "{SIGNATURE_ALICE}",
        placement: "replace",
        size: { width: 200, height: 50 },
      },
    },
  ],
});

File Input Methods​

TurboSign supports four different ways to provide document files:

1. File Upload (Buffer/Blob)​

const { readFileSync } = require("fs");
const { TurboSign } = require("@turbodocx/sdk");

const fileBuffer = readFileSync("./contract.pdf");

const result = await TurboSign.sendSignature({
  file: fileBuffer,
  recipients: [
    { name: "John Doe", email: "john@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 650,
      width: 200,
      height: 50,
      recipientEmail: "john@example.com",
    },
  ],
});
const result = await TurboSign.sendSignature({
  fileLink: "https://storage.example.com/contracts/agreement.pdf",
  recipients: [
    { name: "John Doe", email: "john@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 650,
      width: 200,
      height: 50,
      recipientEmail: "john@example.com",
    },
  ],
});
When to use fileLink

Use fileLink when your documents are already hosted on cloud storage (S3, Google Cloud Storage, etc.). This is more efficient than downloading and re-uploading files.

3. TurboDocx Deliverable ID​

// Use a previously generated TurboDocx document
const result = await TurboSign.sendSignature({
  deliverableId: "deliverable-uuid-from-turbodocx",
  recipients: [
    { name: "John Doe", email: "john@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 650,
      width: 200,
      height: 50,
      recipientEmail: "john@example.com",
    },
  ],
});
Integration with TurboDocx

deliverableId references documents generated using TurboDocx's document generation API. This creates a seamless workflow: generate → sign.

4. TurboDocx Template ID​

// Use a pre-configured TurboSign template
const result = await TurboSign.sendSignature({
  templateId: "template-uuid-from-turbodocx", // Template already contains anchors
  recipients: [
    { name: "Alice Smith", email: "alice@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      recipientEmail: "alice@example.com",
      template: {
        anchor: "{SIGNATURE_ALICE}",
        placement: "replace",
        size: { width: 200, height: 50 },
      },
    },
  ],
});
Integration with TurboDocx

templateId references pre-configured TurboSign templates created in the TurboDocx dashboard. These templates come with built-in anchors and field positioning, making it easy to reuse signature workflows across multiple documents.

API Reference​

Configure​

Configure the SDK with your API credentials and organization settings.

TurboSign.configure({
  apiKey: string;        // Required : Your TurboDocx API key
  orgId: string;         // Required: Your organization ID
  baseUrl?: string;      // Optional: API base URL (default: 'https://api.turbodocx.com')
});

Example:

const { TurboSign } = require("@turbodocx/sdk");

TurboSign.configure({
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
  // Optional: override for testing
  // baseUrl: 'https://api.turbodocx.com'
});
API Credentials Required

Both apiKey and orgId parameters are required for all API requests. To get your credentials, follow the Get Your Credentials steps from the SDKs main page.

Prepare for review​

Upload a document for preview without sending signature request emails.

const { documentId, previewUrl } = await TurboSign.createSignatureReviewLink({
  fileLink: "https://example.com/document.pdf",
  documentName: "Contract Draft",
  recipients: [
    { name: "John Doe", email: "john@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 500,
      width: 200,
      height: 50,
      recipientEmail: "john@example.com",
    },
  ],
});

Prepare for signing​

Upload a document and immediately send signature requests to all recipients.

const { documentId } = await TurboSign.sendSignature({
  fileLink: "https://example.com/document.pdf",
  documentName: "Service Agreement",
  senderName: "Your Company",
  senderEmail: "sender@company.com",
  recipients: [
    { name: "Recipient Name", email: "recipient@example.com", signingOrder: 1 },
  ],
  fields: [
    {
      type: "signature",
      page: 1,
      x: 100,
      y: 500,
      width: 200,
      height: 50,
      recipientEmail: "recipient@example.com",
    },
  ],
});

Get status​

Retrieve the current status of a document.

const result = await TurboSign.getStatus("document-uuid");

console.log(JSON.stringify(result, null, 2));

Download document​

Download the completed signed document as a PDF Blob.

const result = await TurboSign.download("document-uuid");

// Node.js: Save to file
const { writeFileSync } = require("fs");
const buffer = Buffer.from(await result.arrayBuffer());
writeFileSync("signed-contract.pdf", buffer);

Void​

Cancel/void a signature request.

await TurboSign.void("document-uuid", "Contract terms changed");

Resend​

Resend signature request emails to specific recipients.

// Resend to specific recipients
await TurboSign.resend("document-uuid", [
  "recipient-uuid-1",
  "recipient-uuid-2",
]);

Get audit trail​

Retrieve the complete audit trail for a document, including all events and actions.

const result = await TurboSign.getAuditTrail("document-uuid");

console.log(JSON.stringify(result, null, 2));

Error Handling​

The SDK provides typed error classes for different failure scenarios. All errors extend the base TurboDocxError class.

Error Classes​

Error ClassStatus CodeCodeDescription
TurboDocxErrorvariesvariesBase error class for all SDK errors
AuthenticationError401AUTHENTICATION_ERRORInvalid or missing API credentials
ValidationError400VALIDATION_ERRORInvalid request parameters
NotFoundError404NOT_FOUNDDocument or resource not found
RateLimitError429RATE_LIMIT_EXCEEDEDToo many requests
NetworkError-NETWORK_ERRORNetwork connectivity issues

Handling Errors​

const {
  TurboSign,
  TurboDocxError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  NetworkError,
} = require("@turbodocx/sdk");

try {
  const result = await TurboSign.sendSignature({
    fileLink: "https://example.com/contract.pdf",
    recipients: [
      { name: "John Doe", email: "john@example.com", signingOrder: 1 },
    ],
    fields: [
      {
        type: "signature",
        page: 1,
        x: 100,
        y: 650,
        width: 200,
        height: 50,
        recipientEmail: "john@example.com",
      },
    ],
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Authentication failed:", error.message);
    // Check your API key and org ID
  } else if (error instanceof ValidationError) {
    console.error("Validation error:", error.message);
    // Check request parameters
  } else if (error instanceof NotFoundError) {
    console.error("Resource not found:", error.message);
    // Document or recipient doesn't exist
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited:", error.message);
    // Wait and retry
  } else if (error instanceof NetworkError) {
    console.error("Network error:", error.message);
    // Check connectivity
  } else if (error instanceof TurboDocxError) {
    console.error("SDK error:", error.message, error.statusCode, error.code);
  }
}

Error Properties​

All errors include these properties:

PropertyTypeDescription
messagestringHuman-readable error description
statusCodenumber \| undefinedHTTP status code (if applicable)
codestring \| undefinedMachine-readable error code

TypeScript Types​

The SDK exports TypeScript types for full type safety. Import them directly from the package.

Importing Types​

import type {
  // Field types
  SignatureFieldType,
  N8nField,
  N8nRecipient,
  // Request types
  CreateSignatureReviewLinkRequest,
  SendSignatureRequest,
} from "@turbodocx/sdk";

SignatureFieldType​

Union type for all available field types:

type SignatureFieldType =
  | "signature"
  | "initial"
  | "date"
  | "text"
  | "full_name"
  | "title"
  | "company"
  | "first_name"
  | "last_name"
  | "email"
  | "checkbox";

N8nRecipient​

Recipient configuration for signature requests:

PropertyTypeRequiredDescription
namestringYesRecipient's full name
emailstringYesRecipient's email address
signingOrdernumberYesSigning order (1-indexed)

N8nField​

Field configuration supporting both coordinate-based and template-based positioning:

PropertyTypeRequiredDescription
typeSignatureFieldTypeYesField type
recipientEmailstringYesWhich recipient fills this field
pagenumberNo*Page number (1-indexed)
xnumberNo*X coordinate in pixels
ynumberNo*Y coordinate in pixels
widthnumberNo*Field width in pixels
heightnumberNo*Field height in pixels
defaultValuestringNoDefault value (for checkbox: "true" or "false")
isMultilinebooleanNoEnable multiline text
isReadonlybooleanNoMake field read-only (pre-filled)
requiredbooleanNoWhether field is required
backgroundColorstringNoBackground color (hex, rgb, or named)
templateobjectNoTemplate anchor configuration

*Required when not using template anchors

Template Configuration:

PropertyTypeRequiredDescription
anchorstringYesText anchor pattern like {TagName}
placementstringYes"replace" | "before" | "after" | "above" | "below"
sizeobjectYes{ width: number; height: number }
offsetobjectNo{ x: number; y: number }
caseSensitivebooleanNoCase sensitive search (default: false)
useRegexbooleanNoUse regex for anchor/searchText (default: false)

CreateSignatureReviewLinkRequest / SendSignatureRequest​

Request configuration for createSignatureReviewLink and sendSignature methods:

PropertyTypeRequiredDescription
fileBufferConditionalPDF file as Buffer
fileLinkstringConditionalURL to document file
deliverableIdstringConditionalTurboDocx deliverable ID
templateIdstringConditionalTurboDocx template ID
recipientsN8nRecipient[]YesRecipients who will sign
fieldsN8nField[]YesSignature fields configuration
documentNamestringNoDocument name
documentDescriptionstringNoDocument description
senderNamestringNoSender name
senderEmailstringNoSender email
ccEmailsstring[]NoArray of CC email addresses
File Source (Conditional)

Exactly one file source is required: file, fileLink, deliverableId, or templateId.

Additional Documentation​

For detailed information about advanced configuration and API concepts, see:

Core API References​

Resources​