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

View on GitHub

bash — turbodocx

$npx skills add TurboDocx/quickstart

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

The official TurboDocx SDK for Python applications. Build document generation and digital signature workflows with async/await patterns and comprehensive error handling. Available on PyPI as turbodocx-sdk.

Installation

pip
Poetry
Pipenv

pip install turbodocx-sdk

poetry add turbodocx-sdk

pipenv install turbodocx-sdk

Requirements

Python 3.8+
httpx (installed automatically)
pydantic (installed automatically)

Configuration

from turbodocx_sdk import TurboSign
import os

# Configure globally (recommended)
TurboSign.configure(
    api_key=os.environ["TURBODOCX_API_KEY"],        # Required: Your TurboDocx API key
    org_id=os.environ["TURBODOCX_ORG_ID"],          # Required: Your organization ID
    sender_email="contracts@yourcompany.com",       # Required: Reply-to address for signature emails
    sender_name="Your Company",                     # Recommended: Sender name shown in emails
    # base_url="https://api.turbodocx.com"          # Optional: Override base URL
)

Authentication

Authenticate using api_key. 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
TURBODOCX_SENDER_EMAIL=contracts@yourcompany.com
TURBODOCX_SENDER_NAME=Your Company

API Credentials Required

api_key and org_id are required for all API requests. TurboSign additionally requires sender_email (set it on configure(), per call, or via the TURBODOCX_SENDER_EMAIL environment variable) — configure() raises a ValidationError without it. sender_name is optional but strongly recommended. To get your credentials, follow the Get Your Credentials steps from the SDKs main page.

Quick Start

Send a Document for Signature

import asyncio
import json
import os
from turbodocx_sdk import TurboSign

TurboSign.configure(
    api_key=os.environ["TURBODOCX_API_KEY"],
    org_id=os.environ["TURBODOCX_ORG_ID"],
    sender_email="contracts@acme.com",
    sender_name="Acme Corp",
)

async def send_contract():
    result = await TurboSign.send_signature(
        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"}
        ],
        file_link="https://www.turbodocx.com/examples/turbodocx.pdf",
        document_name="Service Agreement",
        sender_name="Acme Corp",
        sender_email="contracts@acme.com",
    )

    print("Result:", json.dumps(result, indent=2))

asyncio.run(send_contract())

Using Template-Based Fields

import asyncio
import json

async def send_with_template():
    result = await TurboSign.send_signature(
        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},
                },
            },
        ],
        file_link="https://www.turbodocx.com/examples/turbodocx.pdf",
    )

    print("Result:", json.dumps(result, indent=2))

asyncio.run(send_with_template())

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.

File Input Methods

TurboSign supports four different ways to provide document files:

Async context

The examples below use await, so they must run inside an async function (call them with asyncio.run(...)). See the Send a Document for Signature Quick Start for the full runnable form.

1. File Upload (bytes)

with open("./contract.pdf", "rb") as f:
    pdf_buffer = f.read()

result = await TurboSign.send_signature(
    file=pdf_buffer,
    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",
        },
    ],
)

2. File URL (file_link)

