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

View on GitHubFull install guide →

bash — turbodocx

$npx skills add TurboDocx/quickstart

# then, inside your agent:›/turbodocx-sdk deliverable

The official TurboDocx Deliverable SDK for Java applications. Generate documents from templates with dynamic variable injection, download source files and PDFs, and manage deliverables programmatically with the Builder pattern, comprehensive error handling, and type-safe APIs. Available on Maven Central as com.turbodocx:turbodocx-sdk.

Installation

Maven

<dependency>
    <groupId>com.turbodocx</groupId>
    <artifactId>turbodocx-sdk</artifactId>
    <version>0.7.0</version>
</dependency>

Gradle (Kotlin)

implementation("com.turbodocx:turbodocx-sdk:0.7.0")

Gradle (Groovy)

implementation 'com.turbodocx:turbodocx-sdk:0.7.0'

Requirements

• Java 11+
• OkHttp 4.x (included)
• Gson 2.x (included)

---

Configuration

import com.turbodocx.TurboDocxClient;
import com.turbodocx.DeliverableClient;

public class Main {
    public static void main(String[] args) {
        // Option 1: Standalone deliverable client (no senderEmail needed)
        DeliverableClient deliverable = new TurboDocxClient.Builder()
            .apiKey(System.getenv("TURBODOCX_API_KEY"))
            .orgId(System.getenv("TURBODOCX_ORG_ID"))
            .buildDeliverableClient();

        // Option 2: Full client (includes TurboSign + Deliverable)
        TurboDocxClient client = new TurboDocxClient.Builder()
            .apiKey(System.getenv("TURBODOCX_API_KEY"))
            .orgId(System.getenv("TURBODOCX_ORG_ID"))
            .senderEmail("sender@example.com")
            .build();
        DeliverableClient deliverable = client.deliverable();
    }
}

No senderEmail Required

Use buildDeliverableClient() when you only need document generation: it skips the senderEmail validation required by TurboSign.

Environment Variables

export TURBODOCX_API_KEY=your_api_key_here
export TURBODOCX_ORG_ID=your_org_id_here

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.

---

Quick Start

Generate a document from a template

import com.turbodocx.TurboDocxClient;
import com.turbodocx.DeliverableClient;
import com.turbodocx.models.deliverable.*;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        DeliverableClient deliverable = new TurboDocxClient.Builder()
            .apiKey(System.getenv("TURBODOCX_API_KEY"))
            .orgId(System.getenv("TURBODOCX_ORG_ID"))
            .buildDeliverableClient();

        Gson gson = new GsonBuilder().setPrettyPrinting().create();

        DeliverableVariable var1 = new DeliverableVariable();
        var1.setPlaceholder("{CompanyName}");
        var1.setText("Acme Corporation");
        var1.setMimeType("text");

        DeliverableVariable var2 = new DeliverableVariable();
        var2.setPlaceholder("{Date}");
        var2.setText("2026-03-12");
        var2.setMimeType("text");

        CreateDeliverableRequest request = new CreateDeliverableRequest();
        request.setName("Q1 Report");
        request.setTemplateId("your-template-id");
        request.setVariables(List.of(var1, var2));
        request.setDescription("Quarterly business report");
        request.setTags(List.of("reports", "quarterly"));

        CreateDeliverableResponse result = deliverable.generateDeliverable(request);

        System.out.println("Result: " + gson.toJson(result));
    }
}

Download and manage deliverables

import com.turbodocx.TurboDocxClient;
import com.turbodocx.DeliverableClient;
import com.turbodocx.models.deliverable.*;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        DeliverableClient deliverable = new TurboDocxClient.Builder()
            .apiKey(System.getenv("TURBODOCX_API_KEY"))
            .orgId(System.getenv("TURBODOCX_ORG_ID"))
            .buildDeliverableClient();

        Gson gson = new GsonBuilder().setPrettyPrinting().create();

        // List deliverables with pagination
        ListDeliverablesRequest listRequest = new ListDeliverablesRequest();
        listRequest.setLimit(10);
        listRequest.setShowTags(true);
        DeliverableListResponse list = deliverable.listDeliverables(listRequest);
        System.out.println("Total: " + list.getTotalRecords());

        // Get deliverable details
        DeliverableRecord details = deliverable.getDeliverableDetails("deliverable-uuid");
        System.out.println("Name: " + details.getName());

        // Download source file (DOCX/PPTX)
        byte[] sourceFile = deliverable.downloadSourceFile("deliverable-uuid");
        Files.write(Paths.get("report.docx"), sourceFile);

        // Download PDF
        byte[] pdfFile = deliverable.downloadPDF("deliverable-uuid");
        Files.write(Paths.get("report.pdf"), pdfFile);

        // Update deliverable
        UpdateDeliverableRequest updateRequest = new UpdateDeliverableRequest();
        updateRequest.setName("Q1 Report - Final");
        updateRequest.setDescription("Final quarterly business report");
        updateRequest.setTags(List.of("reports", "final"));
        deliverable.updateDeliverableInfo("deliverable-uuid", updateRequest);

        // Delete deliverable
        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:

