TurboSign API Integration

This comprehensive guide walks you through the TurboSign single-step API integration. Learn how to programmatically upload documents, configure recipients, set up signature fields, and send documents for electronic signatures using a single, streamlined API call.

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 GitHubFull install guide →

bash — turbodocx

$npx skills add TurboDocx/quickstart

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

Overview

The TurboSign API provides a simplified single-step process to prepare documents for electronic signatures. Instead of multiple API calls, you can now accomplish everything in one request.

Two Endpoint Options

TurboSign offers two single-step endpoints to fit different workflows:

1. Prepare for Review - Upload and get preview URL (no emails sent)
2. Prepare for Signing - Upload and send immediately (emails sent)

Key Features

• Single API Call: Upload document, add recipients, and configure fields in one request
• RESTful API: Standard HTTP methods with multipart/form-data
• Bearer Token Authentication: Secure API access using JWT tokens
• Multiple Recipients: Support for multiple signers with custom signing order
• Flexible Field Placement: Position signature fields using anchors or coordinates
• Multiple File Sources: Upload file, or reference deliverableId, templateId, or fileLink
• Real-time Status Updates: Track document status throughout the signing process
• Webhook Integration: Receive notifications when signing is complete

Prefer using an SDK?

We offer official SDKs that handle authentication, error handling, and type safety for you.

View all SDKs →

TLDR; Complete Working Example 🚀

Don't want to read all the details? Here's what you need to know:

Available Field Types

Type	Description	Use Case
signature	Electronic signature field	Legal signatures
initial	Initial field	Document initials, paragraph acknowledgments
date	Date picker field	Signing date, agreement date
full_name	Full name field	Automatically fills signer's complete name
first_name	First name field	Automatically fills signer's first name
last_name	Last name field	Automatically fills signer's last name
title	Title/job title field	Professional title or position
company	Company name field	Organization or company name
email	Email address field	Signer's email address
text	Generic text input field	Custom text, notes, or any other text input
checkbox	Checkbox field	Acknowledgments, consent, agreements

Quick Start: Prepare for Signing (Most Common)

Use this endpoint to send documents immediately for signing:

Loading code examples...

Alternative: Prepare for Review

Use this endpoint when you need a preview URL to verify field placement:

Loading code examples...

Quick Comparison

Feature	prepare-for-review	prepare-for-signing
Sends emails?	❌ No	✅ Yes
Returns preview URL?	✅ Yes	❌ No
Returns recipients?	✅ Yes	✅ Yes
Final status	REVIEW_READY	UNDER_REVIEW
Use when	Need to verify field placement	Ready to send immediately

Now that you've seen the whole thing, let's dive into the details...

Prerequisites

To have an AI coding agent scaffold the integration, install the TurboDocx Quickstart skill with npx skills add TurboDocx/quickstart and run /turbodocx-sdk turbosign in the agent.

Before you begin, ensure you have:

• API Access Token: Bearer token for authentication
• Organization ID: Your organization identifier
• PDF Document: Document ready for signature collection

Getting Your Credentials

1. Login to TurboDocx: Visit https://www.turbodocx.com
2. Navigate to Settings: Click your account avatar, then click Settings
3. API Keys Section: Open API keys (under Developers) to generate or retrieve your API access token
4. Organization ID: Copy your organization ID from the Features and integrations page

Authentication

All TurboSign API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Additional required headers for all requests:

x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Choosing Your Endpoint

TurboSign offers two single-step endpoints to fit different workflows. Choose the one that best matches your use case.

When to Use prepare-for-review

✅ Use this endpoint when you want to:

• Verify field placement before sending to recipients
• Get a preview URL to review the document in TurboSign's interface
• Manually trigger email sending after verifying field placement
• Ensure correct field positioning before recipients receive emails

Workflow: Upload → Get preview URL → Review in browser → Manually send when ready

When to Use prepare-for-signing

✅ Use this endpoint when you want to:

• Send documents immediately without preview step
• Automate the entire signature process end-to-end
• Use with verified templates or confident field positioning
• Skip manual review and send directly to recipients

Workflow: Upload → Emails sent automatically → Recipients sign

Endpoint 1: Prepare for Review

Creates a signature request and returns a preview URL. No emails are sent to recipients.

Endpoint

POST https://api.turbodocx.com/turbosign/single/prepare-for-review

Headers

Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Request Body (multipart/form-data)

⚠️ Important: Recipients and fields must be sent as JSON strings in form-data

Field	Type	Required	Description
file	File	Conditional*	PDF, DOCX, or PPTX file to upload
deliverableId	String (UUID)	Conditional*	Reference to existing deliverable
templateId	String (UUID)	Conditional*	Reference to existing template (DOCX, PPTX, or a PDF signature template). Required when any recipient has a role
fileLink	String (URL)	Conditional*	URL to download file from
documentName	String	No	Document name in TurboSign (max 255 chars)
documentDescription	String	No	Document description (max 1000 chars)
recipients	String (JSON)	Yes	JSON string array of recipient objects
fields	String (JSON)	Conditional**	JSON string array of field objects. Must not be empty. Optional only when a recipient has a role
senderName	String	No	Name of sender (max 255 chars). Defaults to your API key's name.
senderEmail	String (email)	Yes	Reply-to address on the signature email and the sender recorded in the audit trail
ccEmails	String (JSON)	No	JSON string array of CC email addresses
remindersEnabled	Boolean	No	Send reminder emails to signers who haven't signed
reminderDelay	String (JSON)	No	Time to the FIRST reminder, {"value":3,"unit":"days"}
reminderInterval	String (JSON)	No	Gap between later reminders
maxReminders	Number	No	Cap per signer, max 50. -1 unlimited, 0 none
expirationEnabled	Boolean	No	Close the signing window after expireAfter
expireAfter	String (JSON)	No	How long the document stays signable
expirationWarning	String (JSON)	No	How far before expiry warnings start. 0 = never warn
expirationWarningInterval	String (JSON)	No	Gap between warnings once they start

* File Source: Must provide exactly ONE of: file, deliverableId, templateId, or fileLink

** Fields: Required, unless at least one recipient names a template signer role. Omitting fields without a role returns 400 FieldsRequired. See Sending with signer roles.

A PDF template is sent as it was stored at upload: TurboDocx refuses password-protected PDFs, repairs damaged ones where it can, and flattens fillable form fields into the page (see PDF signature templates). The request's recipients and fields are used as sent. A signature setup saved on the template in the TurboDocx app is applied only when a recipient names one of its roles (see Sending with signer roles).

Reminders & expiration are optional

The eight schedule fields are per-document overrides. Omit any of them and that setting is inherited from your organization's E-Signature defaults; omit all of them and the document simply follows the org policy as it stands at send time. Both reminders and expiration ship off by default, so leaving these out preserves today's behaviour exactly.

The resolved schedule is frozen onto the document when it is sent — changing your org defaults later never alters a document already out for signature.

Durations are {value, unit} objects sent as JSON strings, because multipart/form-data cannot carry a nested value:

reminderDelay={"value":3,"unit":"days"}
expireAfter={"value":30,"unit":"hours"}

unit is "hours" or "days". value is a whole number, minimum 1 and at most 999 days (23976 hours) — except expirationWarning, where 0 means "never send a warning".

See Reminders & Expiration for the full behaviour.

senderEmail is required

