Skip to main content

Deliverable 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 Deliverable integration end-to-end.

Skill countView on GitHubFull install guide →
bash — turbodocx
$npx skills add TurboDocx/quickstart
# then, inside your agent:›/turbodocx-sdk deliverable

The official TurboDocx Deliverable SDK for JavaScript and TypeScript applications. Generate documents from templates with dynamic variable injection, download source files and PDFs, and manage deliverables programmatically. 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 { Deliverable } = require("@turbodocx/sdk");

// Configure globally (recommended for server-side)
Deliverable.configure({
  apiKey: process.env.TURBODOCX_API_KEY, // Required: Your TurboDocx API key
  orgId: process.env.TURBODOCX_ORG_ID, // Required: Your organization ID
  // Optional: OAuth access token instead of an API key
  // accessToken: process.env.TURBODOCX_ACCESS_TOKEN,
  // Optional: override base URL for testing
  // baseUrl: 'https://api.turbodocx.com'
});

DeliverableConfig fields:

PropertyTypeRequiredDescription
apiKeystringYes*Your TurboDocx API key
accessTokenstringYes*OAuth access token, alternative to apiKey
orgIdstringYesYour organization ID
baseUrlstringNoAPI base URL (defaults to https://api.turbodocx.com)

*Supply either apiKey or accessToken. When both are set, accessToken wins.

No Sender Email Required

Unlike TurboSign, the Deliverable module only requires a credential and orgId: no sender email or name is needed.

Environment Variables​

# .env
TURBODOCX_API_KEY=your_api_key_here
TURBODOCX_ORG_ID=your_org_id_here

Quick Start​

Generate a document from a template​

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

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

// Generate a document from a template with variables
const result = await Deliverable.generateDeliverable({
  name: "Q1 Report",
  templateId: "your-template-id",
  variables: [
    { placeholder: "{CompanyName}", text: "Acme Corporation", mimeType: "text" },
    { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
  ],
  description: "Quarterly business report",
  tags: ["reports", "quarterly"],
});

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

Download and manage deliverables​

const { Deliverable } = require("@turbodocx/sdk");
const { writeFileSync } = require("fs");

// List deliverables with pagination
const list = await Deliverable.listDeliverables({ limit: 10, showTags: true });
console.log(`Total: ${list.totalRecords}`);

// Get deliverable details
const details = await Deliverable.getDeliverableDetails("deliverable-uuid");
console.log(`Name: ${details.name}`);

// Download source file (DOCX/PPTX)
const buffer = await Deliverable.downloadSourceFile("deliverable-uuid");
writeFileSync("report.docx", Buffer.from(buffer));

// Download PDF
const pdfBuffer = await Deliverable.downloadPDF("deliverable-uuid");
writeFileSync("report.pdf", Buffer.from(pdfBuffer));

// Update deliverable
await Deliverable.updateDeliverableInfo("deliverable-uuid", {
  name: "Q1 Report - Final",
  description: "Final quarterly business report",
});

// Delete deliverable
await Deliverable.deleteDeliverable("deliverable-uuid");

Variable Types​

The Deliverable module supports four variable types for template injection:

1. Text Variables​

Inject plain text values into template placeholders:

const variables = [
  { placeholder: "{CompanyName}", text: "Acme Corporation", mimeType: "text" },
  { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
];

2. HTML Variables​

Inject rich HTML content with formatting:

const variables = [
  {
    placeholder: "{Summary}",
    text: "<p>This is a <strong>formatted</strong> summary with <em>rich text</em>.</p>",
    mimeType: "html",
  },
];

3. Image Variables​

Inject images by providing a URL or base64-encoded content:

const variables = [
  {
    placeholder: "{Logo}",
    text: "https://example.com/logo.png",
    mimeType: "image",
  },
];

4. Markdown Variables​

Inject markdown content that gets converted to formatted text:

const variables = [
  {
    placeholder: "{Notes}",
    text: "## Key Points\n- First item\n- Second item\n\n**Important:** Review before submission.",
    mimeType: "markdown",
  },
];
Variable Stack

For repeating content (e.g., table rows), use variableStack instead of text to provide multiple values for the same placeholder. See the Types section for details.

API Reference​

Async snippets

The snippets below are partial and run inside an async function. They assume you have already called Deliverable.configure(...) and that asyncio and json are imported (import asyncio, json). For a complete runnable script, wrap the calls in async def main(): ... and run with asyncio.run(main()), as shown in Quick Start.

Configure​

Configure the SDK with your API credentials and organization settings.

Example:

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

Deliverable.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.

Generate deliverable​

Generate a new document from a template with variable substitution.

const result = await Deliverable.generateDeliverable({
  name: "Q1 Report",
  templateId: "your-template-id",
  variables: [
    { placeholder: "{CompanyName}", text: "Acme Corp", mimeType: "text" },
    { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
  ],
  description: "Quarterly business report",
  tags: ["reports", "quarterly"],
});

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

List deliverables​

List deliverables with pagination, search, and filtering.

const list = await Deliverable.listDeliverables({
  limit: 10,
  offset: 0,
  query: "report",
  showTags: true,
});

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

Get deliverable details​

Retrieve the full details of a single deliverable, including variables and fonts.

const details = await Deliverable.getDeliverableDetails("deliverable-uuid", {
  showTags: true,
});

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

Update deliverable info​

Update a deliverable's name, description, or tags.

const result = await Deliverable.updateDeliverableInfo("deliverable-uuid", {
  name: "Q1 Report - Final",
  description: "Final quarterly business report",
  tags: ["reports", "final"],
});

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

Delete deliverable​

Soft-delete a deliverable.

const result = await Deliverable.deleteDeliverable("deliverable-uuid");

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

Download source file​

Download the original source file (DOCX or PPTX).

const buffer = await Deliverable.downloadSourceFile("deliverable-uuid");

// Node.js: Save to file
const { writeFileSync } = require("fs");
writeFileSync("report.docx", Buffer.from(buffer));

Download PDF​

Download the PDF version of a deliverable.

const buffer = await Deliverable.downloadPDF("deliverable-uuid");

// Node.js: Save to file
const { writeFileSync } = require("fs");
writeFileSync("report.pdf", Buffer.from(buffer));

Error Handling​

Deliverable.generateDeliverable() rejects with NotFoundError when templateId doesn't match a template in the org, and ValidationError when an entry in variables is missing a required field. Both extend the base TurboDocxError class:

Handling Errors​

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

try {
  const result = await Deliverable.generateDeliverable({
    name: "Q1 Report",
    templateId: "your-template-id",
    variables: [
      { placeholder: "{CompanyName}", text: "Acme Corp", mimeType: "text" },
    ],
  });
} 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);
    // Template or deliverable 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);
  }
}

The full typed-error table (AuthenticationError, AuthorizationError, ConflictError, RateLimitError, NetworkError, HTTP status and code mapping) and the message/statusCode/code properties shared by every error are documented once in the JavaScript / TypeScript SDK's Error Handling reference.

TypeScript Types / Python Types / PHP Types / Types​

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

Importing Types​

import type {
  // Variable types
  DeliverableVariable,
  VariableMimeType,
  // Request types
  DeliverableConfig,
  CreateDeliverableRequest,
  UpdateDeliverableRequest,
  ListDeliverablesOptions,
  // Response types
  CreateDeliverableResponse,
  UpdateDeliverableResponse,
  DeleteDeliverableResponse,
  DeliverableListResponse,
  // Record types
  DeliverableRecord,
  Tag,
  Font,
} from "@turbodocx/sdk";

VariableMimeType​

Union type for variable content types:

type VariableMimeType = "text" | "html" | "image" | "markdown";

DeliverableVariable / Variable Array Structure​

Variable configuration for template injection:

PropertyTypeRequiredDescription
placeholderstringYesTemplate placeholder (e.g., {CompanyName})
textstringNo*Value to inject
mimeTypeVariableMimeTypeYes"text", "html", "image", or "markdown"
isDisabledbooleanNoSkip this variable during generation
subvariablesDeliverableVariable[]NoNested sub-variables for HTML content
variableStackobject | arrayNoMultiple instances for repeating content
aiPromptstringNoAI prompt for content generation (max 16,000 chars)
allowRichTextInjectionbooleanNoWhether to allow rich text injection

*Required unless variableStack is provided or isDisabled is true.

CreateDeliverableRequest / Generate Deliverable Request​

Request configuration for generateDeliverable:

PropertyTypeRequiredDescription
namestringYesDeliverable name (3-255 characters)
templateIdstringYesTemplate ID to generate from
variablesDeliverableVariable[]YesVariables for template substitution
descriptionstringNoDescription (up to 65,535 characters)
tagsstring[]NoTag strings to associate

UpdateDeliverableRequest / Update Deliverable Request​

Request configuration for updateDeliverableInfo:

PropertyTypeRequiredDescription
namestringNoUpdated name (3-255 characters)
descriptionstringNoUpdated description
tagsstring[]NoReplace all tags (empty array to remove)

ListDeliverablesOptions / List Deliverables Options / ListDeliverablesRequest​

Options for listDeliverables:

 

PropertyTypeRequiredDescription
limitnumberNoResults per page (1-100, default 6)
offsetnumberNoResults to skip (default 0)
querystringNoSearch query to filter by name
showTagsbooleanNoInclude tags in the response

DeliverableRecord / Deliverable Record​

The deliverable object returned by both listDeliverables and getDeliverableDetails. Fields marked details only are populated only by getDeliverableDetails:

 

PropertyTypeDescription
idstringUnique deliverable ID (UUID)
namestringDeliverable name
descriptionstringDescription text
templateIdstringSource template ID
templateNamestringSource template name
templateNotDeletedbooleanWhether the source template still exists
createdBystringUser ID of the creator
emailstringCreator's email address
fileSizenumberFile size in bytes
fileTypestringMIME type of the generated file
defaultFontstringDefault font used
fontsFont[]Fonts used in the document
isActivebooleanWhether the deliverable is active
createdOnstringISO 8601 creation timestamp
updatedOnstringISO 8601 last update timestamp
variablesDeliverableVariable[]Parsed variable objects with values (details only)
tagsTag[]Associated tags (when showTags=true)

DeliverableDetailRecord / Deliverable Detail Record​

The deliverable object returned by get_deliverable_details. Includes all fields from DeliverableRecord except fileSize, plus:

 

PropertyTypeDescription
templateNamestrSource template name
templateNotDeletedboolWhether the source template still exists
variableslist[dict]Parsed variable objects with values

Tag​

Tag object included when showTags is enabled:

 

PropertyTypeDescription
idstringTag unique identifier (UUID)
labelstringTag display name
isActivebooleanWhether the tag is active
updatedOnstringISO 8601 last update timestamp
createdOnstringISO 8601 creation timestamp
createdBystringUser ID of the tag creator
orgIdstringOrganization ID

Additional Documentation​

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

Core API References​

Resources​

Last updated on