result = await TurboSign.send_signature(
    file_link="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 file_link

Use file_link 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
result = await TurboSign.send_signature(
    deliverable_id="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

deliverable_id 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
result = await TurboSign.send_signature(
    template_id="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

template_id 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

Async context

The snippets below use await, so they must run inside an async function. For a standalone script, wrap the call and run it with asyncio.run(...), and add import json if the snippet calls json.dumps:

import asyncio
import json

async def main():
    result = await TurboSign.get_status("document-uuid")
    print(json.dumps(result, indent=2))

asyncio.run(main())

Configure

Configure the SDK with your API credentials and organization settings.

TurboSign.configure(
    api_key: str,                                    # Required: Your TurboDocx API key
    org_id: str,                                     # Required: Your organization ID
    sender_email: str,                               # Required: Reply-to address for signature emails
    sender_name: str = None,                         # Recommended: Sender name shown in emails
    base_url: str = "https://api.turbodocx.com"     # Optional: API base URL
)

Prepare for review

Upload a document for preview without sending signature request emails.

result = await TurboSign.create_signature_review_link(
    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"}],
    file_link="https://www.turbodocx.com/examples/turbodocx.pdf",
    document_name="Contract Draft",
)

print(result["documentId"])
print(result["previewUrl"])

Prepare for signing

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

result = await TurboSign.send_signature(
    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"}],
    file_link="https://www.turbodocx.com/examples/turbodocx.pdf",
    document_name="Service Agreement",
    sender_name="Your Company",
    sender_email="sender@company.com",
)

print(result["documentId"])

Get status

Retrieve the current status of a document.

result = await TurboSign.get_status("document-uuid")

print("Result:", json.dumps(result, indent=2))

Download document

Download the completed signed document as PDF bytes.

pdf_bytes = await TurboSign.download("document-uuid")

# Save to file
with open("signed-contract.pdf", "wb") as f:
    f.write(pdf_bytes)

Void

Cancel/void a signature request.

result = await TurboSign.void_document("document-uuid", reason="Contract terms changed")

Resend

Resend signature request emails to specific recipients.

result = await TurboSign.resend_email("document-uuid", recipient_ids=["recipient-uuid-1", "recipient-uuid-2"])

Get audit trail

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

result = await TurboSign.get_audit_trail("document-uuid")

print("Result:", json.dumps(result, indent=2))

Error Handling

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

Error Classes

Error Class	Status Code	Description
`TurboDocxError`	varies	Base error class for all SDK errors
`AuthenticationError`	401	Invalid or missing API credentials
`ValidationError`	400	Invalid request parameters
`NotFoundError`	404	Document or resource not found
`RateLimitError`	429	Too many requests
`NetworkError`	-	Network connectivity issues

Handling Errors

import asyncio
from turbodocx_sdk import (
    TurboSign,
    TurboDocxError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    NetworkError,
)

async def send_with_error_handling():
    try:
        result = await TurboSign.send_signature(
            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",
            }],
            file_link="https://www.turbodocx.com/examples/turbodocx.pdf",
        )
    except AuthenticationError as e:
        print(f"Authentication failed: {e}")
        # Check your API key and org ID
    except ValidationError as e:
        print(f"Validation error: {e}")
        # Check request parameters
    except NotFoundError as e:
        print(f"Resource not found: {e}")
        # Document or recipient doesn't exist
    except RateLimitError as e:
        print(f"Rate limited: {e}")
        # Wait and retry
    except NetworkError as e:
        print(f"Network error: {e}")
        # Check connectivity
    except TurboDocxError as e:
        print(f"SDK error: {e}, status_code={e.status_code}, code={e.code}")

asyncio.run(send_with_error_handling())

Error Properties

All errors include these properties:

Property	Type	Description
`message`	`str`	Human-readable error description (via `str(error)`)
`status_code`	`int \| None`	HTTP status code (if applicable)
`code`	`str \| None`	Machine-readable error code

Python Types

The SDK uses Python type hints with Dict[str, Any] for flexible JSON-like structures.

Importing Types

from typing import Dict, List, Any, Optional

SignatureFieldType

String literal values for field types:

# Available field type values
field_types = [
    "signature",
    "initial",
    "date",
    "text",
    "full_name",
    "title",
    "company",
    "first_name",
    "last_name",
    "email",
    "checkbox",
]

Recipient

Recipient configuration for signature requests:

Property	Type	Required	Description
`name`	`str`	Yes	Recipient's full name
`email`	`str`	Yes	Recipient's email address
`signingOrder`	`int`	Yes	Signing order (1-indexed)

recipient: Dict[str, Any] = {
    "name": "John Doe",
    "email": "john@example.com",
    "signingOrder": 1
}

Field

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

Property	Type	Required	Description
`type`	`str`	Yes	Field type (see SignatureFieldType)
`recipientEmail`	`str`	Yes	Which recipient fills this field
`page`	`int`	No*	Page number (1-indexed)
`x`	`int`	No*	X coordinate in pixels
`y`	`int`	No*	Y coordinate in pixels
`width`	`int`	No*	Field width in pixels
`height`	`int`	No*	Field height in pixels
`defaultValue`	`str`	No	Default value (for checkbox: `"true"` or `"false"`)
`isMultiline`	`bool`	No	Enable multiline text
`isReadonly`	`bool`	No	Make field read-only (pre-filled)
`required`	`bool`	No	Whether field is required
`backgroundColor`	`str`	No	Background color (hex, rgb, or named)
`template`	`Dict`	No	Template anchor configuration

*Required when not using template anchors

Template Configuration:

Property	Type	Required	Description
`anchor`	`str`	Yes	Text anchor pattern like `{TagName}`
`placement`	`str`	Yes	`"replace"` \| `"before"` \| `"after"` \| `"above"` \| `"below"`
`size`	`Dict`	Yes	`{ "width": int, "height": int }`
`offset`	`Dict`	No	`{ "x": int, "y": int }`
`caseSensitive`	`bool`	No	Case sensitive search (default: False)
`useRegex`	`bool`	No	Use regex for anchor/searchText (default: False)

field: Dict[str, Any] = {
    "type": "signature",
    "page": 1,
    "x": 100,
    "y": 500,
    "width": 200,
    "height": 50,
    "recipientEmail": "john@example.com"
}

Request Parameters

Request configuration for create_signature_review_link and send_signature methods:

Parameter	Type	Required	Description
`recipients`	`List[Dict]`	Yes	Recipients who will sign
`fields`	`List[Dict]`	Yes	Signature fields configuration
`file`	`bytes`	Conditional	PDF file content as bytes
`file_name`	`str`	No	Original filename (used with `file` bytes)
`file_link`	`str`	Conditional	URL to document file
`deliverable_id`	`str`	Conditional	TurboDocx deliverable ID
`template_id`	`str`	Conditional	TurboDocx template ID
`document_name`	`str`	No	Document name
`document_description`	`str`	No	Document description
`sender_name`	`str`	No	Sender name (overrides the configured value)
`sender_email`	`str`	No**	Sender / reply-to email (overrides the configured value)
`cc_emails`	`List[str]`	No	Array of CC email addresses

File Source (Conditional)

Exactly one file source is required: file, file_link, deliverable_id, or template_id.

** sender_email is optional per call but required at the SDK level for TurboSign: it must be supplied via configure(), the TURBODOCX_SENDER_EMAIL environment variable, or this per-call parameter, otherwise the SDK raises a ValidationError.

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

Let an agent scaffold this for you

Installation​

Requirements​

Configuration​

Environment Variables​

Quick Start​

Send a Document for Signature​

Using Template-Based Fields​

File Input Methods​

1. File Upload (bytes)​

2. File URL (file_link)​

3. TurboDocx Deliverable ID​

4. TurboDocx Template ID​

API Reference​

Configure​

Prepare for review​

Prepare for signing​

Get status​

Download document​

Void​

Resend​

Get audit trail​

Error Handling​

Error Classes​

Handling Errors​

Error Properties​

Python Types​

Importing Types​

SignatureFieldType​

Recipient​

Field​

Request Parameters​

Additional Documentation​

Core API References​

Resources​