senderEmail must be supplied on every API/SDK signature request. A request authenticated with an API key has no mailbox of its own, so TurboDocx rejects the request with HTTP 400 and the error code SenderEmailRequired rather than sending from an unmonitored address. senderName is optional — it defaults to the name of your API key (shown in the recipient's email and the audit trail); if no name can be resolved at all the API returns 400 SenderNameRequired.

TurboQuote works differently: quotes have no senderEmail request field — the sender is resolved from the org quote template. See Prepared By & Sender Identity.

Recipients JSON Format

Recipients must be stringified before adding to form-data:

const recipients = JSON.stringify([
  {
    name: "John Smith",
    email: "john.smith@company.com",
    signingOrder: 1,
    metadata: {
      color: "hsl(200, 75%, 50%)",
      lightColor: "hsl(200, 75%, 93%)",
    },
  },
  {
    name: "Jane Doe",
    email: "jane.doe@partner.com",
    signingOrder: 2,
    metadata: {
      color: "hsl(270, 75%, 50%)",
      lightColor: "hsl(270, 75%, 93%)",
    },
  },
]);
formData.append("recipients", recipients);

Fields JSON Format

Fields reference recipients by email (not recipientId) and must be stringified:

Template-based (recommended):

const fields = JSON.stringify([
  {
    recipientEmail: "john.smith@company.com",
    type: "signature",
    template: {
      anchor: "{Signature1}",
      placement: "replace",
      size: { width: 200, height: 80 },
      offset: { x: 0, y: 0 },
    },
    required: true,
  },
  {
    recipientEmail: "john.smith@company.com",
    type: "date",
    template: {
      anchor: "{Date1}",
      placement: "replace",
      size: { width: 150, height: 30 },
    },
    required: true,
  },
]);
formData.append("fields", fields);

Coordinate-based:

const fields = JSON.stringify([
  {
    recipientEmail: "john.smith@company.com",
    type: "signature",
    page: 1,
    x: 100,
    y: 200,
    width: 200,
    height: 80,
    pageWidth: 612,
    pageHeight: 792,
    required: true,
  },
]);
formData.append("fields", fields);

Sending with signer roles

A PDF template in TurboDocx can carry a saved signature setup: signer roles (for example "Client" and "Countersigner") with fields placed on the PDF for each role. Each role has a stable key (for example client), shown under Use via API on the template page (turn on Dev Mode to see it) and returned by Get Template Signature Setup. A role is either a slot with no saved signer, filled in each time you send, or it has a saved signer (a name and email used when you leave the role out). Roles saved before keys existed answer to signer_1, signer_2 and so on, by signing order.

Signer roles work with PDF signature templates only, because the saved field positions are measured on that PDF. To send a Word or PowerPoint template, generate a deliverable and send it with deliverableId.

How role keys are made

The key is made from the role name in TurboDocx: lowercase, with spaces and symbols turned into underscores.

Role name	Key
Client	client
Account Manager	account_manager
Counter-signer	counter_signer
Signer 1	signer_1

• A role left with the default name ("Signer 1", "Signer 2") has the key signer_1, signer_2. These keys follow the role's position, so they renumber if roles are reordered, added or removed. Give a role its own name if your code depends on it.
• If two roles would make the same key, the second gets a number, such as client_2. TurboDocx does not allow two roles with the same name, so this is rare.
• Once a template is saved, the key of a role you named never changes, even if you rename the role later.
• Keys are matched ignoring case.

To find the keys, turn on Dev Mode in TurboDocx. The template page then shows a Use via API panel, and the Code button on the send page shows Send this template by role. Both give ready-to-paste code with your template ID, organization ID and role keys. You can also call Get Template Signature Setup.

Use the key, not the display name

Pass the key (signer_1), not the name shown in the app (Signer 1). A display name fails with UnknownSignerRole, and the error lists the valid keys: Unknown role "Signer 1". This template's roles are: signer_1, signer_2.

To send such a template, pass its templateId and give each recipient a role:

curl -X POST https://api.turbodocx.com/turbosign/single/prepare-for-signing \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-rapiddocx-org-id: YOUR_ORGANIZATION_ID" \
  -F "templateId=TEMPLATE_ID" \
  -F "senderEmail=you@company.com" \
  -F 'recipients=[{"role":"client","name":"Jane Doe","email":"jane@client.com"}]'

How a role send behaves:

• Role keys are matched case-insensitively. role requires templateId.
• Fields come from the template. The fields saved for each role are placed for the signer who fills it, so fields can be left out. Any fields you do pass are added to the template's (for example an extra witness signature).
• Roles you leave out use the template's saved signer. A role with no saved signer must be filled, or the request fails with SignerRoleUnfilled.
• Signing order follows the template's role order, then any recipients without a role in their own signingOrder. The final order is renumbered so it runs 1, 2, 3 and so on. A recipient with a role needs no signingOrder.
• Template defaults fill the gaps. The template's saved CC emails, document description, document name and reminder and expiration settings apply to anything the request leaves out. Values in the request always win.
• Identity verification. A role's saved verification choice applies unless the recipient sets its own identityVerification. A role saved with SMS verification needs the recipient's phone. If your organization no longer allows a role's saved choice (for example SMS was turned off), the organization default applies instead of failing the send. A choice you set on the recipient yourself is still checked as usual. See the recipient in the embedded signing reference for those fields.
• Every signer needs a field. A role send where a signer ends up with no fields fails with SignerHasNoFields (Prepare for Review skips this check, because you place fields in the review screen afterwards).
• Without roles nothing changes. fields is still required when no recipient names a role.

Claiming a role with a different signer

A role with a saved signer can still be given to someone else for one send. Pass a recipient with that role and the new person's name and email, and the new person takes the role and all of its fields. The template is not changed.

[{ "role": "countersigner", "name": "Alex Kim", "email": "alex@acme.com" }]

What changes for the new signer:

• Name and email fields are filled from the new recipient. A first name field takes the first word of name and a last name field takes the rest. If that leaves a value empty (a one-word name has no last name), the field is left blank and unlocked so the signer types it.
• Title and company fields lose the saved person's values and are unlocked, so the new signer fills them in.
• A field set to keep its own default value in TurboDocx keeps that value.
• Identity verification keeps the role's saved choice unless the recipient sets its own. The saved person's phone is never used: a role saved with SMS verification needs the new recipient's phone, or the send fails with OtpPhoneRequired.
• Email addresses must stay unique. If the new signer's email matches another role's signer, or a recipient without a role, the send fails with DuplicateRoleEmail.

Signer role errors

These return 400 with a body of the form { "message": "...", "type": "..." }:

type	Example message	Cause
UnknownSignerRole	Unknown role "clinet". This template's roles are: client, countersigner	A role does not match any of the template's role keys
DuplicateSignerRole	Role "client" was given more than one recipient	Two recipients name the same role
SignerRoleUnfilled	Role "client" needs a signer. Pass recipients: [{ role: "<role>", name, email }]	A role has no saved signer and no recipient fills it
TemplateHasNoSignerRoles		The template has no saved signer roles
RoleRequiresTemplate		A recipient has a role but the request has no templateId
DuplicateRoleEmail		Two roles resolved to the same email address, or a recipient without a role has a role signer's email
SignerHasNoFields	Signer "Jane Doe" has no fields to sign. Place a field for them or remove them.	A signer ends up with no fields after the template's fields are placed
OtpPhoneRequired		A role requires SMS verification and the recipient has no phone
FieldsRequired		fields was omitted and no recipient names a role
TemplateRolesNeedPdfTemplate		Roles were sent for a Word or PowerPoint template

Document and field errors

These also return 400 with a body of the form { "message": "...", "type": "..." } (the signature setup endpoints return { "error": "...", "code": "..." } instead):

type	Example message	Cause
FieldsRequired	fields is required. Leave it out only when sending a templateId whose recipients name a role (recipients[].role).	fields was omitted or empty and no recipient names a role
FieldPageOutOfRange	A field is placed on page 5, but the document has 3 pages.	A coordinate-based field has a page the document doesn't have
SignatureSetupTemplateMismatch		A signature setup placed on an uploaded PDF was saved onto a template that isn't a PDF template
SignatureSetupPageOutOfRange	A field is placed on page 5, but this PDF has 3 pages.	A signature setup saved onto a PDF template has a field past the PDF's last page

Locked templates and permissions

• Saving or deleting a template's signature setup returns 423 while someone is editing the template in TurboDocx. Retry once they have finished.
• Get Template Signature Setup requires the administrator, contributor or user role. A viewer is refused.

Reading a draft's signers

GET /turbosign/documents/{documentId}/with-recipients returns a draft and its signers. When the draft was created from a template with signer roles, each signer that fills a role also has templateRoleLabel: the role's name as shown in TurboDocx (for example "Client"). It is for display only. To send by role, pass the role's key from Get Template Signature Setup, not this label.

Example response, trimmed to the signer fields:

{
  "data": {
    "document": { "id": "DOCUMENT_ID", "name": "Service Agreement", "status": "DRAFT" },
    "recipients": [
      {
        "id": "RECIPIENT_ID",
        "name": "Jane Doe",
        "email": "jane@client.com",
        "signingOrder": 1,
        "metadata": {},
        "otpChannel": "none",
        "phone": null,
        "templateRoleLabel": "Client"
      }
    ]
  }
}

A signer that doesn't fill a template role has no templateRoleLabel.

Editing a draft's signers

When you change a draft's signers with PATCH /turbosign/documents/{documentId}/update-with-recipients, the recipients you send replace the draft's current signers. A recipient with an id is updated in place; a recipient without an id is added as a new signer; a current signer you leave out is removed, along with that signer's fields. This also applies to a draft created from a template, so sending recipients without id replaces the signers the template saved. The draft must still be in DRAFT status, otherwise the request returns 409.

Response

{
  "success": true,
  "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
  "status": "REVIEW_READY",
  "previewUrl": "https://www.turbodocx.com/sign/preview/abc123...",
  "recipients": [
    {
      "id": "5f673f37-9912-4e72-85aa-8f3649760f6b",
      "name": "John Smith",
      "email": "john.smith@company.com",
      "signingOrder": 1,
      "metadata": {
        "color": "hsl(200, 75%, 50%)",
        "lightColor": "hsl(200, 75%, 93%)"
      }
    }
  ],
  "message": "Document prepared for review. Use the preview URL to review and assign fields."
}

Response Fields

Field	Type	Description
success	Boolean	Request success status
documentId	String (UUID)	Unique document identifier - save for tracking
status	String	Document status (REVIEW_READY)
previewUrl	String (URL)	URL to preview and verify document
recipients	Array	Array of recipient objects with generated IDs
message	String	Human-readable success message

Code Examples

Loading code examples...

Next Steps After Review

Once you've reviewed the document via the preview URL click "Send for Signing" button on the preview page to send emails to recipients

Endpoint 2: Prepare for Signing

Creates a signature request and immediately sends emails to recipients. Use this for production workflows when you're confident in your field positioning.

Endpoint

POST https://api.turbodocx.com/turbosign/single/prepare-for-signing

Headers

Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Request Body (multipart/form-data)

The request format is identical to prepare-for-review. See the "Endpoint 1: Prepare for Review" section above for detailed field documentation.

Signer roles work the same way here: pass templateId and give each recipient a role. See Sending with signer roles.

Response

{
  "success": true,
  "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
  "status": "UNDER_REVIEW",
  "recipients": [
    {
      "id": "5f673f37-9912-4e72-85aa-8f3649760f6b",
      "name": "John Smith",
      "email": "john.smith@company.com",
      "signingOrder": 1,
      "metadata": {
        "color": "hsl(200, 75%, 50%)",
        "lightColor": "hsl(200, 75%, 93%)"
      }
    }
  ],
  "message": "Document sent for signing. Emails are being sent to recipients."
}

Response Fields

Field	Type	Description
success	Boolean	Request success status
documentId	String (UUID)	Unique document identifier - save for tracking
status	String	Document status (UNDER_REVIEW)
recipients	Array	Array of recipient objects with generated IDs
message	String	Human-readable success message

⚠️ Note: This endpoint returns immediately after creating the document. Email sending happens asynchronously in the background. Use webhooks to receive notification when the document is fully signed. Documents sent with an API key don't email a "fully signed" copy to the sender; signers and CC recipients still get their completion emails.

Code Examples

Loading code examples...

Need to resend emails?

If a recipient hasn't received or has lost their signing email, you can resend it using the Resend Email endpoint. You'll need the recipientIds from the response of this endpoint.

Endpoint 3: Download Signed Document

After a document has been signed by all recipients (status: COMPLETED), you can download the final signed PDF document.

Endpoint

GET https://api.turbodocx.com/turbosign/documents/{documentId}/download

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
documentId	String (UUID)	Yes	The unique identifier of the document

Response

{
  "downloadUrl": "https://s3.amazonaws.com/bucket/path/to/document.pdf?X-Amz-...",
  "fileName": "Signed_Contract_2024.pdf"
}

Response Fields

Field	Type	Description
downloadUrl	String	Presigned S3 URL to download the signed PDF (expires in 1 hour)
fileName	String	Original filename of the signed document

Document Status Requirement

This endpoint only returns a download URL when the document status is COMPLETED. If the document is still pending signatures, you will receive an error response.

Usage Notes

• The presigned URL expires after 1 hour. Request a new URL if the previous one has expired.
• The downloaded PDF includes all signatures embedded and is legally binding.
• For large documents, consider streaming the download rather than loading the entire file into memory.

Endpoint 4: Get Audit Trail

Retrieve the complete audit trail for a document, including all events and timestamps. The audit trail provides a tamper-evident record of all actions taken on the document using a cryptographic hash chain.

Endpoint

GET https://api.turbodocx.com/turbosign/documents/{documentId}/audit-trail

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
documentId	String (UUID)	Yes	The unique identifier of the document

Response

{
  "data": {
    "document": {
      "id": "4a20eca5-7944-430c-97d5-fcce4be24296",
      "name": "Service Agreement 2024"
    },
    "auditTrail": [
      {
        "id": "entry-uuid-1",
        "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
        "actionType": "prepared_for_review",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "previousHash": null,
        "currentHash": "a1b2c3d4e5f6...",
        "createdOn": "2024-01-15T10:30:00.000Z",
        "details": {
          "ipAddress": "192.168.1.100",
          "userAgent": "Mozilla/5.0..."
        },
        "user": {
          "name": "Admin User",
          "email": "admin@company.com"
        },
        "userId": "user-uuid-1"
      },
      {
        "id": "entry-uuid-2",
        "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
        "actionType": "document_sent",
        "timestamp": "2024-01-15T10:31:00.000Z",
        "previousHash": "a1b2c3d4e5f6...",
        "currentHash": "b2c3d4e5f6g7...",
        "createdOn": "2024-01-15T10:31:00.000Z",
        "details": {
          "recipientCount": 2
        },
        "user": {
          "name": "Admin User",
          "email": "admin@company.com"
        },
        "userId": "user-uuid-1"
      },
      {
        "id": "entry-uuid-3",
        "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
        "actionType": "document_viewed",
        "timestamp": "2024-01-15T11:00:00.000Z",
        "previousHash": "b2c3d4e5f6g7...",
        "currentHash": "c3d4e5f6g7h8...",
        "createdOn": "2024-01-15T11:00:00.000Z",
        "details": {
          "ipAddress": "10.0.0.50"
        },
        "recipient": {
          "name": "John Smith",
          "email": "john.smith@company.com"
        },
        "recipientId": "recipient-uuid-1"
      },
      {
        "id": "entry-uuid-4",
        "documentId": "4a20eca5-7944-430c-97d5-fcce4be24296",
        "actionType": "document_signed",
        "timestamp": "2024-01-15T11:05:00.000Z",
        "previousHash": "c3d4e5f6g7h8...",
        "currentHash": "d4e5f6g7h8i9...",
        "createdOn": "2024-01-15T11:05:00.000Z",
        "details": {
          "signatureType": "electronic",
          "ipAddress": "10.0.0.50"
        },
        "recipient": {
          "name": "John Smith",
          "email": "john.smith@company.com"
        },
        "recipientId": "recipient-uuid-1"
      }
    ]
  }
}

Response Fields

Document Object

Field	Type	Description
id	String (UUID)	Document identifier
name	String	Document name

Audit Trail Entry Object

Field	Type	Description
id	String (UUID)	Unique identifier for the audit entry
documentId	String (UUID)	Document this entry belongs to
actionType	String	Type of action (see Action Types below)
timestamp	String (ISO)	When the action occurred
previousHash	String	Hash of the previous entry (null for first entry)
currentHash	String	Hash of this entry (forms hash chain)
createdOn	String (ISO)	When the entry was created
details	Object	Additional action-specific details
user	Object	User who performed action (for sender actions)
userId	String (UUID)	User ID (when applicable)
recipient	Object	Recipient who performed action (for signer actions)
recipientId	String (UUID)	Recipient ID (when applicable)

Action Types

Action Type	Description
prepared_for_review	Document was uploaded and prepared for review
document_sent	Document was sent to recipients for signing
document_viewed	Recipient opened/viewed the document
document_signed	Recipient signed the document
document_voided	Document was voided/cancelled
document_resent	Reminder/resend email was sent to recipient
email_notification_sent	Signing invitation email was sent
cc_email_notification_sent	CC notification email was sent

Hash Chain Verification

The audit trail uses a cryptographic hash chain for tamper-evidence:

• Each entry's currentHash is computed from the entry data plus the previousHash
• The first entry has previousHash: null
• To verify integrity, recompute each hash and compare
• Any modification to historical entries would break the chain

This provides strong evidence that the audit trail has not been tampered with after creation.

Usage Notes

• The audit trail is available at any document status (not just completed documents)
• All timestamps are in ISO 8601 format (UTC timezone)
• The details object varies by action type and may contain IP addresses, user agents, and other contextual information
• Audit trail entries are immutable and cannot be modified or deleted

Endpoint 5: Get Recipients

Retrieve every recipient on a document with their signing status, their email history, and who sent the document. This is the endpoint to poll when you want to know who has signed and who you are still waiting on.

Endpoint

GET https://api.turbodocx.com/turbosign/documents/{documentId}/recipients

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
documentId	String (UUID)	Yes	The unique identifier of the document

Response

{
  "data": {
    "document": {
      "id": "4a20eca5-7944-430c-97d5-fcce4be24296",
      "name": "Service Agreement 2024",
      "status": "under_review",
      "createdOn": "2024-01-15T10:30:00.000Z",
      "sentOn": "2024-01-15T10:35:00.000Z",
      "expiresAt": null,
      "sentBy": {
        "name": "Jane Sender",
        "email": "jane@acme.com"
      }
    },
    "recipients": [
      {
        "id": "recipient-uuid-1",
        "name": "John Doe",
        "email": "john@example.com",
        "status": "completed",
        "effectiveStatus": "completed",
        "signedOn": "2024-01-16T14:02:00.000Z",
        "signingOrder": 1,
        "delivery": {
          "firstSentOn": "2024-01-15T10:35:00.000Z",
          "lastSentOn": "2024-01-15T10:35:00.000Z",
          "totalSent": 1,
          "reminderCount": 0,
          "lastRemindedAt": "2024-01-15T10:35:00.000Z",
          "warningCount": 0,
          "lastWarningAt": null
        }
      },
      {
        "id": "recipient-uuid-2",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "status": "pending",
        "effectiveStatus": "pending",
        "signedOn": null,
        "signingOrder": 2,
        "delivery": {
          "firstSentOn": "2024-01-16T14:02:05.000Z",
          "lastSentOn": "2024-01-20T09:00:00.000Z",
          "totalSent": 2,
          "reminderCount": 1,
          "lastRemindedAt": "2024-01-20T09:00:00.000Z",
          "warningCount": 0,
          "lastWarningAt": null
        }
      }
    ],
    "summary": {
      "total": 2,
      "pending": 1,
      "viewed": 0,
      "completed": 1,
      "voided": 0,
      "expired": 0,
      "waitingOn": 1
    }
  }
}

Response Fields

document

Field	Type	Description
status	String	Document-level status (draft, under_review, completed, voided, expired, …)
sentOn	String | null	When the document was dispatched to recipients; null while it is still a draft
expiresAt	String | null	When the signing window closes; null if it never expires
sentBy	Object	{ name, email } — the real sender, never the internal service account

recipients[]

Field	Type	Description
status	String	Raw status: pending, viewed or completed
effectiveStatus	String	pending, viewed, completed, voided or expired — use this for display
signedOn	String | null	When this recipient signed; null while pending or viewed
signingOrder	Number	Position in the signing sequence
delivery	Object	This recipient's email history (see below)

recipients[].delivery

Field	Type	Description
firstSentOn	String | null	First email of any kind; null if this recipient has never been emailed
lastSentOn	String | null	Most recent email of any kind
totalSent	Number	Signature request + resends + reminders + expiry warnings + terminal notices
reminderCount	Number	Automatic (scheduled) reminders only — see the note below
lastRemindedAt	String | null	When the reminder cadence clock was last reset — see the note below
warningCount	Number	Expiry warnings sent. Only a warning touches this
lastWarningAt	String | null	When the last expiry warning went out. Only a warning touches this

reminderCount and lastRemindedAt do not mean what their names suggest

reminderCount counts automatic (scheduled) reminders only. It is the counter that the maxReminders schedule setting caps. A manual "remind now" (the Send Reminder action) is a standalone nudge that deliberately does not consume the cap budget, so it does not increment this — even though the email it sends does appear in totalSent. A recipient can therefore read reminderCount: 0 while reminder emails have genuinely been sent.

lastRemindedAt is a cadence clock, not a record of a reminder. Four things stamp it: the initial signature-request send (so the first reminder is measured from the invitation), each scheduled reminder, each manual "remind now", and each expiry warning (a deliberate cross-reset so a reminder never lands adjacent to a warning). Only the second of those bumps reminderCount.

The common consequence: a freshly-sent document returns a non-null lastRemindedAt equal to the invitation timestamp, alongside reminderCount: 0. That is correct — nobody has been reminded. To answer "have we actually chased this person", read totalSent (all emails) or the audit trail's reminder_sent entries, not reminderCount.

warningCount / lastWarningAt have no such caveat — only an expiry warning touches them.

summary

Counts by effectiveStatus, plus waitingOn — the recipients who have not finished (pending + viewed). waitingOn drops to zero once the document reaches a terminal state.

Two status fields, and they differ on purpose

There is no per-recipient declined, voided or expired state in the system — a recipient row only ever holds pending, viewed or completed. That means on a voided or expired document, an unsigned signer still reads pending in status.

effectiveStatus layers the document's outcome on top, so that same signer reads voided or expired. Branch on effectiveStatus, not status, or you will chase people whose signing links are already dead.

A completed signature is never revoked: someone who signed before the document was voided still reads completed in both fields.

effectiveStatus also reflects a lapsed deadline immediately. A document past its expiresAt keeps its old status until a background sweep updates it, but the signing links are already refused at that moment — so effectiveStatus reports expired right away rather than waiting for the row to change.

Usage Notes

• Available at any document status, including drafts (a draft returns its recipients with sentOn: null and delivery.totalSent: 0)
• Recipients are returned ordered by signingOrder
• delivery counts emails to that signer only — CC notifications are excluded, since a CC address is not a signer
• On a document with a signing order, only the current turn has been emailed; delivery.totalSent === 0 distinguishes "not yet invited" from "invited and not acted"
• Returns 404 if the document does not exist or belongs to another organization
• All timestamps are ISO 8601 (UTC)

Endpoint 6: Resend Email

Resend signature request emails to one or more recipients who haven't yet completed signing. Only recipients at the current signing order who haven't completed are eligible for resend.

This applies to documents that have already been sent for signing — there must be an original invitation to resend. A document still in review (no signing emails sent yet) has no eligible recipients.

Endpoint

POST https://api.turbodocx.com/turbosign/documents/{documentId}/resend-email

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
documentId	String (UUID)	Yes	The unique identifier of the document

Request Body (JSON)

Field	Type	Required	Description
recipientIds	Array (UUID[])	Yes	Array of recipient UUIDs to resend emails to (min 1, unique)

{
  "recipientIds": [
    "5f673f37-9912-4e72-85aa-8f3649760f6b",
    "7a891c23-4d56-4e78-9abc-def012345678"
  ]
}

Where do I get recipient IDs?

Recipient IDs are returned in the response of the Prepare for Review (Endpoint 1) and Prepare for Signing (Endpoint 2) endpoints. Save these IDs when creating your signature request.

Response

{
  "data": {
    "success": true,
    "recipientCount": 2
  }
}

Response Fields

Field	Type	Description
data.success	Boolean	Whether the resend was successful
data.recipientCount	Number	Number of recipients who received the email

Error Responses

Status	Error Message	Cause
404	"Document not found"	Document doesn't exist, has been deleted, or belongs to another organization
400	"All recipients have already completed signing"	No eligible recipients remain
400	"Some recipients are not eligible for email resend at this time"	Requested recipients aren't at the current signing order or already completed

The 400 "not eligible" error also returns an invalidRecipientIds array showing which IDs were rejected:

{
  "error": "Some recipients are not eligible for email resend at this time",
  "invalidRecipientIds": ["7a891c23-4d56-4e78-9abc-def012345678"]
}

To recover, retry the request without the listed IDs, or wait until those recipients reach the current signing order before resending to them.

Usage Notes

• Only recipients at the current signing order who haven't completed signing are eligible for resend. If your document uses sequential signing (signingOrder 1, 2, 3...), that means the current active step only.
• The request is all-or-nothing: if any requested ID is ineligible, the whole request is rejected with a 400 and no emails are sent. Fix the recipientIds and retry.
• Each resend creates a document_resent entry in the audit trail for tracking
• The recipientIds array must contain at least one ID and all IDs must be unique UUIDs

Endpoint 7: Send Reminder

Send a reminder email to a document's outstanding signers.

This is a standalone nudge, deliberately decoupled from the automatic reminder schedule: it ignores the configured cadence, works even when reminders are disabled or the per-signer cap is already spent, and does not consume that cap. Use it when someone asks you to "chase them again" outside the normal rhythm.

Distinct from Resend Email: resend re-sends the original invitation; remind sends the reminder copy.

Endpoint

POST https://api.turbodocx.com/turbosign/documents/{documentId}/send-reminder

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
documentId	String (UUID)	Yes	The unique identifier of the document

Request Body (JSON)

Field	Type	Required	Description
recipientIds	Array (UUID[])	No	Subset to remind. Omit to remind every eligible signer. Min 1, unique

Omit the body entirely (or send {}) to remind everyone whose turn it is:

{}

Or name specific signers:

{
  "recipientIds": ["5f673f37-9912-4e72-85aa-8f3649760f6b"]
}

Don't send an empty array

recipientIds must contain at least one ID when the key is present. Sending {"recipientIds": []} is rejected with a 400. To remind everyone, omit the key.

Response

{
  "data": {
    "results": [
      { "recipientId": "5f673f37-9912-4e72-85aa-8f3649760f6b", "status": "sent", "reminderCount": 2, "phase": "reminder" },
      { "recipientId": "7a891c23-4d56-4e78-9abc-def012345678", "status": "skipped_wrong_order" }
    ]
  }
}

Response Fields

Field	Type	Description
data.results	Array	One entry per recipient considered — including those skipped
results[].recipientId	String	The recipient this outcome refers to
results[].status	String	What happened — see the table below
results[].reminderCount	Number	Reminder count after the send. Only meaningful when sent
results[].phase	String	reminder or expiring — which email copy was used

A recipient who was not emailed is reported rather than silently dropped, so you can tell nobody received anything:

status	Meaning
sent	The reminder email was sent
failed	The send was attempted and the mail transport rejected it
skipped_completed	That recipient has already signed
skipped_wrong_order	They're at a later signing order — it isn't their turn yet
skipped_not_due	Scheduled path only: their next reminder isn't due
skipped_max_reached	Scheduled path only: their reminder cap is spent
skipped_disabled	Scheduled path only: reminders are off for this document
skipped_claim_lost	A concurrent request won the send; no duplicate was sent

Error Responses

Status	Error Message	Cause
404	"Document not found"	Document doesn't exist, has been deleted, or belongs to another organization
409	"This document has expired, so its signers can no longer be reminded."	The signing window has closed — the link is dead, so a reminder would be useless
409	"This document has been voided, so its signers can no longer be reminded."	The document was voided
400	"Some recipients are not eligible for a reminder at this time"	A named recipient isn't a current-order pending signer

The 409 responses carry code: "DocumentNotActionable" plus the document's status, so a client can refresh a stale row rather than guessing.

The 400 returns an invalidRecipientIds array showing which IDs were rejected. The request is all-or-nothing — if any named ID is ineligible, no emails are sent:

{
  "error": "Some recipients are not eligible for a reminder at this time",
  "invalidRecipientIds": ["7a891c23-4d56-4e78-9abc-def012345678"]
}

Usage Notes

• Only recipients at the current signing order who haven't completed are eligible.
• Unlike the automatic schedule, this is not gated by remindersEnabled or maxReminders, and it does not increment the reminder count — so it works on a document that never turned reminders on, or one whose cap is already spent.
• Each send creates a reminder_sent entry in the audit trail, recorded against the user who triggered it.

---

Endpoint 8: Get Template Signature Setup

List the signer roles saved on a template, so you know which role keys to pass when sending it with signer roles.

Endpoint

GET https://api.turbodocx.com/turbosign/templates/{templateId}/signature-setup

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
templateId	String (UUID)	Yes	The unique identifier of the template

Response

{
  "data": {
    "templateId": "TEMPLATE_ID",
    "roles": [
      {
        "key": "client",
        "label": "Client",
        "order": 1,
        "hasSavedSigner": false,
        "fieldCount": 3
      },
      {
        "key": "countersigner",
        "label": "Countersigner",
        "order": 2,
        "hasSavedSigner": true,
        "defaultName": "Sam Lee",
        "defaultEmail": "sam@acme.com",
        "fieldCount": 2
      }
    ]
  }
}

Response Fields

Field	Type	Description
data.templateId	String	The template's ID
data.roles	Array	The template's signer roles, in signing order
data.roles[].key	String	The value to pass as a recipient's role
data.roles[].label	String	The role's name as shown in TurboDocx
data.roles[].order	Number	The role's signing order
data.roles[].hasSavedSigner	Boolean	true when the template has a saved signer, used if you leave the role out
data.roles[].defaultName	String	The saved signer's name. Present only when hasSavedSigner is true
data.roles[].defaultEmail	String	The saved signer's email. Present only when hasSavedSigner is true
data.roles[].fieldCount	Number	How many fields are saved for the role

Error Responses

Status	type	Cause
404	SignatureSetupNotFound	"No saved signature setup found for this template": the template doesn't exist in your organization, or has no saved signature setup
400		templateId is not a valid UUID

Usage Notes

• Works with an API key or a user token. The caller needs the administrator, contributor or user role; the viewer role is refused, because the response lists saved signer emails.
• The same role keys are shown in the app under Use via API on the template page when Dev Mode is on.
• Roles saved before keys existed are returned with keys signer_1, signer_2 and so on.

Endpoint 9: Update Template Signature Settings

Change the settings of a template's saved signature setup: CC recipients, the email message, reminders and expiration, and the document name. The signer roles, their keys and the fields are never changed, so integrations that send the template by role keep working. This is what Edit next to Email to signers or Reminders & expiration does on the template's page in TurboDocx (see Change or remove the setup).

Endpoint

PATCH https://api.turbodocx.com/turbosign/templates/{templateId}/signature-setup/settings

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
Content-Type: application/json
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
templateId	String (UUID)	Yes	The unique identifier of the template

Request Body (JSON)

Send at least one of these. A setting you leave out keeps its saved value.

Field	Type	Description
ccEmails	Array	CC email addresses copied on every document sent from the template. Up to 15, no duplicates. Replaces the saved list; [] clears it
documentDescription	String	The message in the signature email (max 1000 chars). "" clears it
scheduleOverrides	Object	Reminder and expiration settings for this template, using the same eight fields as the schedule fields at send time (no expiresAt). Replaces the saved overrides; {} follows your organization's defaults
documentName	String	The name documents are sent under (max 255 chars). PDF signature templates only; ignored for a Word or PowerPoint template. "" uses the template's name

Any other key, such as roles or fields, is rejected with 400.

curl -X PATCH https://api.turbodocx.com/turbosign/templates/TEMPLATE_ID/signature-setup/settings \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-rapiddocx-org-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ccEmails": ["legal@acme.com"],
    "documentDescription": "Please review and sign the attached agreement.",
    "scheduleOverrides": {
      "remindersEnabled": true,
      "reminderDelay": { "value": 3, "unit": "days" }
    }
  }'

