Skip to main content

JavaScript / TypeScript SDK

Agent Skill

Let an agent scaffold this for you

Install the TurboDocx Quickstart Skill and let Claude Code, Cursor, Copilot, Codex, or any agent that speaks the Agent Skills standard install the SDK, wire it into your app, and write a working TurboSign integration end-to-end.

Skill countView on GitHub
bash — turbodocx
$npx skills add TurboDocx/quickstart
# then, inside your agent:›/turbodocx-sdk turbosign

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
  senderEmail: process.env.TURBODOCX_SENDER_EMAIL, // Required: reply-to address for signature request emails
  senderName: "Your Company Name", // Optional but recommended: appears as the sender name
  // 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,
  senderEmail: process.env.TURBODOCX_SENDER_EMAIL,
});

(async () => {
  // Send document with coordinate-based fields
  const result = await TurboSign.sendSignature({
    fileLink: "https://www.turbodocx.com/examples/turbodocx.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://www.turbodocx.com/examples/turbodocx.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");

(async () => {
  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://www.turbodocx.com/examples/turbodocx.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
  senderEmail: string;   // Required: reply-to address for signature request emails
  senderName?: string;   // Optional: sender name in emails (default: 'API Service User')
  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,
  senderEmail: process.env.TURBODOCX_SENDER_EMAIL, // Required for TurboSign
  // 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://www.turbodocx.com/examples/turbodocx.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://www.turbodocx.com/examples/turbodocx.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 { writeFileSync } = require("fs");

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

  // Node.js: Save to file
  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
AuthorizationError403AUTHORIZATION_ERRORAPI key lacks required permissions
ValidationError400VALIDATION_ERRORInvalid request parameters
NotFoundError404NOT_FOUNDDocument or resource not found
ConflictError409CONFLICTResource conflict
RateLimitError429RATE_LIMIT_EXCEEDEDToo many requests
NetworkError-NETWORK_ERRORNetwork connectivity issues

Handling Errors​

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

(async () => {
  try {
    const result = await TurboSign.sendSignature({
      fileLink: "https://www.turbodocx.com/examples/turbodocx.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,
  Field,
  Recipient,
  // 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";

Recipient​

Recipient configuration for signature requests:

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

Field​

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
anchorstringNo†Text anchor pattern like {TagName}
placementstringNo"replace" | "before" | "after" | "above" | "below"
sizeobjectNo{ width: number; height: number }
offsetobjectNo{ x: number; y: number }
caseSensitivebooleanNoCase sensitive search (default: false)
useRegexbooleanNoUse regex for anchor/searchText (default: false)

†All template properties are optional in the type definition, but at least one of anchor or searchText must be provided for anchor-based positioning to work.

CreateSignatureReviewLinkRequest / SendSignatureRequest​

Request configuration for createSignatureReviewLink and sendSignature methods:

PropertyTypeRequiredDescription
fileBufferConditionalPDF file as Buffer
fileLinkstringConditionalURL to document file
deliverableIdstringConditionalTurboDocx deliverable ID
templateIdstringConditionalTurboDocx template ID
recipientsRecipient[]YesRecipients who will sign
fieldsField[]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​

  • Request Body Reference - Complete request body parameters, file sources, and multipart/form-data structure
  • Recipients Reference - Recipient properties, signing order, metadata, and configuration options
  • Field Types Reference - All available field types (signature, date, text, checkbox, etc.) with properties and behaviors
  • Field Positioning Methods - Template-based vs coordinate-based positioning, anchor configuration, and best practices

Resources​

Last updated on