DeliverableVariable var = new DeliverableVariable();
var.setPlaceholder("{CompanyName}");
var.setText("Acme Corporation");
var.setMimeType("text");

2. HTML Variables

Inject rich HTML content with formatting:

DeliverableVariable var = new DeliverableVariable();
var.setPlaceholder("{Summary}");
var.setText("<p>This is a <strong>formatted</strong> summary with <em>rich text</em>.</p>");
var.setMimeType("html");

3. Image Variables

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

DeliverableVariable var = new DeliverableVariable();
var.setPlaceholder("{Logo}");
var.setText("https://example.com/logo.png");
var.setMimeType("image");

4. Markdown Variables

Inject markdown content that gets converted to formatted text:

DeliverableVariable var = new DeliverableVariable();
var.setPlaceholder("{Notes}");
var.setText("## Key Points\n- First item\n- Second item\n\n**Important:** Review before submission.");
var.setMimeType("markdown");

Variable Stack

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

---

API Reference

Configure

Create a new Deliverable client using the Builder pattern.

// Standalone deliverable client
DeliverableClient deliverable = new TurboDocxClient.Builder()
    .apiKey("your-api-key")       // Required
    .orgId("your-org-id")         // Required
    .buildDeliverableClient();

// Or from the full client
TurboDocxClient client = new TurboDocxClient.Builder()
    .apiKey("your-api-key")       // Required
    .orgId("your-org-id")         // Required
    .senderEmail("sender@co.com") // Required for TurboSign
    .build();
DeliverableClient deliverable = client.deliverable();

The builder authenticates with either apiKey(...) or accessToken(...) (a bearer token), and exposes three build targets:

Builder method	Returns	Use for
build()	TurboDocxClient	Full client, turboSign() and deliverable()
buildDeliverableClient()	DeliverableClient	Document generation only (no senderEmail needed)
buildWebhooksClient()	TurboWebhooks	Signature webhook subscriptions, see TurboWebhooks Java SDK

// Authenticate with a bearer access token instead of an API key
DeliverableClient deliverable = new TurboDocxClient.Builder()
    .accessToken(System.getenv("TURBODOCX_ACCESS_TOKEN"))
    .orgId(System.getenv("TURBODOCX_ORG_ID"))
    .buildDeliverableClient();

Sharing one HTTP client

DeliverableClient also has a public constructor, new DeliverableClient(HttpClient), if you already hold a configured HttpClient and want the deliverable module to reuse it. Most applications should use the builder instead.

Generate deliverable

Generate a new document from a template with variable substitution.

DeliverableVariable var1 = new DeliverableVariable();
var1.setPlaceholder("{CompanyName}");
var1.setText("Acme Corp");
var1.setMimeType("text");

CreateDeliverableRequest request = new CreateDeliverableRequest();
request.setName("Q1 Report");
request.setTemplateId("your-template-id");
request.setVariables(List.of(var1));
request.setDescription("Quarterly business report");
request.setTags(List.of("reports", "quarterly"));

CreateDeliverableResponse result = deliverable.generateDeliverable(request);

System.out.println("Result: " + gson.toJson(result));

List deliverables

List deliverables with pagination, search, and filtering.

ListDeliverablesRequest request = new ListDeliverablesRequest();
request.setLimit(10);
request.setOffset(0);
request.setQuery("report");
request.setShowTags(true);

DeliverableListResponse list = deliverable.listDeliverables(request);

System.out.println("Result: " + gson.toJson(list));

Get deliverable details

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

DeliverableRecord details = deliverable.getDeliverableDetails("deliverable-uuid", true);

System.out.println("Result: " + gson.toJson(details));

Update deliverable info

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

UpdateDeliverableRequest request = new UpdateDeliverableRequest();
request.setName("Q1 Report - Final");
request.setDescription("Final quarterly business report");
request.setTags(List.of("reports", "final"));

UpdateDeliverableResponse result = deliverable.updateDeliverableInfo("deliverable-uuid", request);

System.out.println("Result: " + gson.toJson(result));

Delete deliverable

Soft-delete a deliverable.

DeleteDeliverableResponse result = deliverable.deleteDeliverable("deliverable-uuid");

System.out.println("Result: " + gson.toJson(result));

Download source file

Download the original source file (DOCX or PPTX).

byte[] sourceData = deliverable.downloadSourceFile("deliverable-uuid");

// Save to file
Files.write(Paths.get("report.docx"), sourceData);

Download PDF

Download the PDF version of a deliverable.

byte[] pdfData = deliverable.downloadPDF("deliverable-uuid");