Response

{
  "data": {
    "templateId": "TEMPLATE_ID",
    "setup": {
      "roles": [ ... ],
      "fields": [ ... ],
      "ccEmails": ["legal@acme.com"],
      "documentDescription": "Please review and sign the attached agreement.",
      "scheduleOverrides": {
        "remindersEnabled": true,
        "reminderDelay": { "value": 3, "unit": "days" }
      },
      "savedOn": "2026-10-20T14:30:00.000Z"
    }
  }
}

data.setup is the template's whole saved signature setup after the change, including its unchanged roles and fields.

Error Responses

Errors return { "message": "...", "type": "...", "error": "...", "code": "..." }, where type and code hold the same value.

Status	type	Cause
400		No setting was sent (Send at least one of ccEmails, documentDescription, scheduleOverrides, documentName), an unknown key was sent, or a value is invalid
400	CcMatchesSigner	A CC address is also a saved signer on the template
404	SignatureSetupNotFound	The template has no saved signature setup
404	TemplateNotFound	The template doesn't exist in your organization
423		Someone is editing the template in TurboDocx. Retry once they have finished

Usage Notes

• Requires the administrator or contributor role.
• Your organization's own reminder and expiration settings are never changed. scheduleOverrides only applies to documents sent from this template.

Endpoint 10: Delete Template Signature Setup

