From bff878b39b467cccf4bcf0a571ca6b6fbd0cdf2b Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Tue, 20 Oct 2026 07:03:38 -0400 Subject: [PATCH 1/5] docs: v1.133.0 release gaps (Wrike ID filename, failure email note, empty variables, verify email, SignatureOnlyTemplate) --- docs/API/Deliverable-API.md | 6 +++++- .../Wrike/document-generation-automation.md | 13 +++++++++++++ docs/Pipelines/Pipeline-Notifications.md | 16 +++++++++++++++- docs/SDKs/deliverable.md | 2 ++ docs/TurboSign/Signature-Setups-on-Templates.md | 7 +++++-- docs/Welcome-to-TurboDocx.md | 12 ++++++++++++ 6 files changed, 52 insertions(+), 4 deletions(-) diff --git a/docs/API/Deliverable-API.md b/docs/API/Deliverable-API.md index fa00c265..46fc3818 100644 --- a/docs/API/Deliverable-API.md +++ b/docs/API/Deliverable-API.md @@ -268,10 +268,14 @@ This endpoint requires one of these roles: **administrator**, **contributor**, o | ------------- | ------ | -------- | ------------------------------------------ | | `name` | String | **Yes** | Deliverable name (3–255 characters) | | `templateId` | String | **Yes** | Template ID to generate from. A PDF (signature-only) template returns `400 SignatureOnlyTemplate` | -| `variables` | Array | **Yes** | Array of variable objects for substitution | +| `variables` | Array | **Yes** | Array of variable objects for substitution. May be empty (`[]`) | | `description` | String | No | Description (up to 65,535 characters) | | `tags` | Array | No | Array of tag strings to associate | +:::note Empty or partial `variables` +`variables` must be sent, but it can be an empty array. `"variables": []` generates the document and returns `200`. Any placeholder you don't supply a value for renders blank in the document. +::: + ### Variable Object Structure Each variable in the `variables` array represents a placeholder in the template to be substituted: diff --git a/docs/Integrations/Wrike/document-generation-automation.md b/docs/Integrations/Wrike/document-generation-automation.md index 52134645..eb84ef7f 100644 --- a/docs/Integrations/Wrike/document-generation-automation.md +++ b/docs/Integrations/Wrike/document-generation-automation.md @@ -7,6 +7,8 @@ keywords: - wrike generate document - wrike template automation - wrike automated documents + - wrike output filename + - wrike id in file name --- # How to Setup Document Generation Automation @@ -47,6 +49,17 @@ Click the **Select Template** button at the bottom-right corner of the dialog to ![Confirm Selected Template](/img/wrike-integration/Step14-ConfirmTemplate.png) +### Optional: Name the Generated File + +On the same step, the **Output Filename** section builds the name of the generated file. Leave it empty to name the file after the template. + +- Click **Insert Field** to add a value from the triggering Wrike item: **Task Title**, **Folder Name** (the parent folder or project), **Status**, **Assignee** (the first assigned user), **Date** (today, in your organization's date format), **Wrike ID**, or one of your Wrike custom fields. +- Click **Add Separator** or **Add Text** to put your own text between the fields. Drag the chips to reorder them. + +**Wrike ID** is the number in the item's Wrike link. For a task at `https://www.wrike.com/open.htm?id=1234567890`, it is `1234567890`. On a task trigger it is the task's own number, and on a folder or project trigger it is that folder's or project's number. If the link has no number, TurboDocx uses the item's Wrike API ID instead. + +For example, **Wrike ID**, the text ` - ` and **Task Title** name the file `1234567890 - Acme Q2 Proposal`. + ### Step 6: Proceed to Final Configuration Click the **Next** button to advance to the final configuration step. diff --git a/docs/Pipelines/Pipeline-Notifications.md b/docs/Pipelines/Pipeline-Notifications.md index 14f3c818..a58d11f3 100644 --- a/docs/Pipelines/Pipeline-Notifications.md +++ b/docs/Pipelines/Pipeline-Notifications.md @@ -1,7 +1,7 @@ --- title: Pipeline Notifications sidebar_position: 3 -description: Choose who is notified when a pipeline run succeeds or fails, override recipients per routing store, and customize the completion email and ZIP. +description: Choose who is notified when a pipeline run succeeds or fails, set per-store recipients, customize the completion email, and add a note to failure emails. keywords: - pipeline notifications - signed and delivered email @@ -13,6 +13,7 @@ keywords: - attach signed document zip - routing store notifications - pipeline email recipients + - failure email note --- # Pipeline Notifications @@ -72,6 +73,19 @@ If the ZIP attachment is too large to email, the completion email is still sent
+## Add a Note to Failure Emails + +You can add a short note of your own to every failure email the pipeline sends, for example what the recipient should do next. Under the **Failed** list, click **Add a note to the email** and type it in **Note for failure emails**. + +- The note appears under **Note from your administrator**, above the error details, in every failure email for this pipeline. +- It is sent as plain text, as typed. Line breaks are kept. Insert-field chips are not available here. +- The limit is 1,000 characters. A longer paste is cut to the limit and the wizard tells you. +- Clear the box to stop adding a note. + +Once a note is saved, the button reads **Edit failure note**. + +
+ ## Per-Store Notifications If your pipeline uses routing rules on the **Extract & Route** step, each routing rule is a "store" (for example, one region or one business unit). You can give any store its own recipients instead of the pipeline defaults. diff --git a/docs/SDKs/deliverable.md b/docs/SDKs/deliverable.md index e02acf62..66c64804 100644 --- a/docs/SDKs/deliverable.md +++ b/docs/SDKs/deliverable.md @@ -2142,6 +2142,8 @@ Files.write(Paths.get("report.pdf"), pdfData); +A `templateId` that points to a [PDF signature template](/docs/TurboDocx-Templating/API-Templates#pdf-signature-templates) can't generate a document. The API answers `400` with the code `SignatureOnlyTemplate` and the message `PDF templates can only be used to collect signatures, not to generate documents.`, which the SDK raises as its validation error (`ValidationError` or `ValidationException`). Send a PDF template for signature with [TurboSign](/docs/SDKs/turbosign) instead. + ### Handling Errors {#handling-errors} diff --git a/docs/TurboSign/Signature-Setups-on-Templates.md b/docs/TurboSign/Signature-Setups-on-Templates.md index 4200457c..5b7923be 100644 --- a/docs/TurboSign/Signature-Setups-on-Templates.md +++ b/docs/TurboSign/Signature-Setups-on-Templates.md @@ -214,6 +214,9 @@ field and scroll the preview to it. - **Change it:** on the template's page, click **Edit Setup**. The generate page opens on its **Signatures** (or **Prepare & Sign**) tab with the setup loaded. Make your changes, then click **⋮ → Save signature setup to template**. +- **Change only the email or reminders:** on the template's page, click **Edit** next to + **Email to signers** (document name for PDF templates, message and CC recipients) or next to + **Reminders & expiration**, make your changes and save. The signers and fields stay as they are. - **Remove it:** on the template's page, click **Delete Setup** and confirm, or click **⋮ → Delete signature setup from template** on the generate page. Documents you already sent aren't affected. New sends start with no signers or fields. @@ -222,8 +225,8 @@ field and scroll the preview to it. ![Signature setup view of a Word template with no saved setup, showing No signature setup yet and the Set Up On The Generate Page button highlighted](/img/signature_setups_on_templates/04_no_setup_yet.png) -**Edit Setup**, **Delete Setup** and **Set Up On The Generate Page** are shown to Administrators -and Contributors only. +**Edit Setup**, **Edit**, **Delete Setup** and **Set Up On The Generate Page** are shown to +Administrators and Contributors only. ## Save a setup from TurboSign diff --git a/docs/Welcome-to-TurboDocx.md b/docs/Welcome-to-TurboDocx.md index 53f58fbe..73513fb6 100644 --- a/docs/Welcome-to-TurboDocx.md +++ b/docs/Welcome-to-TurboDocx.md @@ -10,6 +10,7 @@ keywords: - getting started - digital signatures - document generation + - verify your email --- @@ -73,6 +74,17 @@ Every TurboDocx product is also a REST API. Official SDKs cover JavaScript/TypeS If a document, template, or integration isn't behaving as expected, check that specific product's page first, most end with their own troubleshooting section, for example [Template Troubleshooting](./TurboDocx-Templating/Template-Troubleshooting.md). If you can't find an answer there, contact TurboDocx support with the organization name and a description of what you tried. +### "Please verify your email" when you sign in {#please-verify-your-email} + +You may see a **Please verify your email** screen the first time you sign in a new way, for example with Google or your company's single sign-on, using the email address of an account you already have. TurboDocx only connects a new sign-in to an existing account once the email address is verified, so nobody can take over an account with an unverified address. + +To continue: + +1. Open the verification link in the email we sent you. If you can't find it, click **Resend verification email**, then check your inbox and spam folder. +2. Click **Sign in again** and sign in the same way as before. + +If you clicked resend a moment ago, the screen asks you to wait a minute before sending another email. + ## Frequently asked questions **Do I need to write code to use TurboDocx?** From f9a846a210f27fc71f45a89da09cdd37f396fad8 Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Tue, 20 Oct 2026 07:04:45 -0400 Subject: [PATCH 2/5] docs(turbosign): update a template's signature settings and delete its setup via the API --- docs/TurboSign/API-Signatures.md | 142 +++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/docs/TurboSign/API-Signatures.md b/docs/TurboSign/API-Signatures.md index 10e090e9..cebe0816 100644 --- a/docs/TurboSign/API-Signatures.md +++ b/docs/TurboSign/API-Signatures.md @@ -36,6 +36,8 @@ keywords: - resend signature - signer roles - template signature setup + - update signature setup settings + - delete signature setup --- import ScriptLoader from '@site/src/components/ScriptLoader'; @@ -1280,6 +1282,146 @@ User-Agent: TurboDocx API Client - 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 {#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](./Signature-Setups-on-Templates.md#change-or-remove-the-setup)). + +### Endpoint + +```http +PATCH https://api.turbodocx.com/turbosign/templates/{templateId}/signature-setup/settings +``` + +### Headers + +```http +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](#endpoint-1-prepare-for-review) 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`. + +```bash +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 + +```json +{ + "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 {#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 + +```http +DELETE https://api.turbodocx.com/turbosign/templates/{templateId}/save-signature-setup +``` + +### Headers + +```http +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 + +```json +{ + "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](#endpoint-9-update-template-signature-settings) instead. + ## Send a template set up in TurboDocx {#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. From e1831c659c86724295d6614ed27632343f62a1b9 Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Tue, 20 Oct 2026 07:09:08 -0400 Subject: [PATCH 3/5] docs: put the no-roles bullet back in the role send list; neutral wording for the verify-email screen --- docs/TurboSign/API-Signatures.md | 2 +- docs/Welcome-to-TurboDocx.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/TurboSign/API-Signatures.md b/docs/TurboSign/API-Signatures.md index cebe0816..06ce94eb 100644 --- a/docs/TurboSign/API-Signatures.md +++ b/docs/TurboSign/API-Signatures.md @@ -407,6 +407,7 @@ How a role send behaves: - **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](/docs/TurboSign/embedded-signing/reference#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 {#claiming-a-role-with-a-different-signer} @@ -423,7 +424,6 @@ What changes for the new signer: - **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`. -- **Without roles nothing changes.** `fields` is still required when no recipient names a role. #### Signer role errors diff --git a/docs/Welcome-to-TurboDocx.md b/docs/Welcome-to-TurboDocx.md index 73513fb6..551aa71d 100644 --- a/docs/Welcome-to-TurboDocx.md +++ b/docs/Welcome-to-TurboDocx.md @@ -76,7 +76,7 @@ If a document, template, or integration isn't behaving as expected, check that s ### "Please verify your email" when you sign in {#please-verify-your-email} -You may see a **Please verify your email** screen the first time you sign in a new way, for example with Google or your company's single sign-on, using the email address of an account you already have. TurboDocx only connects a new sign-in to an existing account once the email address is verified, so nobody can take over an account with an unverified address. +You may see a **Please verify your email** screen the first time you sign in with a new sign-in method that uses the same email address as an account you already have, before that address is verified. TurboDocx only connects a new sign-in to an existing account once the email address is verified, so nobody can take over an account with an unverified address. To continue: From 3ea3382065b0c7b3f66af537ae706dcdee078907 Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Tue, 20 Oct 2026 08:41:17 -0400 Subject: [PATCH 4/5] docs: keep the quickstart skill command and pipeline links in the markdown twins, drop a link to an unbuilt page --- docs/Pipelines/Pipeline-Notifications.md | 8 ++++---- docs/SDKs/deliverable.md | 2 ++ docs/TurboSign/API-Signatures.md | 2 ++ docs/Welcome-to-TurboDocx.md | 1 - 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/Pipelines/Pipeline-Notifications.md b/docs/Pipelines/Pipeline-Notifications.md index a58d11f3..dd813f39 100644 --- a/docs/Pipelines/Pipeline-Notifications.md +++ b/docs/Pipelines/Pipeline-Notifications.md @@ -28,7 +28,7 @@ Pipelines are an **Enterprise** feature. If you don't see the option to create o
-You set **default notifications** on the **Destination** step (labeled **Deliver** in the wizard's progress rail), and **per-store overrides** on the **Extract & Route** step. If you haven't built a pipeline yet, start with **[Creating an E-Signature Pipeline](./Creating-an-E-Signature-Pipeline)** and come back here to fine-tune the alerts. +You set **default notifications** on the **Destination** step (labeled **Deliver** in the wizard's progress rail), and **per-store overrides** on the **Extract & Route** step. If you haven't built a pipeline yet, start with **[Creating an E-Signature Pipeline](./Creating-an-E-Signature-Pipeline.md)** and come back here to fine-tune the alerts.
@@ -115,6 +115,6 @@ Per-store notifications are useful when different regions, branches, or departme ## What's Next? -- **[Creating an E-Signature Pipeline](./Creating-an-E-Signature-Pipeline)**: build the pipeline these notifications belong to. -- **[Field Extraction](./Field-Extraction)**: define the routing fields that create per-store rules. -- **[Cloud Connectors](./Cloud-Connectors)**: resolve signers from your own internal systems. +- **[Creating an E-Signature Pipeline](./Creating-an-E-Signature-Pipeline.md)**: build the pipeline these notifications belong to. +- **[Field Extraction](./Field-Extraction.md)**: define the routing fields that create per-store rules. +- **[Cloud Connectors](./Cloud-Connectors.md)**: resolve signers from your own internal systems. diff --git a/docs/SDKs/deliverable.md b/docs/SDKs/deliverable.md index 66c64804..ae988101 100644 --- a/docs/SDKs/deliverable.md +++ b/docs/SDKs/deliverable.md @@ -76,6 +76,8 @@ The official TurboDocx Deliverable SDK for Java applications. Generate documents ## Installation {#installation} +To have an AI coding agent scaffold the integration, install the TurboDocx Quickstart skill with `npx skills add TurboDocx/quickstart` and run `/turbodocx-sdk deliverable` in the agent. To install the SDK yourself: + diff --git a/docs/TurboSign/API-Signatures.md b/docs/TurboSign/API-Signatures.md index 06ce94eb..148cddca 100644 --- a/docs/TurboSign/API-Signatures.md +++ b/docs/TurboSign/API-Signatures.md @@ -135,6 +135,8 @@ 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 diff --git a/docs/Welcome-to-TurboDocx.md b/docs/Welcome-to-TurboDocx.md index 551aa71d..7893144f 100644 --- a/docs/Welcome-to-TurboDocx.md +++ b/docs/Welcome-to-TurboDocx.md @@ -35,7 +35,6 @@ TurboDocx Templating turns an existing Word or PowerPoint file into a reusable t - [How to Create a Template](./TurboDocx-Templating/How-to-Create-a-Template.md): turn an existing document into a reusable template. - [How to Create a Document Template](./TurboDocx-Templating/How-to-Create-a-Document-Template.md) and [How to Create a Presentation Template](./TurboDocx-Templating/How-to-Create-a-Presentation-Template.md): format-specific walkthroughs for Word and PowerPoint. - [How to Create a Deliverable](./TurboDocx-Templating/How-to-Create-a-Deliverable.md): generate a finished document from a template. -- [Advanced Templating](./Advanced-Configuration/Advanced-Templating.md): loops, conditionals, and expressions for complex templates. ## Get documents signed From 9d1805f3c4595ca71401f2b60881e5a4ce6731fc Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Mon, 5 Oct 2026 17:45:01 -0400 Subject: [PATCH 5/5] docs(turbosign): document error status codes for single-step and update-with-recipients Rebased onto develop: moved from the old space-named paths to API-Signatures.md and embedded-signing/reference.md, and noted that DocumentNotFound/RecipientNotFound moved from 400 to 404 in v1.132.0. --- docs/TurboSign/API-Signatures.md | 30 ++++++++++++++++++++ docs/TurboSign/embedded-signing/reference.md | 2 +- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/TurboSign/API-Signatures.md b/docs/TurboSign/API-Signatures.md index 148cddca..53372460 100644 --- a/docs/TurboSign/API-Signatures.md +++ b/docs/TurboSign/API-Signatures.md @@ -2160,6 +2160,36 @@ formData.Add(new StringContent(recipients), "recipients"); | `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 {#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: + +```json +{ + "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`, `NotSignersTurn`, `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. + +:::note 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](./embedded-signing/reference.md#errors). + ### Common Issues #### JSON String Formatting Errors diff --git a/docs/TurboSign/embedded-signing/reference.md b/docs/TurboSign/embedded-signing/reference.md index 73f45750..f7363de1 100644 --- a/docs/TurboSign/embedded-signing/reference.md +++ b/docs/TurboSign/embedded-signing/reference.md @@ -536,7 +536,7 @@ Identity and passcode errors from sending a document and from `createSigningUrl` | 410 | `SigningUrlNotRedeemable` | A single-use signing URL was already used or has expired. Request a new one. | | 423 | `locked` | The signer entered 20 wrong codes. See [Passcode attempts and lockout](#passcode-attempts-and-lockout). | -A missing document returns `404` with the older `{ "message", "type": "DocumentNotFound" }` body. The signer-facing passcode endpoints that the signing page calls use their own `{ "error", "code" }` body with lowercase codes, for example `locked` with HTTP `423`. +A missing document returns `404` with `DocumentNotFound`. When you send a document, that error uses the same four-field body as above; other endpoints may return only `message` and `type`. See [Error Codes for Sending and Updating Recipients](../API-Signatures.md#error-codes-for-sending-and-updating-recipients) for the full list for those endpoints. The signer-facing passcode endpoints that the signing page calls use their own `{ "error", "code" }` body with lowercase codes, for example `locked` with HTTP `423`. :::warning A blank iframe is not an API error When your origin is not under **Allowed embedding domains**, the API calls all succeed but the browser refuses to render the frame (a `frame-ancestors` error in the console). Add your origin in [Set up your organization](./set-up-your-organization.md#step-5-allow-the-origins-that-may-embed-the-signing-page).