// Save to file
Files.write(Paths.get("report.pdf"), pdfData);

---

Error Handling

deliverable.generateDeliverable() throws TurboDocxException.NotFoundException when templateId doesn't match a template in the org, and TurboDocxException.ValidationException when a variable in the request is missing a required field:

Handling Errors

import com.turbodocx.TurboDocxException;

try {
    CreateDeliverableResponse result = deliverable.generateDeliverable(request);
} catch (TurboDocxException.AuthenticationException e) {
    System.err.println("Authentication failed: " + e.getMessage());
    // Check your API key and org ID
} catch (TurboDocxException.ValidationException e) {
    System.err.println("Validation error: " + e.getMessage());
    // Check request parameters
} catch (TurboDocxException.NotFoundException e) {
    System.err.println("Not found: " + e.getMessage());
    // Template or deliverable doesn't exist
} catch (TurboDocxException.RateLimitException e) {
    System.err.println("Rate limited: " + e.getMessage());
    // Wait and retry
} catch (TurboDocxException.NetworkException e) {
    System.err.println("Network error: " + e.getMessage());
    // Check connectivity
} catch (TurboDocxException e) {
    // Base exception for other API errors
    System.err.println("API error [" + e.getStatusCode() + "]: " + e.getMessage());
}

The full typed-exception table (AuthenticationException, AuthorizationException, ConflictException, RateLimitException, NetworkException, HTTP status mapping) and the getMessage()/getStatusCode()/getCode() methods shared by every exception are documented once in the Java SDK's Error Handling reference.

---

Types

VariableMimeType

String values for variable content types:

Value	Description
"text"	Plain text injection
"html"	Rich HTML content
"image"	Image URL or base64 content
"markdown"	Markdown converted to text

DeliverableVariable

Variable configuration for template injection:

Property	Type	Required	Description
placeholder	String	Yes	Template placeholder (e.g., {CompanyName})
text	String	No*	Value to inject
mimeType	String	Yes	"text", "html", "image", or "markdown"
isDisabled	Boolean	No	Skip this variable during generation
subvariables	List<DeliverableVariable>	No	Nested sub-variables for HTML content
variableStack	Object	No	Multiple instances for repeating content
aiPrompt	String	No	AI prompt for content generation (max 16,000 chars)
allowRichTextInjection	Boolean	No	Allow rich text (HTML) to be injected for this variable

*Required unless variableStack is provided or isDisabled is true.

CreateDeliverableRequest

Request configuration for generateDeliverable:

Property	Type	Required	Description
name	String	Yes	Deliverable name (3-255 characters)
templateId	String	Yes	Template ID to generate from
variables	List<DeliverableVariable>	Yes	Variables for template substitution
description	String	No	Description (up to 65,535 characters)
tags	List<String>	No	Tag strings to associate

UpdateDeliverableRequest

Request configuration for updateDeliverableInfo:

Property	Type	Required	Description
name	String	No	Updated name (3-255 characters)
description	String	No	Updated description
tags	List<String>	No	Replace all tags (empty list to remove)

ListDeliverablesRequest

Options for listDeliverables:

Property	Type	Required	Description
limit	Integer	No	Results per page (1-100, default 6)
offset	Integer	No	Results to skip (default 0)
query	String	No	Search query to filter by name
showTags	Boolean	No	Include tags in the response

DeliverableRecord

The deliverable object returned by both listDeliverables and getDeliverableDetails. Both methods return the same type.

Property	Type	Description
id	String	Unique deliverable ID (UUID)
name	String	Deliverable name
description	String	Description text
templateId	String	Source template ID
templateName	String	Source template name
templateNotDeleted	boolean	Whether the source template still exists
createdBy	String	User ID of the creator
email	String	Creator's email address
fileSize	Long	File size in bytes
fileType	String	MIME type of the generated file
defaultFont	String	Default font used
isActive	boolean	Whether the deliverable is active
createdOn	String	ISO 8601 creation timestamp
updatedOn	String	ISO 8601 last update timestamp
variables	List<DeliverableVariable>	Parsed variable objects with values
tags	List<Tag>	Associated tags (when showTags=true)

Tag

Tag object included when showTags is enabled:

Property	Type	Description
id	String	Tag unique identifier (UUID)
label	String	Tag display name
isActive	boolean	Whether the tag is active
updatedOn	String	ISO 8601 last update timestamp
createdOn	String	ISO 8601 creation timestamp
createdBy	String	User ID of the tag creator
orgId	String	Organization ID

---

Additional Documentation

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

Core API References

• TurboDocx Templating - How to create and configure document templates
• Variable Reference - Complete guide to variable types, formatting, and advanced injection options
• API Reference - Full REST API documentation for Deliverable endpoints

---

Resources

• GitHub Repository
• Maven Central
• API Reference