Remove a template's saved signature setup: its signer roles, fields, CC recipients, message, reminders and document name. Documents already sent are not affected. New sends from the template start with no signers or fields, and a role send fails with TemplateHasNoSignerRoles.

Endpoint

DELETE https://api.turbodocx.com/turbosign/templates/{templateId}/save-signature-setup

Headers

Authorization: Bearer YOUR_API_TOKEN
x-rapiddocx-org-id: YOUR_ORGANIZATION_ID
User-Agent: TurboDocx API Client

Path Parameters

Parameter	Type	Required	Description
templateId	String (UUID)	Yes	The unique identifier of the template

Response

{
  "data": {
    "templateId": "TEMPLATE_ID"
  }
}

Error Responses

Status	Body	Cause
404	{ "error": "Template not found", "code": "TemplateNotFound" }	The template doesn't exist in your organization
423	{ "error": "Resource is locked", ... }	Someone is editing the template in TurboDocx. Retry once they have finished

Usage Notes

• Requires the administrator or contributor role.
• Deleting a template that has no saved setup also returns 200.
• To change only the settings and keep the roles and fields, use Update Template Signature Settings instead.

Send a template set up in TurboDocx

When the signers and fields are already set up on a template in TurboDocx, an integration only needs to say who fills each role.

1. In TurboDocx, upload the PDF as a template, add a role for each signer (for example "Client" and "Countersigner"), drag each role's fields onto the page and save the signature setup. Give a role a saved signer if the same person always signs it.
2. Look up the role keys with Get Template Signature Setup, or copy them from Use via API on the template page (shown with Dev Mode on).
3. Send with Prepare for Signing (or Prepare for Review), passing templateId and one recipient per role you want to fill. Leave out fields and signingOrder:

curl -X POST https://api.turbodocx.com/turbosign/single/prepare-for-signing \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-rapiddocx-org-id: YOUR_ORGANIZATION_ID" \
  -F "templateId=TEMPLATE_ID" \
  -F "senderEmail=you@company.com" \
  -F 'recipients=[{"role":"client","name":"Jane Doe","email":"jane@client.com"}]'

Here client is filled by Jane Doe and countersigner, left out, goes to the signer saved on the template. See Sending with signer roles for the full rules and errors. The SDKs support the same flow; see Send a template set up in TurboDocx in the TurboSign SDK guide.

---

Reminders & Expiration

Two independent, opt-in features you can configure organization-wide in E-Signature Settings → Reminders & Expiration, or per-document via the schedule fields on either send endpoint.

Both ship off by default. A document sent without any schedule fields behaves exactly as it always has: no reminders, no expiry.

The schedule

Field	Default	Meaning
remindersEnabled	false	Send reminder emails at all
reminderDelay	3 days	Time to the first reminder, measured from that signer's invitation
reminderInterval	3 days	Gap between subsequent reminders
maxReminders	5	Cap per signer, max 50. -1 unlimited, 0 none. Never caps expiry warnings
expirationEnabled	false	Expire the document at all
expireAfter	120 days	How long the document stays signable, counted from sending
expirationWarning	3 days	How far before expiry warnings start. 0 = never warn
expirationWarningInterval	1 day	Gap between warnings once they start

reminderDelay and reminderInterval are separate because a single interval can't express "first at 3 days, then every 5". expirationWarning / expirationWarningInterval mirror that split exactly.

Two independent tracks

Reminders and expiry warnings run as two separate clocks, so a signer gets the full escalating stream — reminders keep coming even after the warning window opens. The two are coordinated so they never collide: on any given tick a due warning takes priority and restarts the reminder clock, so a signer never receives a reminder and a warning at the same moment.

Expiry warnings also still fire when reminders are off or capped — the deadline notice belongs to expiration, not to reminders.

Expiry

When expirationEnabled is on, the document carries an absolute deadline:

• expiresAt — an ISO timestamp on the document, absent when it has no deadline.
• Once that instant passes, every signing link returns HTTP 410 with code: "DocumentExpired", and the document moves to the terminal status expired.
• Expiry is enforced in real time on every signing request, so a link stops working exactly on time regardless of background processing.

A document that was already completed keeps working — the deadline exists to stop signing, and signing is already finished.

Validation

The API rejects contradictory combinations with 400 and error: "InvalidSignatureSchedule", plus a machine-readable data.code and the conflicting data.fields:

Code	Rule
ExpiryWindowTooShort	expireAfter must be at least one hour
WarningExceedsExpiry	expirationWarning must be less than expireAfter
WarningIntervalTooShort	expirationWarningInterval must be at least one hour when warnings are on
ReminderDelayExceedsExpiry	The first reminder must fall inside the expiry window, or it would never send
ReminderIntervalExceedsExpiry	Follow-up reminders must fit inside the window

The canonical mistake these prevent: "remind every 4 days" with "expire in 2 days" — the document would die before the first nudge was ever due, and you'd believe reminders were on while no email ever sent.

---

Recipients Reference

Recipient Properties

Each recipient object in the recipients array should contain the following properties:

Property	Type	Required	Description
name	String	Yes	Full name of the recipient/signer
email	String (email)	Yes	Email address of the recipient (must be unique)
signingOrder	Number	Conditional	Order in which recipient should sign (starts at 1). Not needed on a recipient with a role
role	String	No	Template signer role this recipient fills (for example client). Requires templateId. See Sending with signer roles
metadata	Object	No	Optional metadata for UI customization (color, lightColor)

Metadata Object (Optional)

The metadata object allows you to customize the recipient's UI appearance:

Property	Type	Description	Example
color	String	Primary color for recipient in HSL format	"hsl(200, 75%, 50%)"
lightColor	String	Light background color for recipient in HSL format	"hsl(200, 75%, 93%)"

Example Recipients Array

[
  {
    "name": "John Smith",
    "email": "john.smith@company.com",
    "signingOrder": 1
  },
  {
    "name": "Jane Doe",
    "email": "jane.doe@partner.com",
    "signingOrder": 2
  }
]

With Optional Metadata

[
  {
    "name": "John Smith",
    "email": "john.smith@company.com",
    "signingOrder": 1,
    "metadata": {
      "color": "hsl(200, 75%, 50%)",
      "lightColor": "hsl(200, 75%, 93%)"
    }
  }
]

Field Types Reference

Complete Field Type List

Type	Description	Auto-filled	Use Case
signature	Electronic signature field	No	Legal signatures, agreements
initial	Initial field	No	Document initials, paragraph acknowledgments
date	Date picker field	No	Signing date, agreement date
full_name	Full name field	Yes	Automatically fills signer's complete name
first_name	First name field	Yes	Automatically fills signer's first name
last_name	Last name field	Yes	Automatically fills signer's last name
title	Title/job title field	No	Professional title or position
company	Company name field	No	Organization or company name
email	Email address field	Yes	Signer's email address
text	Generic text input field	No	Custom text, notes, or any other text input
checkbox	Checkbox field	No	Acknowledgments, consent, agreements

Field Configuration Properties

Common Properties (All Field Types)

Property	Type	Required	Description
recipientEmail	String	Yes	Email address of recipient (matches email in recipients array)
type	String	Yes	Field type (see table above)
required	Boolean	No	Whether the signer must fill the field (default: true). Send false to let the signer leave it blank and still finish. Must be a JSON boolean, not the string "false"; null is treated as not set (required). Cannot be false on signature or initial fields. See Optional Fields
defaultValue	String	No	Pre-filled value for the field (max 600 characters). This is a real value that is submitted with the signature, not placeholder hint text. Stored per field, so two fields of the same type for one recipient can start with different values. Not allowed on signature or initial fields. A checkbox takes "true" or "false"; a date takes a fixed date in MM/DD/YYYY (omit it to use the signing date)
isReadonly	Boolean	No	Makes field non-editable (for prefilled values)
backgroundColor	String	No	Custom background color (hex or rgba)
metadata	Object	No	Optional field metadata. Carries fieldKey (on a controlling checkbox) and/or a conditional rule (on a dependent field). See Conditional (IF/THEN) Fields. Other keys are kept with the field as sent. The TurboDocx app adds useOwnDefaultValue: true to a name, email, title or company field that keeps its own defaultValue instead of following its recipient's value for that field type. It is an editor hint only: every field is signed with its own defaultValue either way.

Template-based Properties

Property	Type	Required	Description
template.anchor	String	Yes	Text anchor to find in document (e.g., {Signature1})
template.placement	String	Yes	How to place field: "replace", "before", "after"
template.size	Object	Yes	Field dimensions: { width: number, height: number }
template.offset	Object	No	Position offset: { x: number, y: number } (default: {x:0, y:0})
template.caseSensitive	Boolean	No	Whether anchor search is case-sensitive (default: true)
template.useRegex	Boolean	No	Whether to treat anchor as regex pattern (default: false)
template.alignment	String	No	Where the signer's entry sits: "left", "center" or "right". See Field Alignment

Coordinate-based Properties

Property	Type	Required	Description
page	Number	Yes	Page number (starts at 1)
x	Number	Yes	Horizontal position from left edge (pixels)
y	Number	Yes	Vertical position from top edge (pixels)
width	Number	Yes	Field width in pixels
height	Number	Yes	Field height in pixels
pageWidth	Number	No	Total page width in pixels (optional, for responsive positioning)
pageHeight	Number	No	Total page height in pixels (optional, for responsive positioning)
alignment	String	No	Where the signer's entry sits: "left", "center" or "right". See Field Alignment

Optional Fields

Every field is required by default: the signer cannot finish until it is filled. Set required: false on a field to make it optional. The signer can then leave it blank and still complete the document, and a blank optional field stays empty on the signed PDF.

const fields = JSON.stringify([
  {
    recipientEmail: "john.smith@company.com",
    type: "signature",
    template: { anchor: "{Signature1}", placement: "replace", size: { width: 200, height: 80 } },
  },
  // Optional: the signer may leave this blank
  {
    recipientEmail: "john.smith@company.com",
    type: "text",
    template: { anchor: "{Notes}", placement: "replace", size: { width: 300, height: 30 } },
    required: false,
  },
]);
formData.append("fields", fields);

Rules:

• Signature and initial fields are always required. Sending required: false on a signature or initial field is rejected with 400 OptionalNotSupported.
• required must be a JSON boolean. Any other value, including the string "false", is rejected with 400 InvalidFieldRequired. Omitting required, or sending null, is the same as true.
• Each recipient needs at least one required, editable field. A field counts when it is not isReadonly and its required is not false. A signature field always counts. A recipient whose fields are all optional or read-only is rejected with 400 NoEditableFieldsForRecipient.
• Date and checkbox fields are always filled on the signing page, so making them optional does not change what the signer sees. It does change one check: an optional date or checkbox does not count as the recipient's required field, so a recipient whose only other fields are optional is still rejected with 400 NoEditableFieldsForRecipient.
• defaultValue is a real value, not hint text. If you put instructions such as "Explain any changes here" in defaultValue, that text is submitted and lands on the signed PDF unless the signer clears it. Leave defaultValue empty on an optional field you want to stay blank.
• isReadonly and required: false can be combined. A read-only field is pre-filled and the signer can't change it, so it never holds up signing, whether it is required or not. A field that a conditional rule still hides or locks never holds up signing either.

On the signing page, an empty optional field keeps its normal label (for example "Text") and shows a small Optional tag on its top-right corner. The "N of M required" progress counter leaves optional fields out. A locked field never shows the tag: that covers a read-only field and a field that a conditional unlock rule still holds locked, and the tag appears once the rule unlocks it. A locked field shows its lock icon instead when your organization draws locked fields as grey boxes (see Locked Fields Rendering). If the signer fills in an optional field and changes their mind, they can open it and click Clear field.

required works the same way on prepare-for-signing, prepare-for-review, and in each documents[].fields array of the Bulk API.

Behavior change for existing integrations

Earlier, the single-step endpoints accepted required but ignored it, so every field was treated as required. required: false is now honored. If your integration already sends required: false, those fields become optional for the signer. Requests that send required: false on a signature or initial field, send a non-boolean required, or leave a recipient with no required editable field now return 400 (OptionalNotSupported, InvalidFieldRequired, or NoEditableFieldsForRecipient).

Conditional (IF/THEN) Fields

Any field can carry an optional metadata object. It is used to build conditional (IF/THEN) relationships between fields: a controlling checkbox decides whether one or more dependent fields are shown or unlocked. This works with both the prepare-for-signing and prepare-for-review single-step routes (and with the Bulk API, which uses the same field format).

The relationship has two halves:

1. The controlling checkbox gets a stable identifier via metadata.fieldKey. It must be a field of type: "checkbox".
2. Each dependent field points back at that checkbox with a metadata.conditional rule whose controllingFieldKey equals the checkbox's fieldKey.

metadata Object

Property	Type	Required	Description
fieldKey	String	No	Stable identifier for a controlling checkbox. Referenced by dependent fields' controllingFieldKey. Set this on the checkbox (type: "checkbox").
conditional	Object	No	Rule placed on a dependent field that makes its visibility/editability depend on a controlling checkbox. See below.

metadata.conditional Object

Property	Type	Required	Description
controllingFieldKey	String	Yes	The metadata.fieldKey of the controlling checkbox this field depends on. Must be non-empty.
operator	String	Yes	Condition to evaluate against the checkbox: "is_checked" or "is_not_checked".
action	String	Yes	What happens to this field when the condition is met: "show" or "unlock".

show vs. unlock

The action controls the dependent field's starting state and what the condition changes:

• show — the dependent field is hidden until the condition is met. When the checkbox matches the operator, the field appears.
• unlock — the dependent field is visible but read-only until the condition is met. When the checkbox matches the operator, the field becomes editable.

Worked Example

A recipient checks "Request changes" and a text box appears asking them to explain. The checkbox is the controller (fieldKey: "request_changes"); the text field shows only when the box is checked.

const fields = JSON.stringify([
  // The recipient's signature. Every recipient needs at least one required field.
  {
    recipientEmail: "john.smith@company.com",
    type: "signature",
    page: 1,
    x: 100,
    y: 600,
    width: 200,
    height: 80,
  },
  // Controlling checkbox — gets a stable fieldKey
  {
    recipientEmail: "john.smith@company.com",
    type: "checkbox",
    page: 1,
    x: 100,
    y: 400,
    width: 20,
    height: 20,
    required: false,
    metadata: {
      fieldKey: "request_changes",
    },
  },
  // Dependent text field — hidden until the checkbox above is checked
  {
    recipientEmail: "john.smith@company.com",
    type: "text",
    page: 1,
    x: 130,
    y: 400,
    width: 300,
    height: 60,
    required: false,
    defaultValue: "",
    metadata: {
      conditional: {
        controllingFieldKey: "request_changes",
        operator: "is_checked",
        action: "show",
      },
    },
  },
]);
formData.append("fields", fields);

To instead keep the field visible but locked until the box is checked, change the dependent field's action to "unlock". To reveal a field when a box is cleared (for example, an "I do not consent — explain why" note), use operator: "is_not_checked".

Validation and Fail-Open Behavior

The API validates the shape of every conditional rule. A malformed rule is rejected with HTTP 400 and the type InvalidConditionalRule. A rule is malformed when:

• operator is anything other than "is_checked" or "is_not_checked", or
• action is anything other than "show" or "unlock", or
• controllingFieldKey is missing or empty.

{
  "message": "Field 2: metadata.conditional.operator must be one of: is_checked, is_not_checked",
  "type": "InvalidConditionalRule"
}

A well-formed rule whose controllingFieldKey does not match any checkbox's fieldKey in the same request does not error — it fails open. The dependent field stays visible and editable as if it had no rule, so a typo in controllingFieldKey silently disables the condition rather than blocking the send. Double-check that the controllingFieldKey on each dependent field exactly matches the fieldKey of an existing checkbox.

Field Type Special Behaviors

signature & initial

• Draws a signature pad for user input
• Can be text-based or drawn
• Cryptographically signed and hashed for legal validity
• Cannot carry a defaultValue — sending one is rejected
• Always required: required: false is rejected with 400 OptionalNotSupported

date

• Shows date picker interface
• Format: MM/DD/YYYY (US) or DD/MM/YYYY (configurable)
• Fills automatically with the date the recipient signs
• To pin a specific date instead, set defaultValue to that date in MM/DD/YYYY format (e.g. "12/31/2026"). Omit defaultValue (or send "") to keep the signing-date behavior
• defaultValue must be a real calendar date in MM/DD/YYYY — a non-existent date such as "02/31/2026" (or any malformed value) is rejected with 400 InvalidDateValue. There is no "today" keyword
• A date field cannot be isReadonly — a pinned date still shows to the signer, it is not locked
• Always filled on the signing page, so required: false does not change what the signer sees, but an optional date does not count as the recipient's required field

full_name, first_name, last_name, email

• Auto-populated from recipient profile
• Can be overridden by recipient if needed
• Useful for legal compliance and form filling

text

• Single-line text input by default
• Supports defaultValue for prefilled content
• Set required: false to let the signer leave it blank (see Optional Fields)
• Use for titles, company names, custom fields

checkbox

• Boolean true/false value
• Useful for acknowledgments and consent
• Can have label text next to checkbox
• Always has a value (checked or unchecked) when the signer finishes, so required: false does not change what the signer sees, but an optional checkbox does not count as the recipient's required field

Field Positioning Methods

TurboSign supports two methods for positioning signature fields in your documents.

Method 1: Template-based Positioning (Recommended)

Uses text anchors in your PDF as placeholders. TurboSign searches for these anchors and places fields accordingly.

Advantages

✅ Easy to update field positions (just edit the PDF) ✅ No need to measure exact coordinates ✅ Works across different page sizes ✅ More maintainable for non-technical users ✅ Handles document variations gracefully

How it Works

1. Add anchor text to your PDF: Place text like {Signature1}, {Date1}, {Initial1} where you want fields
2. Configure fields with anchor references: Tell TurboSign what to search for
3. TurboSign finds and replaces: Anchors are found and replaced with interactive fields

Anchor Configuration Example

{
  "recipientEmail": "john.smith@company.com",
  "type": "signature",
  "template": {
    "anchor": "{Signature1}",
    "placement": "replace",
    "size": { "width": 200, "height": 80 },
    "offset": { "x": 0, "y": 0 },
    "caseSensitive": true,
    "useRegex": false
  },
  "required": true
}

Placement Options

• replace: Removes the anchor text and places the field in its position
• before: Places field before the anchor text (anchor remains visible)
• after: Places field after the anchor text (anchor remains visible)

Field Alignment

Use alignment to choose where the signer's entry (a typed or drawn signature, initials, a date, or any text value) sits inside its field: "left", "center" or "right".

• Anchor fields: set it on the template as template.alignment. With "placement": "replace", it also pins the field to that side of the anchor text: "left" starts the field where the anchor starts, "right" ends it where the anchor ends.
• Coordinate fields: set it at the top level of the field as alignment.
• Leave it out (or send null) to keep the standard placement. Existing integrations don't change.
• Any other value is rejected with a 400 error: alignment must be one of: left, center, right.
• Checkbox fields ignore it.

{
  "recipientEmail": "master@shipping.com",
  "type": "signature",
  "template": {
    "anchor": "{MasterSignature}",
    "placement": "replace",
    "size": { "width": 180, "height": 40 },
    "alignment": "left"
  }
}

The signing page shows the entry with the same alignment, and the signed PDF matches it.

Offset Usage

Offset allows fine-tuning field position relative to the anchor:

• x: Positive moves right, negative moves left (pixels)
• y: Positive moves down, negative moves up (pixels)

{
  "anchor": "{Signature1}",
  "placement": "replace",
  "size": { "width": 200, "height": 80 },
  "offset": { "x": 10, "y": -5 } // 10px right, 5px up from anchor
}

Method 2: Coordinate-based Positioning

Uses exact pixel coordinates to position fields on specific pages. Best for precise control or when anchors aren't feasible.

Advantages

✅ Pixel-perfect precision ✅ Works with PDFs that can't be edited ✅ Programmatically generated positions ✅ Useful for form-filling scenarios ✅ Consistent placement across documents

How it Works

1. Measure exact x,y coordinates in your PDF (using PDF editor or viewer)
2. Provide page number, coordinates, and dimensions
3. TurboSign places fields at exact positions

Coordinate Configuration Example

{
  "recipientEmail": "john.smith@company.com",
  "type": "signature",
  "page": 1,
  "x": 100,
  "y": 200,
  "width": 200,
  "height": 80,
  "pageWidth": 612,
  "pageHeight": 792,
  "required": true
}

Coordinate System Reference

• Origin (0,0): Top-left corner of the page
• X-axis: Increases from left to right
• Y-axis: Increases from top to bottom
• Standard US Letter: 612 x 792 pixels (8.5" x 11" at 72 DPI)
• Standard A4: 595 x 842 pixels (210mm x 297mm at 72 DPI)

Coordinate Validation

Fields must stay within page boundaries:

• x ≥ 0
• y ≥ 0
• x + width ≤ pageWidth
• y + height ≤ pageHeight

Measuring Coordinates

Adobe Acrobat Pro:

1. View → Show/Hide → Rulers & Grids → Rulers
2. Hover over location to see coordinates

Browser Developer Tools:

1. Open PDF in browser
2. Right-click → Inspect
3. Use element inspector to measure positions

PDF Editing Software:

• Use built-in coordinate display
• Draw rectangles to measure dimensions

Quick Coordinate Example

Position a signature field at bottom-right of a US Letter page:

{
  "recipientEmail": "john@example.com",
  "type": "signature",
  "page": 1,
  "x": 362, // 612 - 250 = 362 (right aligned with 50px margin)
  "y": 662, // 792 - 130 = 662 (bottom aligned with 50px margin)
  "width": 200,
  "height": 80,
  "pageWidth": 612,
  "pageHeight": 792
}

Best Practices

Workflow Selection

When You Need Field Verification:

• ✅ Use prepare-for-review to get preview URLs
• ✅ Verify field placement in browser before sending
• ✅ Manually trigger sending after review
• ✅ Useful for new document templates or complex field layouts

When Field Placement Is Verified:

• ✅ Use prepare-for-signing to send immediately
• ✅ Implement webhook handlers for completion notifications
• ✅ Use proper error handling and retry logic
• ✅ Monitor API rate limits
• ✅ Log all document IDs for tracking

General Tips:

• ✅ Use deliverableId or templateId to avoid repeated uploads
• ✅ Test with your own email addresses first
• ✅ Both endpoints are production-ready

Security

• Never expose API tokens: Store tokens securely in environment variables or secrets management
• Use HTTPS only: All API calls must use HTTPS in production (API enforces this)
• Validate inputs: Always validate recipient emails and document names before submission
• Implement rate limiting: Respect API rate limits to avoid throttling
• Rotate tokens regularly: Generate new API tokens periodically
• Use webhook signatures: Verify webhook payloads using HMAC signatures
• Sanitize user inputs: Validate and sanitize all user-provided data

Error Handling

• Check HTTP status codes: Always verify response status before processing
• Handle timeouts: Implement retry logic with exponential backoff for network failures
• Log API responses: Keep detailed logs for debugging and monitoring
• Validate responses: Check response structure before accessing data
• Graceful degradation: Have fallback behavior for API failures
• User-friendly errors: Display helpful error messages to end users

Performance

File Upload Optimization:

• Compress PDFs when possible (aim for <5MB)
• Use fileLink for files already in cloud storage (S3, GCS, etc.)
• Use deliverableId/templateId to reference existing documents
• Avoid uploading the same document multiple times

API Efficiency:

• Single-step endpoints reduce API calls from 3 to 1 (3x faster)
• Batch multiple documents in parallel requests when possible
• Use connection pooling for multiple requests
• Implement exponential backoff for retries
• Cache responses when appropriate

Network Optimization:

• Use CDN for document hosting when using fileLink
• Enable gzip compression for API requests
• Minimize payload sizes by only including required fields

Document Preparation

Text Anchors (Template-based):

• Use consistent anchor naming: {FieldType}{Number} (e.g., {Signature1}, {Date1})
• Place anchors exactly where you want fields
• Use unique anchors (avoid duplicates)
• Test anchor placement with prepare-for-review first
• Document your anchor naming convention

Coordinate-based:

• Verify coordinates work across different PDF viewers
• Account for page margins and headers/footers
• Use standard page sizes when possible
• Test on actual page dimensions (don't assume)
• Validate boundaries before submission

Document Validation:

• Ensure PDFs are not password-protected or corrupted
• Verify all pages are readable
• Test with actual documents before production
• Keep backup copies of source documents

JSON String Formatting

⚠️ Critical: Recipients and fields must be valid JSON strings when added to form-data.

Correct:

const recipients = JSON.stringify([
  { name: "John", email: "john@example.com", signingOrder: 1 },
]);
formData.append("recipients", recipients);

Incorrect:

// Don't send object/array directly!
formData.append("recipients", recipientsArray); // ❌ Wrong
formData.append("recipients", "[{...}]"); // ❌ Wrong (string literal, not stringified)

Python Example:

import json
recipients = json.dumps([
    {"name": "John", "email": "john@example.com", "signingOrder": 1}
])
form_data['recipients'] = recipients

C# Example:

using System.Text.Json;
var recipients = JsonSerializer.Serialize(new[] {
    new { name = "John", email = "john@example.com", signingOrder = 1 }
});
formData.Add(new StringContent(recipients), "recipients");

Error Handling & Troubleshooting

Common HTTP Status Codes

Status Code	Description	Solution
200	Success	Request completed successfully
400	Bad Request	Check request body format and required fields
401	Unauthorized	Verify API token and headers
403	Forbidden	Check organization ID and permissions
404	Not Found	Verify endpoint URLs are correct
422	Unprocessable Entity	Validate field values and constraints
429	Too Many Requests	Implement rate limiting and retry logic
500	Internal Server Error	Contact support if persistent

Error Codes for Sending and Updating Recipients

POST /turbosign/single/prepare-for-review, POST /turbosign/single/prepare-for-signing and PATCH /turbosign/documents/{id}/update-with-recipients return signature errors with a specific HTTP status and a machine-readable code. The body includes error (human-readable text) and code (the machine-readable value). It also repeats them as message and type, and may include a data object with details, so read the fields you need and ignore the rest:

{
  "message": "This organization does not allow changing the identity-verification method. Omit otpChannel or set it to 'email'.",
  "type": "OtpOverrideNotAllowed",
  "error": "This organization does not allow changing the identity-verification method. Omit otpChannel or set it to 'email'.",
  "code": "OtpOverrideNotAllowed"
}

Status	code	Meaning
400	Any code not listed below, for example OtpPhoneRequired, OtpPhoneInvalid, IdentityConfigInvalid, DuplicateExternalId	The request is invalid. Fix the input and retry.
402	OtpNotEntitled, SmsOtpLimitExceeded	The plan does not include this verification, or the SMS allowance is used up.
403	ExternalIdvNotAllowed, IdentityOverrideNotAllowed, OtpOverrideNotAllowed, EmbeddedSigningNotEnabled, SmsOtpNotEnabled	The organization has not turned on the feature or mode the request uses, or has locked the passcode method.
404	DocumentNotFound, RecipientNotFound	The document or recipient does not exist, was deleted, or belongs to another organization. On update-with-recipients, a document ID that does not exist returns 404 with only { "error": "Document not found" }.
409	DocumentNotSignable, RecipientAlreadySigned, RecipientNotInTurn, SmsProviderNotConfigured, RecipientRequiresSingleUseUrl	The document or recipient is not in a state that allows the request, or the organization has no SMS provider saved.
410	SigningUrlNotRedeemable	A single-use signing URL was already used or has expired.

None of these signature errors return a 5xx status. A 500 from these endpoints means an unexpected server problem, not a problem with your request.

Changed in v1.132.0

DocumentNotFound and RecipientNotFound returned 400 from these endpoints before v1.132.0. Since v1.132.0 they return 404. If your integration checks for 400 to detect a missing document or recipient, check for 404 or read code instead.

For what each identity and passcode code means and how to fix it, see Embedded signing errors.

Common Issues

JSON String Formatting Errors

Symptoms: 400 Bad Request with message "Invalid JSON in recipients/fields"

Solutions:

• ✅ Verify JSON.stringify() or equivalent is used for recipients, fields, ccEmails
• ✅ Check JSON is valid using JSONLint or similar validator
• ✅ Ensure proper escaping of quotes in JSON strings
• ✅ Test with minimal example first (1 recipient, 1 field)

Example Error Response:

{
  "error": "Invalid JSON string in recipients field",
  "code": "JSONParseError",
  "details": "Unexpected token at position 45"
}

Debug Steps:

1. Log the JSON string before sending
2. Validate JSON with online validator
3. Check for special characters or unescaped quotes
4. Test with hardcoded valid JSON first

File Source Errors

Symptoms: 400 Bad Request with message about file source

Solutions:

• ✅ Provide exactly ONE of: file, deliverableId, templateId, fileId, fileLink
• ✅ Verify UUIDs are valid format (8-4-4-4-12 characters)
• ✅ Check file upload isn't corrupted or empty
• ✅ Ensure fileLink is accessible (not behind auth)

Example Error Response:

{
  "error": "Must provide exactly one file source",
  "code": "InvalidFileSource"
}

Recipients/Fields Mismatch

Symptoms: 400 Bad Request about missing recipient or email mismatch

Solutions:

• ✅ Verify recipientEmail in fields matches email in recipients array exactly
• ✅ Check for typos in email addresses
• ✅ Ensure all fields reference valid recipients
• ✅ Email matching is case-sensitive

Example:

// Recipients array
[{ email: "john.smith@company.com", ... }]

// Fields array - must match exactly
[{ recipientEmail: "john.smith@company.com", ... }]  // ✅ Correct
[{ recipientEmail: "John.Smith@company.com", ... }]  // ❌ Wrong (case mismatch)

Optional Field Errors

Symptoms: 400 Bad Request with code OptionalNotSupported, InvalidFieldRequired, or NoEditableFieldsForRecipient

Code	Cause	Fix
OptionalNotSupported	required: false on a signature or initial field	Remove required from that field, or set it to true
InvalidFieldRequired	required is not a boolean or null (for example the string "false")	Send a JSON boolean: true or false
NoEditableFieldsForRecipient	A recipient has only optional or read-only fields	Give that recipient at least one required, editable field, such as a signature

Example Error Response:

{
  "error": "Field 1: SIGNATURE and INITIAL field types cannot be optional. Field type \"signature\" must be completed by the signer.",
  "code": "OptionalNotSupported"
}

See Optional Fields for the full rules.

Authentication Failures

Symptoms: 401 Unauthorized responses

Solutions:

• ✅ Verify API token is correct and not expired
• ✅ Check that x-rapiddocx-org-id header matches your organization
• ✅ Ensure Bearer token format: Bearer YOUR_TOKEN (with space)
• ✅ Confirm token has necessary permissions

Example Correct Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-rapiddocx-org-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Document Upload Failures

Symptoms: Upload returns error or times out

Solutions:

• ✅ Verify PDF file is not corrupted or password-protected
• ✅ Check file size is under maximum limit (typically 10MB)
• ✅ Ensure file is actually a PDF (check MIME type)
• ✅ Verify network connection and try again
• ✅ For fileLink, ensure URL is accessible

Field Positioning Problems

Symptoms: Signature fields appear in wrong locations or not at all

Template-based Solutions:

• ✅ Verify anchor text exists in the PDF document
• ✅ Check anchor text matches exactly (case-sensitive by default)
• ✅ Test with caseSensitive: false if having matching issues
• ✅ Try different placement options (replace, before, after)
• ✅ Use prepare-for-review to visually verify placement

Coordinate-based Solutions:

• ✅ Verify page dimensions match your PDF's actual size
• ✅ Check that x,y coordinates are within page boundaries
• ✅ Ensure coordinates account for any PDF margins or headers
• ✅ Test with different page numbers if multi-page document
• ✅ Validate that x + width ≤ pageWidth and y + height ≤ pageHeight

Webhook Integration Issues

Symptoms: Not receiving completion notifications

Solutions:

• ✅ Verify webhook URLs are accessible and return 200 OK
• ✅ Check webhook configuration in organization settings
• ✅ Review webhook delivery history for error details
• ✅ Test webhook endpoints with external tools (webhook.site, ngrok)
• ✅ Implement HMAC signature verification

Debugging Tips

1. Test with prepare-for-review first: Visual confirmation before sending emails
2. Use preview URLs: Verify field placement and document appearance
3. Check response documentId: Save this for tracking and debugging
4. Enable request logging: Log all requests and responses with timestamps
5. Test with minimal payloads: Start simple (1 recipient, 1 field), add complexity incrementally
6. Validate JSON before sending: Use JSON validators to check format
7. Use Postman/Insomnia: Test manually before writing code
8. Check API status page: Verify TurboDocx services are operational
9. Review error messages carefully: Error responses include specific details
10. Monitor rate limits: Track API usage to avoid throttling

Example Debug Request

# Test with curl to isolate issues
curl -X POST https://api.turbodocx.com/turbosign/single/prepare-for-review \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-rapiddocx-org-id: YOUR_ORG_ID" \
  -F "file=@document.pdf" \
  -F "documentName=Test Document" \
  -F "senderEmail=you@yourcompany.com" \
  -F 'recipients=[{"name":"Test User","email":"test@example.com","signingOrder":1}]' \
  -F 'fields=[{"recipientEmail":"test@example.com","type":"signature","page":1,"x":100,"y":200,"width":200,"height":80,"pageWidth":612,"pageHeight":792}]' \
  -v

Next Steps

Webhooks - The Next Logical Step

Now that you've integrated the single-step signing flow, the next step is setting up webhooks to receive real-time notifications when documents are signed. This eliminates the need for polling and provides instant updates about document status changes.

📖 Learn how to configure Webhooks →

Related Documentation

• TurboSign Setup Guide
• Webhook Configuration
• API Authentication

Support

Need help with your integration?

• Discord Community: Join our Discord server for real-time support and discussions
• Documentation: https://docs.turbodocx.com

---

Ready to get started? Follow the guide above to integrate TurboSign single-step API into your application and start collecting electronic signatures programmatically with a single API call!