{ "openapi": "3.1.0", "info": { "title": "Embed API", "description": "#### Authentication\n\nAll endpoints in this API require Bearer authentication using an API key. Include the API key obtained from the customer portal in the Authorization header of each request, formatted as follows:\n\n```\nAuthorization: Bearer \n```\n\n#### Base URLs\n\nLegal Engine endpoints (`/api/...`) are served from `https://api.builder.docue.com` and Sign Engine endpoints (`/sign/...`) from `https://api.embed.docue.com`. The same API key works for both.\n", "version": "1.0.0", "contact": { "email": "support@docue.com", "url": "https://docue.com" } }, "servers": [ { "url": "https://api.embed.docue.com", "description": "Production (Sign Engine)" } ], "security": [ { "APIKey": [] } ], "paths": { "/api/workspaces/current": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Get current workspace", "operationId": "getCurrentWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.Workspace.Data.WorkspaceData.WorkspaceData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "name": "Acme Inc." } } } } } } } }, "/api/templates": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "List templates", "description": "Fetch templates available for the authenticated workspace.\n\nUse `filter[query]` to search templates by title with a partial, case-insensitive match.\nExample: `GET /api/templates?filter[query]=employment`\n\nUse `filter[collection]` to only return templates that belong to a specific collection ID.\nExample: `GET /api/templates?filter[collection]=01965c7e-dc1e-7292-8199-8184041c1204`\n\nYou can combine both filters in one request.\nExample: `GET /api/templates?filter[query]=employment&filter[collection]=01965c7e-dc1e-7292-8199-8184041c1204`\n\nTo include template collections in each template item, request `include=collections`.\n", "operationId": "getTemplates", "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/PaginationPerPage" }, { "$ref": "#/components/parameters/PaginationPage" }, { "$ref": "#/components/parameters/TemplatesFilterQuery" }, { "$ref": "#/components/parameters/TemplatesFilterCollection" }, { "$ref": "#/components/parameters/TemplatesSort" }, { "$ref": "#/components/parameters/TemplatesSortLocale" }, { "$ref": "#/components/parameters/TemplatesInclude" } ], "responses": { "200": { "description": "Successful response with a list of templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App.Data.Template.TemplateData.TemplateData" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "data": [ { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "title": { "_type": "translatable", "en-GB": "Employment Agreement" }, "description": { "_type": "translatable", "en-GB": "Description" }, "short_description": { "_type": "translatable", "en-GB": "Short description" }, "default_document_name": { "_type": "translatable", "en-GB": "Employment Agreement" }, "collections": [ { "id": "01965c7e-dc1e-7292-8199-8184041c1204", "title": { "de": "Arbeitsrecht", "fi": "Työsuhde ja HR", "pl": "Zatrudnienie i HR", "sv": "Anställningsförhållande och HR", "_type": "translatable", "en-GB": "Employment and HR" }, "created_at": "2026-03-02T11:37:09Z", "updated_at": "2026-04-20T12:38:43Z" }, { "id": "0198553a-20cc-7344-bbf9-a75dde9152dd", "title": { "de": "Gründung", "fi": "Yrityksen perustaminen", "pl": "Zakładanie przedsiębiorstwa", "sv": "Starta ett företag", "_type": "translatable", "en-GB": "Starting a company" }, "created_at": "2026-03-02T11:37:10Z", "updated_at": "2026-04-20T12:38:37Z" } ], "created_at": "2025-03-22T14:30:00Z", "updated_at": "2025-03-22T14:30:00Z", "languages": [ { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "code": "en-GB" } ], "jurisdictions": [ { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "code": "FI" } ] } ], "meta": { "status": { "code": 200, "text": "OK" }, "pagination": { "items": 1, "total": 30, "has_pages": true, "is_first": true, "pointer": { "previous": null, "current": 1, "next": 2 } } } } } } } } } }, "/api/template-collections": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "List template collections", "description": "Fetch the available template collections.\n\nTo fetch templates that belong to a collection, refer to the `GET /api/templates` endpoint and use `filter[collection]`.\n", "operationId": "getTemplateCollections", "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/PaginationPerPage" }, { "$ref": "#/components/parameters/PaginationPage" }, { "$ref": "#/components/parameters/TemplateCollectionsFilterQuery" }, { "$ref": "#/components/parameters/TemplateCollectionsSort" }, { "$ref": "#/components/parameters/TemplatesSortLocale" } ], "responses": { "200": { "description": "Successful response with a list of template collections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateCollectionData" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "data": [ { "id": "01965c7e-dc1e-7292-8199-8184041c1204", "title": { "de": "Arbeitsrecht", "fi": "Työsuhde ja HR", "pl": "Zatrudnienie i HR", "sv": "Anställningsförhållande och HR", "_type": "translatable", "en-GB": "Employment and HR" }, "_data_type": "app.http.api.template_collection.data.template_collection_data" }, { "id": "0198553c-9fdc-7299-a901-64896be29f30", "title": { "de": "Finanzierung", "fi": "Rahoitus, tilinpäätös ja varojenjako", "pl": "Finanse przedsiębiorstw", "sv": "Finansiering, bokslut och betalningar", "_type": "translatable", "en-GB": "Corporate finance" }, "_data_type": "app.http.api.template_collection.data.template_collection_data" } ], "meta": { "status": { "code": 200, "text": "OK" }, "pagination": { "items": 2, "total": 12, "has_pages": true, "is_first": true, "pointer": { "previous": null, "current": 1, "next": 2 } } } } } } } } } }, "/api/templates/{template_id}": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Get a single template", "description": "Fetch one template by ID.\n\nUse `include=collections` to include the template's collection memberships. You can also include `languages` and `jurisdictions`.\n", "operationId": "getTemplateById", "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/TemplatesInclude" }, { "name": "template_id", "in": "path", "required": true, "description": "The UUID of the template to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully retrieved the template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/App.Data.Template.TemplateData.TemplateData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "title": { "_type": "translatable", "en-GB": "Employment Agreement" }, "description": { "_type": "translatable", "en-GB": "Description" }, "short_description": { "_type": "translatable", "en-GB": "Short description" }, "default_document_name": { "_type": "translatable", "en-GB": "Employment Agreement" }, "collections": [ { "id": "01965c7e-dc1e-7292-8199-8184041c1204", "title": { "de": "Arbeitsrecht", "fi": "Työsuhde ja HR", "pl": "Zatrudnienie i HR", "sv": "Anställningsförhållande och HR", "_type": "translatable", "en-GB": "Employment and HR" }, "created_at": "2026-03-02T11:37:09Z", "updated_at": "2026-04-20T12:38:43Z" }, { "id": "0198553a-20cc-7344-bbf9-a75dde9152dd", "title": { "de": "Gründung", "fi": "Yrityksen perustaminen", "pl": "Zakładanie przedsiębiorstwa", "sv": "Starta ett företag", "_type": "translatable", "en-GB": "Starting a company" }, "created_at": "2026-03-02T11:37:10Z", "updated_at": "2026-04-20T12:38:37Z" } ], "created_at": "2025-03-22T14:30:00Z", "updated_at": "2025-03-22T14:30:00Z", "languages": [ { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "code": "en-GB" } ], "jurisdictions": [ { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "code": "FI" } ] } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/api/browser/sessions": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Create a new browser session", "description": "To use our template browser for selecting the correct template, create a new browser session and redirect the end user to our app. Our app will then redirect the user back to your app to the URL defined in the handlers.\n\nBy creating a new browser session, you receive a redirect URL to send the end user. You also obtain a browser session ID, which allows you to retrieve the selected template, language, and the document title provided by the end user.\n\nThe redirect URL is a secure link to our hosted app. It contains a one-time authorization token to authenticate the end user securely. Our app exchanges the token for a session cookie, granting access to this specific browser session only.\n\nThe session expires after 15 minutes if the user has not been redirected to the URL.\n\n#### Handlers\n\nWhen creating a browser session, you must provide handler URLs.\n\n**Success handler**\nThe user is redirected to this URL after successfully selecting the template and other details. Please note that the user may be redirected to this URL multiple times if they navigate back to the session using the browser's history.\n\n**Cancel handler**\nThe user is redirected to this URL when they intentionally cancel the template selection by clicking the \"back button\" in the header. They can continue using the template browser if they navigate back to the session using the browser's history; therefore, this may be called multiple times.\n\n**Delete handler**\nThe user is redirected to this URL when the browser session expires or is deleted via the API. In many cases, it is acceptable to use the same endpoint as in the cancel handler. This may be called multiple times.\n\n**Error handler**\nThe user is redirected to this URL when something unexpected occurs.\n\n#### Handler url parameters\n\nThe handler URL is appended (existing query parameters will remain intact) with the following query parameters:\n| Parameter | Description |\n| --------------- | -------------------------------------------------------------- |\n| `session_id` | Template browser session ID |\n| `template_id` | ID of the selected template (only on success) |\n| `document_name` | Name the end-user choosed for the document (only on success) |\n| `languages[0]` | Primary language of the document (only on success) |\n| `languages[1]` | Secondary language of the document (only on success, optional) |\n\n\nFor example, if you have defined success handler:\n```json\n\"success_handler\": {\n \"endpoint\": \"https://example.com?handler=success\",\n \"method\": \"GET\"\n}\n```\nThe user will be redirected to URL:\n ```\n https://example.com?handler=success&session_id=0195c6eb-99ae-73c1-94f0-1763b872735d&template_id=0195c6eb-99ae-73c1-cc3a-1763b8743333d&language[0]=en-GB&document_name=Employment%20Agreement\n ```\n\nIn most cases, you want to immediately start a new **builder session** using the provided data and redirect the user back to our UI.\n", "operationId": "createBrowserSession", "tags": [ "Template browser" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Api.BrowserSession.Payload.CreateBrowserSessionPayload.CreateBrowserSessionPayload" }, "example": { "ui_language": "en-GB", "handlers": { "success_handler": { "url": "https://example.com", "method": "GET" }, "error_handler": { "url": "https://example.com", "method": "GET" }, "delete_handler": { "url": "https://example.com", "method": "GET" }, "cancel_handler": { "url": "https://example.com", "method": "GET" } } } } } }, "responses": { "201": { "description": "Successful response with details about the browser session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BrowserSession.Data.BrowserSessionCreatedData.BrowserSessionCreatedData" } } }, "example": { "data": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u" } } } } } } } }, "/api/browser/sessions/{session_id}": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Retrieve details of existing browser session", "description": "Returns details of the existing browser session. This information can serve as the source of truth when the user is redirected to your success handler.\n", "operationId": "getBrowserSession", "tags": [ "Template browser" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully retrieved the session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BrowserSession.Data.BrowserSessionData.BrowserSessionData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "status": "completed", "state": { "template_id": "0195c6eb-99ae-73c1-cc3a-1763b8743333d", "languages": [ "en-GB" ], "document_name": "Employment Agreement" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } }, "delete": { "summary": "Delete browser session", "description": "Invalidates the browser session. The session remains accessible through the API for a limited time before it is permanently deleted. If the end user is still viewing the page, they will be redirected to the delete handler URL you specified.\n\n> There is no need to delete completed sessions; they will be automatically pruned after a certain period.\n", "operationId": "deleteBrowserSession", "tags": [ "Template browser" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to delete.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully deleted the session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BrowserSession.Data.BrowserSessionData.BrowserSessionData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "status": "deleted", "state": null } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/api/builder/sessions": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Create a new builder session", "description": "A builder session is required to start drafting a document in the Builder through the Embed API. Each session is isolated and contains all document-related data. Once the session ends, all data is deleted from our servers.\n\n**To create a session, you need:**\n- A template ID - Get this from our Template Listing API or let the end-user pick one via the hosted Template Browser UI.\n- A list of languages - The languages must match the languages available for the selected template. The language determines the final document's language that the end-user drafts. Currently, only one language can be provided.\n- A document name - Acts like a file name. It's shown in the builder UI and can be edited by the end-user.\n\n**Participant details**\n\nYou can provide end-user details, such as display name and email, for your reference. These will be required later for collaboration features like commenting, but they are not currently in use. You can use the External ID field to store your internal user ID, which you can later use to match our participants with your users if needed.\n\n**Trial mode**\n\nYou can optionally enable trial mode by providing `trial` configuration in the request payload. Trial mode configures trial-related texts and CTA shown in the Builder UI.\nTrial sessions cannot be finalized with `POST /api/builder/sessions/{session_id}/contract/finalize`.\n\nHTML support in trial fields:\n- `heading_text`: HTML supported (sanitized). Allowed tags: `strong`, `b`, `wbr`.\n- `finalize_content`: HTML supported (sanitized). Allowed tags: `strong`, `b`, `wbr`, `br`, `li`, `ul`, `h2`, `h3`, `h4`, `p`.\n- `heading_cta_text`, `preview_text`, `finalize_title`, `finalize_cta_text`: plain text only (HTML not supported).\n\n**Finalization confirmation**\n\nYou can optionally provide `finalization` settings to control the confirmation dialog shown before finalization. Omit `finalization` to use the default dialog.\n- `confirmation_enabled` controls whether confirmation dialog is shown before finalization.\n- `confirmation_text`: HTML supported. Allowed tags: `strong`, `b`, `wbr`.\n- If `confirmation_enabled` is `true` and `confirmation_text` is `null`, the Builder UI falls back to its default confirmation message.\n- If trial mode is enabled (`trial` is not `null`), `finalization` settings are ignored.\n\nFor more details and an example of the default dialog, see the [Finalize confirmation dialog](/embed-api/legal-engine/finalize-confirmation) guide.\n\n**Redirect URL**\n\nAfter creating a session, you'll get a one-time URL to send the end-user to our hosted builder UI. Opening the link creates a secure session with access to that document only.\n\nThe redirect URL is valid for 15 minutes.\n\n#### Handlers\nYou need to provide handlers that redirect the end user back to your service after drafting.\n\n**Success handler**\nThe user is redirected to this URL after completing the drafting session and filling in all the required information. The document is then considered \"ready\" and cannot be altered. Please note that the endpoint may be called multiple times if users navigates back to our builder via browser history.\n\n**Cancel handler**\nThe user is redirected to this URL after canceling the drafting session. The builder session remains intact. If the user navigates back to our UI using browser history, they can resume drafting. Therefore, it is possible for this handler to be called multiple times.\n\n**Delete handler**\nThe user is redirected to this URL after the document is deleted. Document can be deleted via API and end-users can delete the document through the UI. Once deleted, the document cannot be altered, but it remains accessible via the API for a certain period before being permanently deleted. If the user navigates back to the builder after deletion, they will be automatically redirected to this handler. Consequently, this endpoint may be called multiple times.\n\n**Error handler**\nThe user is redirected to this URL when an unexpected error occurs.\n\n#### Handler url parameters\n\nHandler URLs are appended (existing parameters will remain unchanged) with the following query parameters:\n| Parameter | Description |\n| --------------- | ---------------------------------------------------- |\n| `session_id` | Builder session ID |\n| `participant_id`| Builder participant ID |\n", "operationId": "createBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBuilderSessionPayload" }, "example": { "contract": { "template_id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "document_name": "Employment agreement", "languages": [ "en-GB" ] }, "participant": { "email": "john.doe@example.org", "display_name": "John Doe" }, "ui_language": "en-GB", "handlers": { "success_handler": { "url": "https://example.com", "method": "GET" }, "error_handler": { "url": "https://example.com", "method": "GET" }, "delete_handler": { "url": "https://example.com", "method": "GET" }, "cancel_handler": { "url": "https://example.com", "method": "GET" } }, "finalization": { "confirmation_enabled": true, "confirmation_text": "Please review carefully. This action cannot be undone." } } } } }, "responses": { "201": { "description": "Successful response with details about the builder session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData" } } }, "example": { "data": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u", "participant": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "display_name": null, "external_id": null, "email": null } } } } } } } } }, "/api/builder/sessions/{session_id}": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Retrieve details of existing builder session", "description": "Returns details of the existing builder session.\n", "operationId": "getBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully retrieved the session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BuilderSessionData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "status": "completed", "trial": null, "finalization": null, "participants": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "display_name": null, "email": null, "external_id": null } ] } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } }, "patch": { "summary": "Update existing builder session", "description": "Updates mutable builder session settings.\n\nCurrently the endpoint supports updating:\n- `trial` mode configuration. Set `trial` to `null` to disable trial mode.\n- `finalization` confirmation settings. Set `finalization` to `null` to clear custom finalization behavior.\nFor trial and finalization field definitions, constraints, and HTML support rules, see\n[Create a new builder session](#operation/createBuilderSession).\nSee also the [Finalize confirmation dialog](/embed-api/legal-engine/finalize-confirmation) guide.\n", "operationId": "updateBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to update.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "X-Participant", "in": "header", "required": true, "description": "Participant ID of a user in this builder session.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBuilderSessionPayload" }, "example": { "trial": { "cta_url": "https://example.com/trial", "heading_text": "Free trial - Upgrade to unlock full preview, downloads, and e-signing.", "heading_cta_text": "Explore plans", "preview_text": "Unlock full preview", "finalize_title": "Finish and use your document", "finalize_content": "

Your document is ready.

Upgrade to:

", "finalize_cta_text": "Explore plans" }, "finalization": { "confirmation_enabled": true, "confirmation_text": "Please review carefully. This action cannot be undone." } } } } }, "responses": { "200": { "description": "Successfully updated the session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BuilderSessionData" } } }, "example": { "data": { "id": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a", "status": "pending", "trial": { "cta_url": "https://example.com/trial", "heading_text": "Free trial - Upgrade to unlock full preview, downloads, and e-signing.", "heading_cta_text": "Explore plans", "preview_text": "Unlock full preview", "finalize_title": "Finish and use your document", "finalize_content": "

Your document is ready.

Upgrade to:

", "finalize_cta_text": "Explore plans" }, "finalization": { "confirmation_enabled": true, "confirmation_text": "Please review carefully. This action cannot be undone." }, "participants": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "display_name": "Jane Doe", "email": "jane.doe@example.org", "external_id": "user-123" } ] } } } } }, "404": { "description": "Session or participant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "409": { "description": "Session cannot be updated in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "Only a pending session can be patched" } } } } } }, "422": { "description": "Validation error in request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete builder session", "description": "Invalidates the builder session. The session is no longer accessible via the API after deletion. If the end user is still in the builder, they are redirected to the delete handler URL you provided when creating the session.\n", "operationId": "deleteBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to delete.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "204": { "description": "Successfully deleted the session. No content is returned." }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/api/builder/sessions/{session_id}/contract": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Get contract state and signees", "description": "Get contract's state and list of signees.\n", "operationId": "getBuilderSessionContract", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully retrieved contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractState" }, "example": { "data": { "state": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "draft", "document_name": "Testing document", "jurisdiction": "FI", "languages": [ "en-GB" ], "value": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba5-fca3d9d646a4", "basic": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-03235f09a720", "title": { "_type": "translatable", "en-GB": "Non-Disclosure Agreement" } }, "parties": [ { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-07fd964cae09", "type": "company", "company_name": "Docue", "company_id": "1212", "first_name": "John", "last_name": "Doe", "job_title": "" }, { "_type": "value", "_id": "0196ae5c-3d2e-7005-9c0d-746605183d92", "type": "person", "company_name": "", "company_id": "", "first_name": "Richard", "last_name": "Roe", "job_title": "" } ], "place_and_date": { "_type": "value", "_id": "0196ae5b-2e9e-706c-aa37-3327550c36ee", "place": "Helsinki", "date": "2025-05-01" } }, "sections": [ { "_type": "contract-section", "id": "0196623c-5d00-7ff8-9528-5187dc2fe5d9", "title": { "_type": "translatable", "en-GB": "Basic information" }, "name": "", "is_included": true, "type": "template", "template_section_id": "0196623c-5d00-7ff8-9528-5187dc2fe5d9", "content": null }, { "_type": "contract-section", "id": "0196ae74-b492-700e-a824-9899cb125a3b", "title": { "_type": "translatable", "en-GB": "Background" }, "name": "", "is_included": true, "type": "custom", "content": { "_type": "translatable", "en-GB": "

Background for this contract is to just test the builder.

" } }, { "_type": "contract-section", "id": "0196623c-8461-7ff8-9528-740c187c94cc", "title": { "_type": "translatable", "en-GB": "Contracting parties" }, "name": "", "is_included": true, "type": "template", "template_section_id": "0196623c-8461-7ff8-9528-740c187c94cc", "content": null }, { "_type": "contract-section", "id": "01966243-fe05-7ff8-9529-572ead0c674b", "title": { "_type": "translatable", "en-GB": "Place and date" }, "name": "", "is_included": true, "type": "template", "template_section_id": "01966243-fe05-7ff8-9529-572ead0c674b", "content": null } ], "appearance": { "logo": { "enabled": false, "content": null, "scale": 50 }, "footer": { "enabled": false, "content": "" }, "heading1": { "family": "arial", "color": "#000000", "size": "20", "weight": "bold", "alignment": "left", "transform": "none" }, "heading2": { "family": "arial", "color": "#000000", "size": "13", "weight": "bold", "alignment": "left", "transform": "none" }, "heading3": { "family": "arial", "color": "#000000", "size": "12", "weight": "bold", "alignment": "left", "transform": "none" }, "heading4": { "family": "arial", "color": "#000000", "size": "11", "weight": "bold", "alignment": "left", "transform": "none" }, "heading5": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "left", "transform": "none" }, "heading6": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "left", "transform": "none" }, "paragraph": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "justify", "transform": "none" }, "table": { "family": "arial", "size": "11", "color": "#000000", "bgColor": "#ffffff", "headerBgColor": "#e7e5e4", "headerColor": "#000000", "borderColorEnabled": true, "borderColor": "#ffffff", "alternatingRowBgColorEnabled": true, "alternatingRowBgColor": "#fafaf9" } } }, "signees": [ { "_type": "signature", "id": "0196ae5b-2e9d-729f-aba6-07fd964cae09", "first_name": "John", "last_name": "Doe", "job_title": "", "fieldset_name": "parties", "page": 1, "x": 0.15219702338766833, "y": 0.3558135326624073, "width": 0.31498543192377354, "height": 0.10690274355869211 }, { "_type": "signature", "id": "0196ae5c-3d2e-7005-9c0d-746605183d92", "first_name": "Richard", "last_name": "Roe", "job_title": "", "fieldset_name": "parties", "page": 1, "x": 0.5040357508465233, "y": 0.3558135326624073, "width": 0.31498543192377354, "height": 0.10690274355869211 } ] } } } } } } }, "patch": { "summary": "Update contract state and appearance", "description": "Update the contract's state values and appearance using [JSON Patch (RFC 6902)](https://datatracker.ietf.org/doc/html/rfc6902) operations.\nThe available operations depend on the path, as does the value. Operations are applied sequentially in the order they appear, so later operations can build on the result of earlier ones.\n\nBy default the patch is all-or-nothing: if any operation fails, nothing is saved and the endpoint returns `422`.\n\nSet `allow_partial: true` to save the operations that succeed. The response is then always `200` and lists the failed operations under `meta.failed_operations`; if every operation failed, nothing is saved. A failed operation leaves no changes behind, so later operations that depend on it — including ones whose array index paths assume it succeeded — may fail or target a different element.\n\nAuthentication, not-found, and malformed-request errors (such as an unsupported `op`) fail the whole request. A `5xx` response does not guarantee that nothing was saved, so read the state before retrying.\n\nSee more detailed description and examples [here](/embed-api/legal-engine/document-state).\n", "operationId": "patchBuilderSessionContract", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "X-Participant", "in": "header", "required": true, "description": "The participant ID for the builder session. This header is required for updating the contract state.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 500, "description": "JSON Patch operations, applied in the order they appear.", "items": { "type": "object", "required": [ "op", "path" ], "properties": { "op": { "type": "string", "enum": [ "replace", "remove", "add" ], "example": "replace" }, "path": { "type": "string", "example": "/document_name" }, "value": { "example": "My document" } } } }, "allow_partial": { "type": "boolean", "default": false, "description": "When `true`, operations that succeed are saved even if others fail, and the response lists the failed operations under `meta.failed_operations`. When `false` (the default), the patch is all-or-nothing.\n", "example": true } } }, "examples": { "allOrNothing": { "summary": "Default all-or-nothing patch", "value": { "operations": [ { "op": "replace", "path": "/document_name", "value": "Employment agreement, John Doe" } ] } }, "partial": { "summary": "Partial success allowed", "value": { "allow_partial": true, "operations": [ { "op": "replace", "path": "/document_name", "value": "Employment agreement, John Doe" }, { "op": "replace", "path": "/value/basic/title", "value": "Employment agreement" } ] } } } } } }, "responses": { "200": { "description": "The resulting contract state. `meta.failed_operations` lists the operations that failed; an empty list means every operation was applied. Without `allow_partial` it is always empty, because any failed operation returns `422` instead.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractPatchResponse" }, "examples": { "partialSomeFailed": { "summary": "Partial success allowed and some operations failed", "value": { "data": { "state": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "draft", "document_name": "Employment agreement, John Doe", "jurisdiction": "FI", "languages": [ "en-GB" ], "value": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba5-fca3d9d646a4", "basic": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-03235f09a720", "title": { "_type": "translatable", "en-GB": "Non-Disclosure Agreement" } } }, "sections": [], "appearance": {} }, "signees": [] }, "meta": { "status": { "code": 200, "text": "OK" }, "failed_operations": [ { "index": 1, "path": "/value/basic/title", "error": { "code": "invalid_operation", "message": "Operation \"replace\" at \"/value/basic/title\" failed: invalid value", "details": { "value": "Invalid input: expected object, received string" } } } ] } } }, "partialAllFailed": { "summary": "Partial success allowed and every operation failed", "value": { "data": { "state": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "draft", "document_name": "Non-Disclosure Agreement", "jurisdiction": "FI", "languages": [ "en-GB" ], "value": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba5-fca3d9d646a4", "basic": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-03235f09a720", "title": { "_type": "translatable", "en-GB": "Non-Disclosure Agreement" } } }, "sections": [], "appearance": {} }, "signees": [] }, "meta": { "status": { "code": 200, "text": "OK" }, "failed_operations": [ { "index": 0, "path": "/id", "error": { "code": "invalid_operation", "message": "Operation \"replace\" at \"/id\" failed: Operations at the specified path are not permitted", "details": [] } }, { "index": 1, "path": "/value/basic/title", "error": { "code": "invalid_operation", "message": "Operation \"replace\" at \"/value/basic/title\" failed: invalid value", "details": { "value": "Invalid input: expected object, received string" } } } ] } } }, "fullState": { "summary": "Full contract state", "value": { "data": { "state": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "draft", "document_name": "Employment agreement, John Doe", "jurisdiction": "FI", "languages": [ "en-GB" ], "value": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba5-fca3d9d646a4", "basic": { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-03235f09a720", "title": { "_type": "translatable", "en-GB": "Non-Disclosure Agreement" } }, "parties": [ { "_type": "value", "_id": "0196ae5b-2e9d-729f-aba6-07fd964cae09", "type": "company", "company_name": "Docue", "company_id": "1212", "first_name": "John", "last_name": "Doe", "job_title": "" }, { "_type": "value", "_id": "0196ae5c-3d2e-7005-9c0d-746605183d92", "type": "person", "company_name": "", "company_id": "", "first_name": "Richard", "last_name": "Roe", "job_title": "" } ], "place_and_date": { "_type": "value", "_id": "0196ae5b-2e9e-706c-aa37-3327550c36ee", "place": "Helsinki", "date": "2025-05-01" } }, "sections": [ { "_type": "contract-section", "id": "0196623c-5d00-7ff8-9528-5187dc2fe5d9", "title": { "_type": "translatable", "en-GB": "Basic information" }, "name": "", "is_included": true, "type": "template", "template_section_id": "0196623c-5d00-7ff8-9528-5187dc2fe5d9", "content": null }, { "_type": "contract-section", "id": "0196ae74-b492-700e-a824-9899cb125a3b", "title": { "_type": "translatable", "en-GB": "Background" }, "name": "", "is_included": true, "type": "custom", "content": { "_type": "translatable", "en-GB": "

Background for this contract is to just test the builder.

" } }, { "_type": "contract-section", "id": "0196623c-8461-7ff8-9528-740c187c94cc", "title": { "_type": "translatable", "en-GB": "Contracting parties" }, "name": "", "is_included": true, "type": "template", "template_section_id": "0196623c-8461-7ff8-9528-740c187c94cc", "content": null }, { "_type": "contract-section", "id": "01966243-fe05-7ff8-9529-572ead0c674b", "title": { "_type": "translatable", "en-GB": "Place and date" }, "name": "", "is_included": true, "type": "template", "template_section_id": "01966243-fe05-7ff8-9529-572ead0c674b", "content": null } ], "appearance": { "logo": { "enabled": false, "content": null, "scale": 50 }, "footer": { "enabled": false, "content": "" }, "heading1": { "family": "arial", "color": "#000000", "size": "20", "weight": "bold", "alignment": "left", "transform": "none" }, "heading2": { "family": "arial", "color": "#000000", "size": "13", "weight": "bold", "alignment": "left", "transform": "none" }, "heading3": { "family": "arial", "color": "#000000", "size": "12", "weight": "bold", "alignment": "left", "transform": "none" }, "heading4": { "family": "arial", "color": "#000000", "size": "11", "weight": "bold", "alignment": "left", "transform": "none" }, "heading5": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "left", "transform": "none" }, "heading6": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "left", "transform": "none" }, "paragraph": { "family": "arial", "color": "#000000", "size": "11", "weight": "regular", "alignment": "justify", "transform": "none" }, "table": { "family": "arial", "size": "11", "color": "#000000", "bgColor": "#ffffff", "headerBgColor": "#e7e5e4", "headerColor": "#000000", "borderColorEnabled": true, "borderColor": "#ffffff", "alternatingRowBgColorEnabled": true, "alternatingRowBgColor": "#fafaf9" } } }, "signees": [ { "_type": "signature", "id": "0196ae5b-2e9d-729f-aba6-07fd964cae09", "first_name": "John", "last_name": "Doe", "job_title": "", "fieldset_name": "parties", "page": 1, "x": 0.15219702338766833, "y": 0.3558135326624073, "width": 0.31498543192377354, "height": 0.10690274355869211 }, { "_type": "signature", "id": "0196ae5c-3d2e-7005-9c0d-746605183d92", "first_name": "Richard", "last_name": "Roe", "job_title": "", "fieldset_name": "parties", "page": 1, "x": 0.5040357508465233, "y": 0.3558135326624073, "width": 0.31498543192377354, "height": 0.10690274355869211 } ] }, "meta": { "status": { "code": 200, "text": "OK" }, "failed_operations": [] } } } } } } }, "401": { "description": "Authentication failed. The API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session or participant not found, or the session has been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "422": { "description": "Nothing was saved. Either the request is malformed, or — without `allow_partial` — an operation failed. `meta.error.details` describes the problem when available.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "allOrNothingRejected": { "summary": "Operation failed without partial success", "value": { "data": null, "meta": { "status": { "code": 422, "text": "Unprocessable Content" }, "error": { "text": "Operation \"replace\" at \"/value/basic/title\" failed: invalid value", "details": { "value": "Invalid input: expected object, received string" } } } } }, "malformedRequest": { "summary": "Malformed request", "value": { "data": null, "meta": { "status": { "code": 422, "text": "Unprocessable Content" }, "error": { "text": "The allow partial field must be true or false.", "details": { "allow_partial": [ "The allow partial field must be true or false." ] } } } } } } } } } } } }, "/api/builder/sessions/{session_id}/contract/finalize": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Finalize contract", "description": "Finalize the current builder session contract. Once finalized, the document becomes read-only and can no longer be patched. The document PDF and HTML can still be downloaded.\n\nIn most cases, the end-user finalizes the contract directly through the Builder UI. Use this endpoint when you need to trigger finalization programmatically from your backend.\n\nRegardless of how finalization is triggered, if the end-user has the Builder UI open, they will be redirected to the `success_handler` URL configured when creating the session.\n", "operationId": "finalizeBuilderSessionContract", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to finalize.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "X-Participant", "in": "header", "required": true, "description": "The participant ID for the builder session performing the finalize action.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "responses": { "200": { "description": "Successfully finalized contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractState" } } } }, "409": { "description": "Contract already finalized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null", "description": "Always null for error responses." }, "meta": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer", "example": 409 }, "text": { "type": "string", "example": "Conflict" } }, "required": [ "code", "text" ] }, "error": { "type": "object", "properties": { "text": { "type": "string", "example": "Only a pending session can be finalized" } }, "required": [ "text" ] } }, "required": [ "status", "error" ] } }, "required": [ "data", "meta" ] }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "Only a pending session can be finalized" } } } } } } } } }, "/api/builder/sessions/{session_id}/contract/unfinalize": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Unfinalize contract", "description": "Revert a finalized builder session contract back to a pending (editable) state. Once unfinalized, the document can be patched again and the end-user can continue drafting.\n\nOnly a session with a `completed` status can be unfinalized. Calling this on a session that is not completed will return a `409 Conflict` error.\n", "operationId": "unfinalizeBuilderSessionContract", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to unfinalize.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "X-Participant", "in": "header", "required": true, "description": "The participant ID for the builder session performing the unfinalize action.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "responses": { "200": { "description": "Successfully unfinalized contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractState" } } } }, "409": { "description": "Contract is not in a completed state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null", "description": "Always null for error responses." }, "meta": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer", "example": 409 }, "text": { "type": "string", "example": "Conflict" } }, "required": [ "code", "text" ] }, "error": { "type": "object", "properties": { "text": { "type": "string", "example": "Only a completed session contract can be unfinalized" } }, "required": [ "text" ] } }, "required": [ "status", "error" ] } }, "required": [ "data", "meta" ] }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "Only a completed session contract can be unfinalized" } } } } } } } } }, "/api/builder/sessions/{session_id}/html": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Get HTML", "description": "Retrieve the rendered HTML of the builder session document. This matches the PDF contents but in HTML format for previewing or custom rendering flows.\n", "operationId": "getBuilderSessionHtml", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "responses": { "200": { "description": "Successfully retrieved HTML", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/api/builder/sessions/{session_id}/pdf": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Get PDF", "description": "Get rendered PDF for the builder session.\n", "operationId": "getBuilderSessionPdf", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ] } }, "/api/builder/sessions/{session_id}/participants": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Add new participant to existing session", "description": "Add a new participant to an existing Builder session.\n\nThis is useful for collaboration flows where multiple users can access and draft\nthe same document session.\n\nThe response includes a one-time URL that authenticates the added participant into\nthe existing session. After creating the participant, redirect that user to the\nreturned URL.\n\nThe Builder handles real-time collaboration automatically. All participants stay in\nsync without manual page refreshes.\n\nIf any participant finalizes the document, all active participants are redirected to\nthe success handler that was configured when the session was created.\n", "operationId": "addParticipantToBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddParticipantPayload" }, "example": { "ui_language": "en-GB", "participant": { "email": "john.doe@example.org", "display_name": "John Doe", "external_id": "user-123" } } } } }, "responses": { "201": { "description": "Successful response with details about the added participant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BuilderSession.Participant.Data.ParticipantAuthenticatedData.ParticipantAuthenticatedData" } } }, "example": { "data": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "url": "https://app.builder.docue.com/builder-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u", "participant": { "id": "0195d42e-d7d5-7f05-8eaf-af1a9c569230", "display_name": "John Doe", "external_id": "user-123", "email": "john.doe@example.org" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "422": { "description": "Validation error in request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/builder/sessions/{session_id}/participants/{participant_id}/authenticate": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Re-authenticate existing participant", "description": "If you want to re-authenticate an existing participant in an ongoing Builder session, you can use this endpoint.\n\nSee details about the url in [create builder session](#operation/createBuilderSession).\n", "operationId": "reauthenticateParticipant", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "participant_id", "in": "path", "required": true, "description": "The UUID of the participant to authenticate.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateParticipantPayload" }, "example": { "ui_language": "en-GB" } } } }, "responses": { "201": { "description": "Successful response with details about the authenticated participant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BuilderSession.Participant.Data.ParticipantAuthenticatedData.ParticipantAuthenticatedData" } } }, "example": { "data": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "url": "https://app.builder.docue.com/browser-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u", "participant": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "display_name": null, "external_id": null, "email": null } } } } } } } } }, "/api/builder/sessions/{session_id}/export": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "get": { "summary": "Export builder session", "description": "Export a builder session as a ZIP file so you can save it and later create a new draft\nwith [import](#operation/importBuilderSession).\n\nUse this when implementing document duplication (for example, after a document is finalized\nand you want to start a similar new document).\n\nThe ZIP contains session drafting data, including all attachments, values filled to the\ncontract, and style customizations. It does not include integration redirect handlers\n(`handlers`).\n", "operationId": "exportBuilderSession", "tags": [ "Builder" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the session to export.", "schema": { "type": "string", "format": "uuid", "example": "7f3f5f62-2c69-7d4e-8a3d-9c0f0e2c5f3a" } }, { "name": "X-Participant", "in": "header", "required": true, "description": "The participant ID for the builder session export request.", "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "responses": { "200": { "description": "Successfully exported builder session as ZIP archive.", "content": { "application/zip": { "schema": { "$ref": "#/components/schemas/BuilderSessionExportFile" } } } } } } }, "/api/builder/sessions/import": { "servers": [ { "url": "https://api.builder.docue.com", "description": "Production (Legal Engine)" } ], "post": { "summary": "Import builder session", "description": "Import a previously exported builder session ZIP archive and create a new builder session from it.\n\nThe exported bundle is signed. No changes to the bundle contents are allowed before import.\nIf the bundle is modified in any way, import fails with `400 Bad Request`.\n\nThe request must include:\n- `session_file`: a ZIP file created by the export endpoint (max size 15 MB).\n- `handlers`: redirect handlers for the new imported session.\n\nFor details about handlers, participant fields, and `ui_language`, see the\n[Create a new builder session](#operation/createBuilderSession) endpoint.\n", "operationId": "importBuilderSession", "tags": [ "Builder" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImportBuilderSessionPayload" }, "encoding": { "handlers": { "contentType": "application/json" }, "participant": { "contentType": "application/json" } }, "example": { "session_file": "", "handlers": { "success_handler": { "url": "https://example.com", "method": "GET" }, "error_handler": { "url": "https://example.com", "method": "GET" }, "delete_handler": { "url": "https://example.com", "method": "GET" }, "cancel_handler": { "url": "https://example.com", "method": "GET" } }, "participant": { "email": "john.doe@example.org", "display_name": "John Doe", "external_id": "user-123" }, "ui_language": "en-GB" } } } }, "responses": { "201": { "description": "Successful response with details about the imported builder session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuilderSessionImportResponse" }, "example": { "data": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "url": "https://app.builder.docue.com/builder-session/0195c6eb-99ae-73c1-94f0-1763b872735d#pREXDkBmZSOnl29EzmoICcfx9S19ix6u", "participant": { "id": "0195c6eb-99ae-73c1-94f0-1763b872735d", "display_name": "John Doe", "external_id": "user-123", "email": "john.doe@example.org" } } } } } }, "400": { "description": "Session import failed. This can happen if the exported bundle was modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 400, "text": "Bad Request" }, "error": { "text": "Session import failed" } } } } } } } } }, "/sign/sessions": { "post": { "summary": "Create a signing session", "description": "Create a signing session by providing files and participants.\n\nInclude signers in the `participants` array here, or add them later while the session is in `pending` state.\n\nFiles can be provided either by URL or uploaded directly:\n- **JSON request** (`application/json`): provide files as URL references in the `files` array.\n- **Multipart request** (`multipart/form-data`): upload file content directly as binary parts. The `data` part contains the JSON payload, and the `files` parts contain the binary file content. Each uploaded file corresponds by position to an entry in `data.files` that does not have a `url`.\n", "operationId": "createSigningSession", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSigningSessionPayload" }, "example": { "document_name": "Employment Agreement", "document_author": "HR Department", "external_id": "deal-42", "expires_at": "2026-03-31T10:30:00.000Z", "start": true, "files": [ { "name": "Employment Agreement.pdf", "url": "https://example.com/files/employment-agreement.pdf" } ], "signature_position": "inline", "participants": [ { "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 0, "deliveries": [ { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." }, { "type": "sms", "target": "+358401234567", "message": "Please sign by Friday." } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "signature_location": { "file_index": 0, "page": 1, "x": 0.15, "y": 0.36, "width": 0.31, "height": 0.1 } }, { "name": "Jane Roe", "ui_language": "sv", "signing_order": 1, "deliveries": [ { "type": "email", "target": "jane.roe@example.org" } ], "signing_methods": [ { "type": "otp_email" } ] } ], "webhooks": [ { "url": "https://example.com/webhooks/signing", "secret": "your-shared-secret" }, { "url": "https://example.com/webhooks/signing-audit" } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreateSigningSessionPayload" }, "files": { "type": "array", "description": "Binary file uploads. Each uploaded file corresponds by position to an entry in `data.files` that does not have a `url`.", "items": { "type": "string", "format": "binary" } } } }, "example": { "data": { "document_name": "Employment Agreement", "document_author": "HR Department", "external_id": "deal-42", "expires_at": "2026-03-31T10:30:00.000Z", "start": true, "signature_position": "inline", "files": [ { "name": "Employment Agreement.pdf" } ], "participants": [ { "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 0, "deliveries": [ { "type": "email", "target": "john.doe@example.org" } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "signature_location": { "file_index": 0, "page": 1, "x": 0.15, "y": 0.36, "width": 0.31, "height": 0.1 } } ], "webhooks": [ { "url": "https://example.com/webhooks/signing", "secret": "your-shared-secret" } ] }, "files": [ "(binary content of Employment Agreement.pdf)" ] }, "encoding": { "data": { "contentType": "application/json" } } } } }, "responses": { "201": { "description": "Successful response with details about the signing session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "started", "document_name": "Employment Agreement", "document_author": "HR Department", "external_id": "deal-42", "expires_at": "2026-03-31T10:30:00.000Z", "ui_domain": null, "email_from": null, "signature_position": "inline", "files": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88501", "file_name": "Employment Agreement.pdf", "file_size": 48211, "index": 0 } ], "participants": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 0, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88311", "delivery": { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } }, { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88312", "delivery": { "type": "sms", "target": "+358401234567", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ] }, { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88212", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "Jane Roe", "external_id": null, "ui_language": "sv", "signing_order": 1, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88321", "delivery": { "type": "email", "target": "jane.roe@example.org" }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "otp_email" } ] } ], "webhooks": [ { "url": "https://example.com/webhooks/signing", "secret_configured": true }, { "url": "https://example.com/webhooks/signing-audit", "secret_configured": false } ] }, "meta": { "status": { "code": 201, "text": "Created" } } } } } }, "422": { "description": "Signing session participant limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}": { "get": { "summary": "Retrieve details of existing signing session", "description": "Returns details of the existing signing session.\n", "operationId": "getSigningSession", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully retrieved the signing session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "pending", "document_name": "Employment Agreement", "document_author": "HR Department", "external_id": "deal-42", "expires_at": "2026-03-31T10:30:00.000Z", "ui_domain": null, "email_from": null, "signature_position": "inline", "files": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88501", "file_name": "Employment Agreement.pdf", "file_size": 48211, "index": 0 } ], "participants": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 0, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88311", "delivery": { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } }, { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88312", "delivery": { "type": "sms", "target": "+358401234567", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ] }, { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88212", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "Jane Roe", "external_id": null, "ui_language": "sv", "signing_order": 1, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88321", "delivery": { "type": "email", "target": "jane.roe@example.org" }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "otp_email" } ] } ], "webhooks": [ { "url": "https://example.com/webhooks/signing", "secret_configured": true }, { "url": "https://example.com/webhooks/signing-audit", "secret_configured": false } ] }, "meta": { "status": { "code": 200, "text": "OK" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } }, "delete": { "summary": "End signing session", "description": "End an existing signing session.\nA pending session is discarded and can no longer be used.\nA started session is cancelled. Participants who were invited are notified and can still view the document.\n", "operationId": "endSigningSession", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully ended the signing session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Signing session cannot be ended in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/start": { "post": { "summary": "Start signing session", "description": "Start an existing signing session.\nThis moves the session status from `pending` to `started`.\nStarting a session locks its files (no files can be added or removed) and allows participants to access the signing flow via their links.\nQueued invitations are sent when the session starts.\nIf the session is not in `pending` state, the endpoint returns `409 Conflict`.\n", "operationId": "startSigningSession", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully started the signing session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "started", "document_name": "Employment Agreement", "document_author": "HR Department", "external_id": "deal-42", "expires_at": "2026-03-31T10:30:00.000Z", "ui_domain": null, "email_from": null, "signature_position": "inline", "files": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88501", "file_name": "Employment Agreement.pdf", "file_size": 48211, "index": 0 } ], "participants": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 0, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88311", "delivery": { "type": "email", "target": "john.doe@example.org" }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" } ] } ] }, "meta": { "status": { "code": 200, "text": "OK" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "409": { "description": "Signing session is not pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "Only a pending signing session can be started" } } } } } } } } }, "/sign/sessions/{session_id}/renew": { "post": { "summary": "Renew expired signing session", "description": "Renew an expired signing session with a new due date.\nA session that expired after it was started returns to started, signatures already collected are kept. \nA session that expired before it was started returns to pending.\n", "operationId": "renewSigningSession", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expires_at" ], "properties": { "expires_at": { "$ref": "#/components/schemas/SigningSessionExpirationTime" } } } } } }, "responses": { "200": { "description": "Successfully renewed the signing session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Signing session is not expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/pdf": { "get": { "summary": "Get signing session PDF", "description": "Get the PDF for the signing session.\n\nDownload the final document once the session status is `completed`.\nAfter the last signature, the audit log and required signing evidence\nare packaged into the PDF. A download made before the session is\ncompleted contains the cryptographically valid signatures applied so\nfar, but not that evidence package.\n\nIf the session contains multiple files, they are merged and returned as one PDF.\n\nSee [Retrieving the signed document](/embed-api/signing/signed-document).\n", "operationId": "getSigningSessionPdf", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully retrieved the signing session PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/webhooks": { "get": { "summary": "List recent webhook delivery attempts", "description": "Returns the most recent webhook delivery attempts for the signing\nsession, newest first. Up to 50 attempts are returned.\n\nSee [Signing webhooks](/embed-api/signing/webhooks) for delivery\nbehavior, event types, and signature validation.\n", "operationId": "listSigningSessionWebhookCalls", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully retrieved the webhook delivery attempts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningWebhookCall" } } } } ] }, "example": { "data": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88401", "url": "https://example.com/webhooks/signing", "status": "delivered", "event": { "payload": { "workspace": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88001" }, "session": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "external_id": "deal-42", "status": "started", "status_changed_at": "2026-02-12T10:30:00Z" }, "participant": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "external_id": "user-123", "session_id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "signed", "status_changed_at": "2026-02-12T10:31:00Z", "decline_reason": null } }, "meta": { "type": "com.docue.sign.v1.participant.signed", "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88411", "timestamp": "2026-02-12T10:31:00Z" } }, "attempt": 1, "retry_after": null, "last_error": null } ], "meta": { "status": { "code": 200, "text": "OK" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/audit": { "get": { "summary": "List audit records for a signing session", "description": "Returns the audit records for the signing session, oldest first.\n", "operationId": "listSigningSessionAuditRecords", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "name": "page[size]", "in": "query", "required": false, "description": "How many records to return. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "page[pointer]", "in": "query", "required": false, "description": "Cursor from a previous page. Leave it out to start at the oldest records.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the audit records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningAuditRecord" } } } } ] }, "example": { "data": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88401", "actor": "integrator", "actor_id": "0196ae5b-2e9d-729f-aba5-fa4db6f88001", "type": "session.created", "timestamp": "2026-09-24T11:16:15.897Z", "client": { "ip": "203.0.113.10", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36" } } ], "meta": { "status": { "code": 200, "text": "OK" }, "pagination": { "items": 1, "total": null, "last_page": null, "page_size": 100, "has_pages": false, "is_first": true, "pointer": { "previous": null, "current": null, "next": null } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/files": { "post": { "summary": "Add new file to signing session", "description": "Add a new file to an existing signing session.\nIf `index` is provided, the file is inserted at that zero-based position in the `files` array.\nIf `index` is omitted, the file is appended to the end of the `files` array.\nIf the signing session is in state `started`, no new files can be added and the endpoint returns `409 Conflict`.\n\nThe file can be provided either by URL or uploaded directly:\n- **JSON request** (`application/json`): provide the file as a URL reference.\n- **Multipart request** (`multipart/form-data`): upload the file content directly as a binary part.\n", "operationId": "createSigningSessionFile", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionFileCreatePayload" }, "example": { "name": "Appendix A - Terms.pdf", "url": "https://example.com/files/appendix-a-terms.pdf", "index": 1 } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "data", "file" ], "properties": { "data": { "$ref": "#/components/schemas/SigningSessionFileUploadData" }, "file": { "type": "string", "format": "binary", "description": "The file content to upload." } } }, "example": { "data": { "name": "Appendix A - Terms.pdf", "index": 1 }, "file": "(binary content of Appendix A - Terms.pdf)" }, "encoding": { "data": { "contentType": "application/json" } } } } }, "responses": { "201": { "description": "Successfully created the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionFileResponse" }, "example": { "data": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88501", "file_name": "Employment Agreement.pdf", "file_size": 48211, "index": 0 }, { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88502", "file_name": "Appendix A - Terms.pdf", "file_size": 12044, "index": 1 } ], "meta": { "status": { "code": 201, "text": "Created" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "409": { "description": "Signing session is already started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "No new files can be added to a started signing session" } } } } } } } } }, "/sign/sessions/{session_id}/participants": { "post": { "summary": "Add new participant to signing session", "description": "Add a new participant to an existing signing session. The session must be in `pending` state.\n", "operationId": "createSigningSessionParticipant", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipant" }, "example": { "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 1, "deliveries": [ { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" } ] } } } }, "responses": { "201": { "description": "Successfully created the participant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipantResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "status": "pending", "status_changed_at": "2026-02-12T10:30:00Z", "name": "John Doe", "external_id": "user-123", "ui_language": "en-GB", "signing_order": 1, "invitations": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88311", "delivery": { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-02-12T10:30:00Z", "sent_at": null, "opened_at": null, "revoked_at": null } } ], "signing_methods": [ { "type": "eid", "target": "fi_nordea" } ] }, "meta": { "status": { "code": 201, "text": "Created" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "422": { "description": "Signing session participant limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}": { "delete": { "summary": "Remove participant from signing session", "description": "Remove an existing participant from the signing session.\n", "operationId": "removeSigningSessionParticipant", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" } ], "responses": { "204": { "description": "Successfully removed the participant. No content is returned." }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}/excuse": { "post": { "summary": "Excuse participant from signing on started session", "description": "Release a participant from the requirement to sign. Their outstanding\ninvitations stop working immediately.\n\nAt least one participant must still sign or have signed.\nYou cannot excuse a participant who is currently signing or who has already signed.\n\nIf nobody remains who still needs to sign, the session completes.\n", "operationId": "excuseSigningSessionParticipant", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" } ], "responses": { "200": { "description": "Successfully excused the participant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipantResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Signing session is not started, or the participant cannot be excused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "At least one participant must still sign or have signed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}/reinstate": { "post": { "summary": "Reinstate a declined participant", "description": "Bring a declined participant back to pending. No invitation is sent.\n\nThe session must be started. Only a declined participant can be\nreinstated.\n", "operationId": "reinstateSigningSessionParticipant", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" } ], "responses": { "200": { "description": "Successfully reinstated the participant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipantResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Signing session is not started, or the participant has not declined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}/invitations": { "post": { "summary": "Create invitation for participant", "description": "Creates a new invitation for a participant.\n\nFor manual delivery, the response includes a signing URL that you share\nwith the signer. Allowed while the session is pending or started.\n\nFor email or SMS delivery, Docue notifies the signer and no signing URL\nis returned. The session must already be started.\n\nManual signing URLs work only after the session has started.\n", "operationId": "createSigningSessionParticipantInvitation", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipantInvitationCreate" }, "examples": { "email": { "summary": "Email delivery", "value": { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." } }, "manual": { "summary": "Manual delivery where the integrator shares the URL", "value": { "type": "manual" } } } } } }, "responses": { "201": { "description": "Successfully created the invitation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionParticipantInvitationResponse" }, "examples": { "email": { "summary": "Email delivery", "value": { "data": { "id": "019f1833-f214-745e-a87c-fdf627b8bc6c", "delivery": { "type": "email", "target": "john.doe@example.org", "message": "Please sign by Friday." }, "timeline": { "created_at": "2026-06-30T11:04:45.331Z", "sent_at": null, "opened_at": null, "revoked_at": null } }, "meta": { "status": { "code": 201, "text": "Created" } } } }, "manual": { "summary": "Manual delivery", "value": { "data": { "id": "019f1833-f214-745e-a87c-fdf627b8bc6c", "signing_url": "https://sign.docue.com/s/#access-code", "delivery": { "type": "manual", "target": null }, "timeline": { "created_at": "2026-06-30T11:04:45.331Z", "sent_at": null, "opened_at": null, "revoked_at": null } }, "meta": { "status": { "code": 201, "text": "Created" } } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}/invitations/{invitation_id}/resend": { "post": { "summary": "Resend an invitation", "description": "Sends the same email or SMS again for an invitation that was already sent.\nThe signing URL does not change and no new invitation is created.\n\nSee [Invitations](/embed-api/signing/invitations#resend-an-invitation) for when\nresending is allowed and how often you can do it.\n", "operationId": "resendSigningSessionParticipantInvitation", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" }, { "$ref": "#/components/parameters/SigningInvitationId" } ], "responses": { "204": { "description": "The invitation will be sent again. No content is returned." }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The invitation cannot be resent in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The invitation was resent too recently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sign/sessions/{session_id}/participants/{participant_id}/invitations/{invitation_id}": { "delete": { "summary": "Revoke a previously created invitation", "description": "Revoke a single invitation so its signing URL stops working immediately.\n\nEach invitation has its own signing URL; revoking one invitation does not affect\nother invitations for the same participant. Use this when a message was sent to\nthe wrong recipient or the link must otherwise be invalidated.\n\nRevoking an already-revoked invitation returns 409 Conflict.\n", "operationId": "deleteSigningSessionParticipantInvitation", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "$ref": "#/components/parameters/SigningParticipantId" }, { "$ref": "#/components/parameters/SigningInvitationId" } ], "responses": { "204": { "description": "Successfully revoked the invitation. No content is returned." }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } }, "409": { "description": "Invitation already revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 409, "text": "Conflict" }, "error": { "text": "Cannot revoke an invitation that was already revoked" } } } } } } } } }, "/sign/sessions/{session_id}/sender-uis": { "post": { "summary": "Create sender UI for signing session", "description": "Create a new Sender UI resource for an existing signing session.\n\nThe response includes a one-time URL to the hosted Sender UI.\nThe URL is valid for 15 minutes and becomes invalid immediately after first successful use.\n\nYou must provide a handler URL:\n- `return_handler`: the user is redirected to this URL when leaving the Sender UI.\n\nThe handler URL is appended with query parameters:\n| Parameter | Description |\n| -------------- | ------------------ |\n| `session_id` | Signing session ID |\n| `sender_ui_id` | Sender UI ID |\n\nUse this endpoint when you want to create a new Sender UI instance with its own handlers and configuration.\n", "operationId": "createSigningSessionSenderUi", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSigningSessionSenderUiPayload" }, "example": { "ui_language": "en-GB", "handlers": { "return_handler": { "url": "https://example.com/sender-ui/return", "method": "GET" } }, "configuration": { "editable_parts": [ "files", "participants", "invitations", "reminders", "start_session" ], "allowed_signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "allow_start": true } } } } }, "responses": { "201": { "description": "Successfully created and authenticated sender UI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionSenderUiAuthenticatedResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88401", "url": "https://sign.docue.com/sender-session/0196ae5b-2e9d-729f-aba5-fa4db6f88401#access-code", "handlers": { "return_handler": { "url": "https://example.com/sender-ui/return", "method": "GET" } }, "configuration": { "editable_parts": [ "files", "participants", "invitations", "reminders", "start_session" ], "allowed_signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "allow_start": true }, "created_at": "2026-02-12T10:30:00Z", "updated_at": "2026-02-12T10:30:00Z", "last_authenticated_at": "2026-02-12T10:30:00Z" }, "meta": { "status": { "code": 201, "text": "Created" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } }, "get": { "summary": "List sender interfaces for signing session", "description": "List existing Sender UI resources for the signing session.\n\nThe list response does not include one-time authentication URLs.\nTo open an existing Sender UI again, call the authenticate endpoint.\n", "operationId": "getSigningSessionSenderUis", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" } ], "responses": { "200": { "description": "Successfully retrieved sender UIs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionSenderUiListResponse" }, "example": { "data": [ { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88401", "handlers": { "return_handler": { "url": "https://example.com/sender-ui/return", "method": "GET" } }, "configuration": { "editable_parts": [ "files", "participants", "invitations", "reminders", "start_session" ], "allowed_signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "allow_start": true }, "created_at": "2026-02-12T10:30:00Z", "updated_at": "2026-02-12T10:35:00Z", "last_authenticated_at": "2026-02-12T10:35:00Z" } ], "meta": { "status": { "code": 200, "text": "OK" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/sender-uis/{sender_ui_id}/authenticate": { "post": { "summary": "Re-authenticate existing sender UI", "description": "Create a new one-time authentication URL for an existing Sender UI.\nUse this when the previous URL has expired or has already been used.\n\nSee details about URL behavior in [create sender UI](#operation/createSigningSessionSenderUi).\n", "operationId": "authenticateSigningSessionSenderUi", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "name": "sender_ui_id", "in": "path", "required": true, "description": "The UUID of the sender UI to authenticate.", "schema": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateSigningSessionSenderUiPayload" }, "example": { "ui_language": "en-GB" } } } }, "responses": { "201": { "description": "Successfully authenticated sender UI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSessionSenderUiAuthenticatedResponse" }, "example": { "data": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88401", "url": "https://sign.docue.com/sender-session/0196ae5b-2e9d-729f-aba5-fa4db6f88401#access-code", "handlers": { "return_handler": { "url": "https://example.com/sender-ui/return", "method": "GET" } }, "configuration": { "editable_parts": [ "files", "participants", "invitations", "reminders", "start_session" ], "allowed_signing_methods": [ { "type": "eid", "target": "fi_nordea" }, { "type": "otp_sms" } ], "allow_start": true }, "created_at": "2026-02-12T10:30:00Z", "updated_at": "2026-02-12T10:35:00Z", "last_authenticated_at": "2026-02-12T10:35:00Z" }, "meta": { "status": { "code": 201, "text": "Created" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } }, "/sign/sessions/{session_id}/sender-uis/{sender_ui_id}": { "delete": { "summary": "Remove sender UI from signing session", "description": "Remove an existing Sender UI resource from the signing session.\n", "operationId": "removeSigningSessionSenderUi", "tags": [ "Signing" ], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/SigningSessionId" }, { "name": "sender_ui_id", "in": "path", "required": true, "description": "The UUID of the sender UI to remove.", "schema": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" } } ], "responses": { "204": { "description": "Successfully removed the sender UI. No content is returned." }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "data": null, "meta": { "status": { "code": 404, "text": "Not Found" }, "error": { "text": "Resource not found" } } } } } } } } } }, "components": { "parameters": { "AcceptHeader": { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "description": "Specify the response format." }, "PaginationPerPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 15, "example": 20 }, "description": "Number of items per page." }, "PaginationPage": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 }, "description": "Page number to retrieve. Defaults to 1." }, "TemplateCollectionsFilterQuery": { "name": "filter[query]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Filter collections by a partial match against the localized title.", "example": "HR" }, "TemplateCollectionsSort": { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Sort order for the template collection list. Use the field name for ascending order, or prefix with `-` for descending order (for example, `title` sorts by localized title ascending; `-title` sorts descending).\n\nAllowed sort fields: `title`, `id`, and `updated_at`.\n\nWhen sorting by `title`, set `sort_locale` to control which translation is preferred for the comparison. If `sort_locale` is omitted, the API compares titles using a fallback across all supported languages.\n", "example": "title" }, "TemplatesFilterQuery": { "name": "filter[query]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Filter templates by a partial match against the localized title.", "example": "employment" }, "TemplatesFilterCollection": { "name": "filter[collection]", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter templates to those belonging to the specified template collection. Use `GET /api/template-collections` to discover available collection IDs. Please note that a template may belong to multiple collections.", "example": "01965c7e-dc1e-7292-8199-8184041c1204" }, "TemplatesInclude": { "in": "query", "name": "include", "schema": { "type": "string" }, "required": false, "description": "Comma delimited list of optional relationships to include.
Available includes: `collections`, `jurisdictions`, `languages`.", "example": "collections,languages,jurisdictions" }, "TemplatesSort": { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Sort order for the template list. Use the field name for ascending order, or prefix with `-` for descending order (for example, `title` sorts by localized title ascending; `-title` sorts descending).\n\nAllowed sort fields: `title`, `created_at`, and `updated_at`.\n\nMultiple sorts can be combined in one parameter as a comma-separated list (for example, `sort=title,-created_at`).\n\nWhen sorting by `title`, set `sort_locale` to control which translation is preferred for the comparison. If `sort_locale` is omitted, the API compares titles using a fallback across all supported languages.\n", "example": "title" }, "TemplatesSortLocale": { "name": "sort_locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "en-US", "en-GB", "en-AU", "en-CA", "en-IN", "en-NZ", "en-ZA", "es", "pt", "de", "fr", "tr", "it", "pl", "ro", "nl", "sv", "hu", "cs", "el", "fi", "no", "da", "sk", "bg", "hr", "sr", "lt", "lv", "sl", "et", "is" ] }, "description": "Locale code used when sorting by `title`: that language’s string is preferred when comparing titles (other languages are still used as fallback). Must be one of the supported Builder language codes. Ignored when the active sort does not use localized title.\n", "example": "en-GB" }, "SigningSessionId": { "name": "session_id", "in": "path", "required": true, "description": "The UUID of the signing session.", "schema": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd" } }, "SigningParticipantId": { "name": "participant_id", "in": "path", "required": true, "description": "The UUID of the participant.", "schema": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88211" } }, "SigningInvitationId": { "name": "invitation_id", "in": "path", "required": true, "description": "The UUID of the invitation.", "schema": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88311" } } }, "securitySchemes": { "APIKey": { "description": "API authentication using bearer token.", "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "CreateBrowserSessionPayload": { "$ref": "#/components/schemas/Api.BrowserSession.Payload.CreateBrowserSessionPayload.CreateBrowserSessionPayload" }, "BrowserSessionCreatedData": { "$ref": "#/components/schemas/Api.BrowserSession.Data.BrowserSessionCreatedData.BrowserSessionCreatedData" }, "BrowserSessionData": { "$ref": "#/components/schemas/Api.BrowserSession.Data.BrowserSessionData.BrowserSessionData" }, "CreateBuilderSessionPayload": { "type": "object", "additionalProperties": false, "properties": { "contract": { "$ref": "#/components/schemas/Api.BuilderSession.Payload.ContractPayload.ContractPayload" }, "handlers": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlersPayload.HandlersPayload" }, "participant": { "$ref": "#/components/schemas/App.Payload.Primitives.ParticipantPayload.ParticipantPayload" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" }, "trial": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionTrial" }, { "type": "null" } ] }, "finalization": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionFinalization" }, { "type": "null" } ], "description": "Optional finalization confirmation behavior for the finalize dialog.\nSet to `null` (or omit) to use the default Builder UI behavior.\n" } }, "required": [ "contract", "handlers" ] }, "AuthenticateParticipantPayload": { "type": "object", "additionalProperties": false, "properties": { "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } } }, "AddParticipantPayload": { "type": "object", "additionalProperties": false, "properties": { "participant": { "$ref": "#/components/schemas/App.Payload.Primitives.ParticipantPayload.ParticipantPayload" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } }, "required": [ "participant" ] }, "ParticipantAuthenticatedData": { "$ref": "#/components/schemas/Api.BuilderSession.Participant.Data.ParticipantAuthenticatedData.ParticipantAuthenticatedData" }, "BuilderSessionCreatedData": { "$ref": "#/components/schemas/Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData" }, "BuilderSessionData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/App.Enums.BuilderSessionStatus" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/App.Data.Primitives.ParticipantData.ParticipantData" } }, "trial": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionTrial" }, { "type": "null" } ] }, "finalization": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionFinalization" }, { "type": "null" } ], "description": "Finalization confirmation settings currently configured for this session.\n`null` means the default Builder UI behavior is used.\n" }, "_data_type": { "type": "string" } }, "required": [ "id", "status", "participants", "trial", "finalization" ] }, "BuilderSessionFinalization": { "type": "object", "additionalProperties": false, "description": "Finalization confirmation settings for the finalize dialog.\n`confirmation_enabled` is required whenever `finalization` is provided.\nThese settings are ignored while trial mode is enabled (`trial` is not `null`).\n", "properties": { "confirmation_enabled": { "type": "boolean", "description": "Enables custom confirmation behavior in the finalize dialog.\nWhen `true`, Builder shows either `confirmation_text` (if provided) or its default confirmation copy.\n" }, "confirmation_text": { "anyOf": [ { "type": "string", "maxLength": 255, "description": "Optional custom message. HTML supported. Allowed tags: `strong`, `b`, `wbr`.\n", "example": "Please review carefully. This action cannot be undone." }, { "type": "null", "description": "Default confirmation copy is used." } ] } }, "required": [ "confirmation_enabled" ] }, "BuilderSessionTrial": { "type": "object", "additionalProperties": false, "description": "Trial mode configuration shown in the Builder UI. When trial mode is enabled, the session cannot be finalized.\nOnly `heading_text` and `finalize_content` support sanitized HTML. Other text fields are plain text only.\n", "properties": { "cta_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Trial CTA target URL. Must be an absolute `http` or `https` URL (for example, `http://localhost:3000/plans` in development).", "example": "https://example.com/trial" }, "heading_text": { "type": "string", "maxLength": 240, "description": "Main trial heading. HTML is sanitized and only `strong`, `b`, and `wbr` tags are preserved. Unsupported tags are stripped.", "example": "Free trial - Upgrade to unlock full preview, downloads, and e-signing." }, "heading_cta_text": { "type": "string", "minLength": 2, "maxLength": 30, "description": "CTA label in the heading area. Plain text only (HTML not supported). Length must be 2-30 characters.", "example": "Explore plans" }, "preview_text": { "type": "string", "maxLength": 240, "description": "Text shown in preview mode lock state. Plain text only (HTML not supported).", "example": "Unlock full preview" }, "finalize_title": { "type": "string", "maxLength": 240, "description": "Title shown on the finalize step in trial mode. Plain text only (HTML not supported).", "example": "Finish and use your document" }, "finalize_content": { "type": "string", "maxLength": 240, "description": "Finalize step content. HTML is sanitized and only `strong`, `b`, `wbr`, `br`, `li`, `ul`, `h2`, `h3`, `h4`, and `p` tags are preserved. Unsupported tags are stripped.", "example": "

Your document is ready.

Upgrade to:

" }, "finalize_cta_text": { "type": "string", "minLength": 2, "maxLength": 30, "description": "CTA label on the finalize step. Plain text only (HTML not supported). Length must be 2-30 characters.", "example": "Explore plans" } }, "required": [ "cta_url", "heading_text", "heading_cta_text", "preview_text", "finalize_title", "finalize_content", "finalize_cta_text" ] }, "PatchBuilderSessionPayload": { "type": "object", "additionalProperties": false, "properties": { "trial": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionTrial" }, { "type": "null" } ] }, "finalization": { "anyOf": [ { "$ref": "#/components/schemas/BuilderSessionFinalization" }, { "type": "null" } ], "description": "Pass `null` to clear previously set finalization settings and restore default Builder UI behavior.\n" } } }, "ImportBuilderSessionPayload": { "type": "object", "additionalProperties": false, "properties": { "session_file": { "type": "string", "format": "binary", "description": "ZIP archive exported from `/api/builder/sessions/{session_id}/export`." }, "handlers": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlersPayload.HandlersPayload" }, "participant": { "$ref": "#/components/schemas/App.Payload.Primitives.ParticipantPayload.ParticipantPayload" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } }, "required": [ "session_file", "handlers" ] }, "BuilderSessionImportResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData" } }, "required": [ "data" ] }, "BuilderSessionExportFile": { "type": "string", "format": "binary", "description": "ZIP archive containing exported builder session data." }, "CreateSigningSessionPayload": { "type": "object", "additionalProperties": false, "required": [ "document_name", "document_author" ], "properties": { "document_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the document shown in the signing UI.\n", "example": "Employment Agreement" }, "document_author": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Author name associated with the document.\n", "example": "HR Department" }, "external_id": { "$ref": "#/components/schemas/SigningSessionExternalId" }, "expires_at": { "$ref": "#/components/schemas/SigningSessionExpirationTime" }, "ui_domain": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionUiDomain" } ] }, "email_from": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionEmailFrom" } ] }, "start": { "type": "boolean", "default": false, "description": "Whether the signing session is started immediately after creation. If `true`, the created session status is `started`; if `false` (or omitted), status is `pending`. Starting a session locks its files (no files can be added or removed) and allows participants to access the signing flow via their links. Queued invitations are sent when the session starts.", "example": true }, "signature_position": { "$ref": "#/components/schemas/SigningSessionSignaturePosition" }, "files": { "type": "array", "description": "Optional list of files for the signing session. If multiple files are provided, they are merged into a single PDF. When using `application/json`, each file must include a `url`. When using `multipart/form-data`, `url` can be omitted — files without a `url` are matched by position to the uploaded binary parts.", "items": { "$ref": "#/components/schemas/SigningSessionFileInput" } }, "participants": { "type": "array", "maxItems": 40, "description": "Signers for the signing session, including any added after creation while the session is in a ` pending ` state.", "items": { "$ref": "#/components/schemas/SigningSessionParticipant" } }, "webhooks": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/SigningSessionWebhook" } } } }, "SigningSuccessResponse": { "type": "object", "properties": { "data": { "description": "Response body. Null when there is nothing to return." }, "meta": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "code", "text" ] }, "pagination": { "type": "object", "description": "Present when the result is paged. Send the next pointer back to read the following page.", "properties": { "items": { "type": "integer", "minimum": 0, "description": "How many records are in this page." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "How many records match in total. Empty when the total was not counted." }, "last_page": { "type": [ "integer", "null" ], "minimum": 1, "description": "Last page number for this page size. Empty when the total was not counted." }, "page_size": { "type": "integer", "minimum": 1, "description": "Maximum number of records in a page." }, "has_pages": { "type": "boolean", "description": "Whether another page exists before or after this one." }, "is_first": { "type": "boolean", "description": "Whether this is the first page." }, "pointer": { "type": "object", "properties": { "previous": { "type": [ "string", "null" ], "description": "Pointer to the previous page. Empty on the first page." }, "current": { "type": [ "string", "null" ], "description": "Pointer for this page. Empty on the first page." }, "next": { "type": [ "string", "null" ], "description": "Pointer to the next page. Empty on the last page." } }, "required": [ "previous", "current", "next" ] } }, "required": [ "items", "total", "last_page", "page_size", "has_pages", "is_first", "pointer" ] } }, "required": [ "status" ] } }, "required": [ "data", "meta" ] }, "SigningSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SigningSessionData" } } } ] }, "SigningSessionFileCreatePayload": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "Appendix A - Terms.pdf" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/files/appendix-a-terms.pdf" }, "index": { "type": "integer", "minimum": 0, "description": "Optional zero-based index where the file is inserted in the session `files` array. If omitted, the file is appended to the end.", "example": 1 } }, "required": [ "name", "url" ] }, "SigningSessionFileUploadData": { "type": "object", "additionalProperties": false, "description": "JSON payload for the `data` part of a `multipart/form-data` file upload request.", "properties": { "name": { "type": "string", "description": "Display name for the file.", "example": "Appendix A - Terms.pdf" }, "index": { "type": "integer", "minimum": 0, "description": "Optional zero-based index where the file is inserted in the session `files` array. If omitted, the file is appended to the end.", "example": 1 } }, "required": [ "name" ] }, "SigningSessionFileResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningSessionFile" } } } } ] }, "SigningSessionParticipantResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SigningSessionParticipantData" } } } ] }, "SigningSessionParticipantInvitationResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SigningSessionParticipantInvitationData" } } } ] }, "CreateSigningSessionSenderUiPayload": { "type": "object", "additionalProperties": false, "properties": { "handlers": { "$ref": "#/components/schemas/SigningSessionSenderUiHandlersPayload" }, "configuration": { "$ref": "#/components/schemas/SigningSessionSenderUiConfiguration" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } }, "required": [ "handlers" ] }, "AuthenticateSigningSessionSenderUiPayload": { "type": "object", "additionalProperties": false, "properties": { "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } } }, "SigningSessionSenderUiAuthenticatedResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SigningSessionSenderUiAuthenticatedData" } } } ] }, "SigningSessionSenderUiListResponse": { "allOf": [ { "$ref": "#/components/schemas/SigningSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningSessionSenderUiData" } } } } ] }, "SigningSessionSenderUiData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" }, "handlers": { "$ref": "#/components/schemas/SigningSessionSenderUiHandlersPayload" }, "configuration": { "$ref": "#/components/schemas/SigningSessionSenderUiConfiguration" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-02-12T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-02-12T10:35:00Z" }, "last_authenticated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the latest successful authentication URL issuance.", "example": "2026-02-12T10:35:00Z" } }, "required": [ "id", "handlers", "created_at", "updated_at", "last_authenticated_at" ] }, "SigningSessionSenderUiAuthenticatedData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" }, "url": { "type": "string", "format": "uri", "description": "One-time URL to open the Sender UI. Valid for 15 minutes and single-use.", "example": "https://sign.docue.com/sender-session/0196ae5b-2e9d-729f-aba5-fa4db6f88401#access-code" }, "handlers": { "$ref": "#/components/schemas/SigningSessionSenderUiHandlersPayload" }, "configuration": { "$ref": "#/components/schemas/SigningSessionSenderUiConfiguration" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-02-12T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-02-12T10:35:00Z" }, "last_authenticated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the latest successful authentication URL issuance.", "example": "2026-02-12T10:35:00Z" } }, "required": [ "id", "url", "handlers", "created_at", "updated_at", "last_authenticated_at" ] }, "SigningSessionSenderUiHandlersPayload": { "type": "object", "additionalProperties": false, "properties": { "return_handler": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlerPayload.HandlerPayload" } }, "required": [ "return_handler" ] }, "SigningSessionSenderUiConfiguration": { "type": "object", "additionalProperties": false, "properties": { "editable_parts": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Which parts of the signing session can be edited in Sender UI. If omitted, all parts are editable.", "items": { "$ref": "#/components/schemas/SigningSessionSenderUiEditablePart" } }, "allowed_signing_methods": { "type": "array", "minItems": 1, "description": "Templates that constrain the `signing_methods` the sender can configure for each\nparticipant in this Sender UI session. Same item shape as a `signing_methods`\nentry (`SigningSessionAuthMethod`). If omitted, the sender may configure any\nmethod available to the workspace.\n\nValidation: every entry in `participant.signing_methods` must match some entry in\n`allowed_signing_methods` — same `type`, and either the template's `target`\nis omitted (any target allowed for this type), or the participant's\n`target` equals the template's `target`. To permit multiple target values\nfor one type (e.g., multiple eID providers), list multiple template\nentries.\n", "items": { "$ref": "#/components/schemas/SigningSessionAuthMethod" } }, "allow_start": { "type": "boolean", "default": true, "description": "Whether Sender UI can start the signing session.", "example": true } } }, "SigningSessionSenderUiEditablePart": { "type": "string", "enum": [ "files", "participants", "invitations", "reminders", "start_session" ], "example": "participants" }, "SigningSessionStatus": { "type": "string", "description": "Lifecycle status of the signing session.\n- `pending`: session created; files and participants can still be changed\n- `starting`: start is in progress\n- `started`: signing is open; participants can access Sign UI\n- `completed`: all participants have signed\n- `cancelled`: session was cancelled after signing started\n- `expired`: session expired before completion\n- `discarded`: session was discarded\n", "enum": [ "pending", "starting", "started", "completed", "cancelled", "expired", "discarded" ], "example": "pending" }, "SigningSessionParticipantStatus": { "type": "string", "description": "Lifecycle status of a participant on a signing session.\n- `pending`: created; has not yet opened Sign UI\n- `viewing`: participant has opened Sign UI\n- `signing`: signing in progress\n- `signed`: participant has signed\n- `declined`: participant declined to sign\n- `excused`: participant was excused from signing\n", "enum": [ "pending", "viewing", "signing", "signed", "declined", "excused" ], "example": "pending" }, "SigningSessionData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd" }, "status": { "$ref": "#/components/schemas/SigningSessionStatus" }, "document_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the document shown in the signing UI.", "example": "Employment Agreement" }, "document_author": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Author name associated with the document.", "example": "HR Department" }, "external_id": { "anyOf": [ { "$ref": "#/components/schemas/SigningSessionExternalId" }, { "type": "null" } ] }, "signature_position": { "$ref": "#/components/schemas/SigningSessionSignaturePosition" }, "expires_at": { "$ref": "#/components/schemas/SigningSessionExpirationTime" }, "ui_domain": { "anyOf": [ { "$ref": "#/components/schemas/SigningSessionUiDomain" }, { "type": "null" } ] }, "email_from": { "anyOf": [ { "$ref": "#/components/schemas/SigningSessionEmailFrom" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/SigningSessionFile" } }, "participants": { "type": "array", "maxItems": 40, "description": "Signers on the signing session.", "items": { "$ref": "#/components/schemas/SigningSessionParticipantData" } }, "webhooks": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/SigningSessionWebhookData" } } }, "required": [ "id", "status", "document_name", "document_author", "external_id", "signature_position", "expires_at", "ui_domain", "email_from" ] }, "SigningSessionUiDomain": { "type": "string", "format": "hostname", "description": "A custom domain registered for your workspace. This session's UI is served from it.\n", "example": "sign.acme.com" }, "SigningSessionEmailFrom": { "type": "string", "description": "From address for invitation emails sent for this session. The domain must be an email domain registered for your workspace.\n", "example": "\"Acme\" " }, "SigningSessionExternalId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your own identifier for correlating this session in your system.", "example": "deal-42" }, "SigningSessionExpirationTime": { "type": "string", "format": "date-time", "description": "Expiration time as an RFC 3339 timestamp, including a timezone. Must be at least one hour and no more than 180 days after creation. Defaults to 180 days.\n", "example": "2026-03-31T10:30:00.000Z" }, "SigningSessionParticipantExternalId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your own identifier for correlating this participant in your system.", "example": "user-123" }, "SigningSessionSignaturePosition": { "type": "string", "description": "Where signatures are placed in the final PDF.\n- `inline`: signatures are placed in the provided participant `signature_location`. Participants without a location remain invisible but are still digitally signed.\n- `start`: a separate signature page is attached to the beginning of the PDF.\n- `end`: a separate signature page is attached to the end of the PDF.\n", "enum": [ "inline", "start", "end" ], "example": "inline" }, "SigningSessionFileInput": { "type": "object", "description": "File entry for creating a signing session. When using `application/json`, `url` is required. When using `multipart/form-data`, `url` can be omitted — the file content is provided as an uploaded binary part instead.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Display name for the file.", "example": "Employment Agreement.pdf" }, "url": { "type": "string", "format": "uri", "description": "URL to fetch the file from. Required when using `application/json`. Can be omitted when uploading the file directly via `multipart/form-data`.", "example": "https://example.com/files/employment-agreement.pdf" } }, "required": [ "name" ] }, "SigningSessionFile": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string", "example": "Employment Agreement.pdf" }, "file_size": { "type": "integer", "minimum": 0 }, "index": { "type": "integer", "minimum": 0, "description": "Zero-based position of the file in the session." } }, "required": [ "id", "file_name", "file_size", "index" ] }, "SigningSessionParticipant": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "John Doe" }, "external_id": { "$ref": "#/components/schemas/SigningSessionParticipantExternalId" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" }, "signing_order": { "type": "integer", "minimum": 0, "default": 0, "description": "Participants sign in ascending order from 0 to N. Participants sharing the same value sign in parallel.", "example": 0 }, "deliveries": { "type": "array", "minItems": 1, "description": "How invitations reach this participant. At least one is required. Email and SMS are queued until the session starts.\n", "items": { "$ref": "#/components/schemas/SigningSessionParticipantInvitation" } }, "signing_methods": { "type": "array", "minItems": 1, "description": "List of allowed signature methods for this participant. `type: password`\nis rejected with `400 type_not_allowed_for_signing` — passwords can only\nbe used in `view_gate`, not as a signing method.\n", "items": { "$ref": "#/components/schemas/SigningSessionAuthMethod" } }, "view_gate": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionAuthMethod" } ], "description": "Optional view gate. The signer must clear this authentication step before\nthe document is exposed. Same shape as a `signing_methods` entry\n(`{ type, target? }`). Supported types: `password`, `otp_email`, `otp_sms`,\n`eid`. When omitted, no view gate is enforced.\n" }, "signature_location": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionSignatureLocation" } ], "description": "Signature location for this participant. Used when `signature_position` is `inline`. If omitted in `inline` mode, the signature is invisible but still digitally signed." } }, "required": [ "name", "deliveries" ] }, "SigningSessionParticipantData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88211" }, "status": { "$ref": "#/components/schemas/SigningSessionParticipantStatus" }, "status_changed_at": { "type": "string", "format": "date-time", "description": "When the participant status last changed." }, "decline_reason": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Reason given when the participant declined.", "example": "Terms are not acceptable" }, "name": { "type": "string", "example": "John Doe" }, "external_id": { "anyOf": [ { "$ref": "#/components/schemas/SigningSessionParticipantExternalId" }, { "type": "null" } ] }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" }, "signing_order": { "type": "integer", "minimum": 0, "default": 0, "description": "Participants sign in ascending order from 0 to N. Participants sharing the same value sign in parallel.", "example": 0 }, "invitations": { "type": "array", "minItems": 1, "description": "Optional list of invitations for this participant.", "items": { "$ref": "#/components/schemas/SigningSessionParticipantInvitationData" } }, "signing_methods": { "type": "array", "minItems": 1, "description": "List of allowed signature methods for this participant.", "items": { "$ref": "#/components/schemas/SigningSessionAuthMethod" } }, "view_gate": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionAuthMethod" } ], "description": "View gate configuration, if one was set at create/update time.\n\nFor `type: \"password\"`, `target` is **not** returned on subsequent reads.\nThe single exception: when a request creates or rotates a password gate\nwithout supplying a `target` (i.e. the server generates one —\n`view_gate: { type: \"password\" }`), the response to **that one request**\ncarries the generated plaintext as `view_gate.target`. You must capture it\non the originating response and deliver it to the signer through a separate\nchannel; it is not retrievable later.\n\nFor `type: \"eid\"`, `target` (when set) reflects the pinned provider key.\nFor `type: \"otp_email\"` / `\"otp_sms\"`, `target` is always omitted (signer-\nentered at challenge time).\n" } }, "required": [ "id", "status", "status_changed_at", "name", "external_id" ] }, "SigningSessionParticipantInvitationTimeline": { "type": "object", "additionalProperties": false, "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the invitation was created.", "example": "2026-06-30T11:04:45.331Z" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invitation was sent, or null if not yet sent.", "example": null }, "opened_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recipient first opened the signing link, or null if not yet opened.", "example": null }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invitation was revoked, or null if still active.", "example": null } }, "required": [ "created_at", "sent_at", "opened_at", "revoked_at" ] }, "SigningSessionParticipantInvitationData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88311" }, "signing_url": { "type": "string", "format": "uri", "description": "URL to open the signing flow for this invitation. Present only for manual delivery, when you share the link yourself. Omitted for email or SMS, which Docue delivers.\n", "example": "https://sign.docue.com/s/#access-code" }, "delivery": { "$ref": "#/components/schemas/SigningSessionParticipantInvitation" }, "timeline": { "$ref": "#/components/schemas/SigningSessionParticipantInvitationTimeline" } }, "required": [ "id", "delivery", "timeline" ] }, "SigningSessionParticipantInvitationCreate": { "allOf": [ { "$ref": "#/components/schemas/SigningSessionParticipantInvitation" } ], "description": "Creates a new invitation for a participant. Manual delivery is allowed while the session is pending or started; you share the signing URL. Email or SMS delivery requires a started session.\n" }, "SigningSessionParticipantInvitation": { "type": "object", "additionalProperties": false, "description": "Invitation delivery channel. Manual means you share the signing URL; Docue does not send email or SMS. Email and SMS require a target.\n", "properties": { "type": { "type": "string", "enum": [ "email", "sms", "manual" ], "example": "email" }, "target": { "type": [ "string", "null" ], "description": "Email address or E.164 phone number. Unused for manual.", "example": "john.doe@example.org" }, "message": { "type": "string", "maxLength": 500, "description": "Optional short note shown with the signing link. Not the full email or SMS body — the surrounding template is fixed.\n", "example": "Please sign by Friday." } }, "required": [ "type" ] }, "SigningSessionAuthMethod": { "type": "object", "additionalProperties": false, "description": "An authentication method allowed for this participant. Used both for the\nsign-time methods list (`signing_methods`) and for the optional view gate\n(`view_gate`). Multi-value \"OR\" semantics are expressed at the list level\n(`signing_methods`, `allowed_signing_methods`), not within a single entry.\n\nPer-type `target` semantics:\n\n- `eid`: target is a specific provider id from the workspace's provider\n catalog (e.g. `fi_nordea`, `fi_op`, `se_bankid`). Country-scoped providers\n are prefixed with their ISO 3166-1 alpha-2 country code; cross-border\n providers (e.g., Smart-ID) are unprefixed. Omitted = any provider\n available to the participant is allowed.\n- `password`: target is the accepted password string. Only valid in\n `view_gate` (passwords are not a valid signing method); if omitted, the\n server generates a password and returns the plaintext once in the\n create/update response. Plaintext is not persisted or retrievable after that.\n- `otp_email` / `otp_sms`: target is optional — pre-fills the signer's\n email or phone at challenge time; the signer can edit before submitting.\n", "properties": { "type": { "type": "string", "enum": [ "password", "otp_email", "otp_sms", "eid" ], "description": "Authentication method type. `password` is only valid for `view_gate`.", "example": "eid" }, "target": { "type": "string", "minLength": 1, "description": "Optional target value for this type (see schema description).", "example": "fi_nordea" } }, "required": [ "type" ] }, "SigningSessionSignatureLocation": { "type": "object", "additionalProperties": false, "properties": { "file_index": { "type": "integer", "minimum": 0, "description": "Zero-based index of the file in the `files` array where the signature area is located.", "example": 0 }, "page": { "type": "integer", "minimum": 1, "description": "Number of the page where the signature area is located. It is 1-based.", "example": 1 }, "x": { "type": "number", "format": "float", "description": "X position of the signature area's location. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.", "example": 0.1 }, "y": { "type": "number", "format": "float", "description": "Y position of the signature area's location. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.", "example": 0.1 }, "width": { "type": "number", "format": "float", "description": "Width of the signature area. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.", "example": 0.1 }, "height": { "type": "number", "format": "float", "description": "Height of the signature area. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.", "example": 0.1 } }, "required": [ "file_index", "page", "x", "y", "width", "height" ] }, "SigningSessionWebhook": { "type": "object", "additionalProperties": false, "description": "A webhook endpoint that receives signing session events. See [Signing webhooks](/embed-api/signing/webhooks) for delivery behavior, event types, and signature validation.", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/signing" }, "secret": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Optional secret used to sign each delivery with HMAC-SHA256. The signature covers the send time (the `X-Webhook-Sent-At` header) and the exact raw request body. When configured, Docue sends the lowercase hexadecimal digest in the `X-Webhook-Signature` header. See [Verify webhook signatures](/embed-api/signing/webhooks#verify-webhook-signatures) for validation instructions and a complete example.", "example": "your-shared-secret" } }, "required": [ "url" ] }, "SigningSessionWebhookData": { "type": "object", "additionalProperties": false, "description": "Webhook endpoint configured on the session.", "properties": { "url": { "type": "string", "format": "uri" }, "secret_configured": { "type": "boolean", "description": "Whether a signing secret was set for this endpoint." } }, "required": [ "url", "secret_configured" ] }, "SigningWebhookEventType": { "type": "string", "description": "The signing event type. See [Signing webhook event types](/embed-api/signing/webhooks#event-types) for details about when each event is sent.", "enum": [ "com.docue.sign.v1.session.created", "com.docue.sign.v1.session.started", "com.docue.sign.v1.session.cancelled", "com.docue.sign.v1.session.discarded", "com.docue.sign.v1.session.completed", "com.docue.sign.v1.session.expired", "com.docue.sign.v1.session.renewed", "com.docue.sign.v1.participant.added", "com.docue.sign.v1.participant.removed", "com.docue.sign.v1.participant.signed", "com.docue.sign.v1.participant.declined", "com.docue.sign.v1.participant.excused", "com.docue.sign.v1.participant.reinstated", "com.docue.sign.v1.invitation.created", "com.docue.sign.v1.invitation.sent", "com.docue.sign.v1.invitation.resent", "com.docue.sign.v1.invitation.opened", "com.docue.sign.v1.invitation.revoked" ], "example": "com.docue.sign.v1.participant.signed" }, "SigningWebhookCall": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/signing" }, "status": { "type": "string", "enum": [ "pending", "delivered", "exhausted" ], "example": "delivered" }, "event": { "type": "object", "additionalProperties": false, "description": "The signing event associated with this delivery attempt. Your webhook receives this object nested under event.\n", "properties": { "payload": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/SigningWebhookEventType" }, "id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "timestamp" ] } }, "required": [ "payload", "meta" ], "example": { "payload": { "workspace": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88001" }, "session": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "external_id": "deal-42", "status": "started", "status_changed_at": "2026-02-12T10:30:00Z" }, "participant": { "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211", "external_id": "user-123", "session_id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd", "status": "signed", "status_changed_at": "2026-02-12T10:31:00Z", "decline_reason": null } }, "meta": { "type": "com.docue.sign.v1.participant.signed", "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88411", "timestamp": "2026-02-12T10:31:00Z" } } }, "attempt": { "type": "integer", "minimum": 0, "example": 1 }, "retry_after": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "last_error": { "type": [ "string", "null" ], "example": null } }, "required": [ "id", "url", "status", "event", "attempt", "retry_after", "last_error" ] }, "SigningAuditRecord": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "format": "uuid", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88401" }, "actor": { "type": "string", "enum": [ "system", "integrator", "sender-ui", "participant" ], "example": "integrator" }, "actor_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Workspace id for an integrator, participant id for a participant, sender UI id for sender-ui. Null when the actor is the system.\n", "example": "0196ae5b-2e9d-729f-aba5-fa4db6f88001" }, "type": { "type": "string", "example": "session.created" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-02-12T10:30:00Z" }, "client": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Client that triggered the record, or null when unknown.", "properties": { "ip": { "type": "string" }, "user_agent": { "type": "string", "maxLength": 1024, "example": "Mozilla/5.0" } }, "required": [ "ip", "user_agent" ] } }, "required": [ "id", "actor", "actor_id", "type", "timestamp" ] }, "WorkspaceData": { "$ref": "#/components/schemas/Api.Workspace.Data.WorkspaceData.WorkspaceData" }, "ContractState": { "type": "object", "properties": { "data": { "type": "object", "properties": { "state": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "finalized" ], "description": "If document is finalized, it cannot be edited." }, "document_name": { "type": "string", "description": "Name of the document. End-users can edit this. This is not visible on the document itself." }, "jurisdiction": { "type": "string", "description": "Jurisdiction of the agreement.", "example": "FI" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages in which the document is drafted. It usually contains just one.", "example": [ "en-GB" ] }, "value": { "type": "object", "description": "Values filled in to the form. The schema varies in every template. See [this](/embed-api/legal-engine/document-state#update-document-field-values) for more information." }, "sections": { "type": "array", "items": { "type": "object" }, "description": "List of sections included in the document. It contains templates and custom sections added by end-users. The sections are presented in the same order as they appear in the document." }, "appearance": { "type": "object", "properties": { "logo": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false }, "content": { "type": [ "string", "null" ], "example": null, "description": "Data URI with base64 encoded JPG,PNG or SVG image." }, "scale": { "type": "number", "example": 50, "description": "Size of the logo, scale 20-100 where 20 is the smallest and 100 is the largest." } } }, "footer": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false }, "content": { "type": "string", "example": "" } } }, "heading1": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "20" }, "weight": { "type": "string", "example": "bold" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "heading2": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "13" }, "weight": { "type": "string", "example": "bold" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "heading3": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "12" }, "weight": { "type": "string", "example": "bold" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "heading4": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "11" }, "weight": { "type": "string", "example": "bold" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "heading5": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "11" }, "weight": { "type": "string", "example": "regular" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "heading6": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "11" }, "weight": { "type": "string", "example": "regular" }, "alignment": { "type": "string", "example": "left" }, "transform": { "type": "string", "example": "none" } } }, "paragraph": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "color": { "type": "string", "example": "#000000" }, "size": { "type": "string", "example": "11" }, "weight": { "type": "string", "example": "regular" }, "alignment": { "type": "string", "example": "justify" }, "transform": { "type": "string", "example": "none" } } }, "table": { "type": "object", "properties": { "family": { "type": "string", "example": "arial" }, "size": { "type": "string", "example": "11" }, "color": { "type": "string", "example": "#000000" }, "bgColor": { "type": "string", "example": "#ffffff" }, "headerBgColor": { "type": "string", "example": "#e7e5e4" }, "headerColor": { "type": "string", "example": "#000000" }, "borderColorEnabled": { "type": "boolean", "example": true }, "borderColor": { "type": "string", "example": "#ffffff" }, "alternatingRowBgColorEnabled": { "type": "boolean", "example": true }, "alternatingRowBgColor": { "type": "string", "example": "#fafaf9" } } } } } }, "description": "Contract current state" }, "signees": { "type": "array", "description": "List of signees found from the document.", "items": { "properties": { "_type": { "type": "string", "const": "signature" }, "id": { "type": "string", "format": "uuid", "description": "Unique ID for the signature." }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "job_title": { "type": "string" }, "company_name": { "type": "string" }, "fieldset_name": { "type": "string", "description": "Name of the fieldset from which this signee originates." }, "page": { "type": "integer", "description": "Number of the page where the signature area of this signee is located. It is 1-based." }, "x": { "type": "number", "format": "float", "description": "X position of the signature area's location. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.", "example": 0.1 }, "y": { "type": "number", "format": "float", "description": "Y position of the signature area's location. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.", "example": 0.1 }, "width": { "type": "number", "format": "float", "description": "Width of the signature area. The value is % of the page's width. For e.g. 0.10 means it is 10% of the page width.", "example": 0.1 }, "height": { "type": "number", "format": "float", "description": "Height of the signature area. The value is % of the page's height. For e.g. 0.10 means it is 10% of the page height.", "example": 0.1 } }, "required": [ "id", "first_name", "last_name", "fieldset_name", "page", "x", "y", "width", "height" ] } } } } } }, "ErrorResponse": { "type": "object", "description": "Standard error response payload.", "properties": { "data": { "type": "null", "description": "Always null for error responses." }, "meta": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "code", "text" ] }, "error": { "type": "object", "properties": { "text": { "type": "string" }, "details": { "type": "object", "description": "Validation details, when available, as a map of what failed to a message or a list of messages.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "text" ] } }, "required": [ "status", "error" ] } }, "required": [ "data", "meta" ] }, "ContractPatchResponse": { "description": "Response of a processed contract patch.", "allOf": [ { "$ref": "#/components/schemas/ContractState" }, { "type": "object", "required": [ "meta" ], "properties": { "meta": { "type": "object", "required": [ "status", "failed_operations" ], "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "text": { "type": "string", "example": "OK" } } }, "failed_operations": { "type": "array", "description": "The operations that failed, in request order. Operations not listed were applied. Always empty when the request did not set `allow_partial` to `true`.", "items": { "$ref": "#/components/schemas/ContractPatchFailedOperation" } } } } } } ] }, "ContractPatchFailedOperation": { "type": "object", "description": "A patch operation that failed and left no changes behind.", "required": [ "index", "path", "error" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Zero-based position of the operation in the request's `operations` array.", "example": 1 }, "path": { "type": "string", "description": "The `path` of the operation, as sent in the request.", "example": "/value/basic/title" }, "error": { "type": "object", "description": "Why the operation failed.", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "enum": [ "invalid_operation", "operation_failed" ], "description": "Machine-readable reason. `invalid_operation` means the operation failed validation, for example a path that cannot be patched or a value of the wrong type. `operation_failed` means it could not be applied to the state.\n", "example": "invalid_operation" }, "message": { "type": "string", "description": "Human-readable reason.", "example": "Operation \"replace\" at \"/value/basic/title\" failed: invalid value" }, "details": { "description": "Validation details as a map of what failed to a message or a list of messages — for example `value` when the operation's `value` does not match the field. An empty array when there are no details.\n", "oneOf": [ { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "type": "array", "maxItems": 0 } ], "example": { "value": "Invalid input: expected object, received string" } } } } } }, "TemplateData": { "$ref": "#/components/schemas/App.Data.Template.TemplateData.TemplateData" }, "TemplateCollectionData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "example": "01965c7e-dc1e-7292-8199-8184041c1204" }, "title": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "_type": "translatable", "en-GB": "Employment and HR", "fi": "Työsuhde ja HR" } }, "_data_type": { "type": "string", "description": "Internal data type identifier returned by the API serializer.", "example": "app.http.api.template_collection.data.template_collection_data" } }, "required": [ "id", "title" ] }, "ResponseMeta": { "type": "object", "properties": { "status": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "text": { "type": "string", "example": "OK" } }, "required": [ "code", "text" ] }, "pagination": { "type": "object", "properties": { "items": { "type": "integer", "minimum": 0, "description": "Number of items in the current page.", "example": 15 }, "total": { "type": "integer", "minimum": 0, "description": "Total number of items across all pages.", "example": 51 }, "has_pages": { "type": "boolean", "description": "Whether there are multiple pages.", "example": true }, "is_first": { "type": "boolean", "description": "Whether the current page is the first page.", "example": true }, "pointer": { "type": "object", "description": "Page navigation pointers.", "properties": { "previous": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Previous page number, or null if on the first page.", "example": null }, "current": { "type": "integer", "minimum": 1, "description": "Current page number.", "example": 1 }, "next": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Next page number, or null if on the last page.", "example": 2 } }, "required": [ "previous", "current", "next" ] } }, "required": [ "items", "total", "has_pages", "is_first", "pointer" ] } }, "required": [ "status", "pagination" ] }, "Api.Workspace.Data.WorkspaceData.WorkspaceData": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "App.Data.Template.TemplateData.TemplateData": { "additionalProperties": false, "properties": { "collections": { "items": { "$ref": "#/components/schemas/App.Data.Template.TemplateCollectionData.TemplateCollectionData" }, "type": "array" }, "created_at": { "type": "string" }, "default_document_name": { "additionalProperties": { "type": "string" }, "type": "object" }, "description": { "additionalProperties": { "type": "string" }, "type": "object" }, "id": { "type": "string" }, "jurisdictions": { "items": { "$ref": "#/components/schemas/App.Data.Template.JurisdictionData.JurisdictionData" }, "type": "array" }, "languages": { "items": { "$ref": "#/components/schemas/App.Data.Template.LanguageData.LanguageData" }, "type": "array" }, "short_description": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": { "additionalProperties": { "type": "string" }, "type": "object" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "short_description", "description", "default_document_name", "created_at", "updated_at" ], "type": "object" }, "App.Data.Template.TemplateCollectionData.TemplateCollectionData": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "templates": { "items": { "$ref": "#/components/schemas/App.Data.Template.TemplateData.TemplateData" }, "type": "array" }, "title": { "additionalProperties": { "type": "string" }, "type": "object" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "created_at", "updated_at" ], "type": "object" }, "App.Data.Template.JurisdictionData.JurisdictionData": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "code" ], "type": "object" }, "App.Data.Template.LanguageData.LanguageData": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "code" ], "type": "object" }, "App.Enums.HttpMethod": { "const": "GET", "type": "string" }, "App.Payload.Primitives.HandlerPayload.HandlerPayload": { "additionalProperties": false, "properties": { "method": { "$ref": "#/components/schemas/App.Enums.HttpMethod" }, "url": { "type": "string" } }, "required": [ "url", "method" ], "type": "object" }, "App.Payload.Primitives.HandlersPayload.HandlersPayload": { "additionalProperties": false, "properties": { "cancel_handler": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlerPayload.HandlerPayload" }, "delete_handler": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlerPayload.HandlerPayload" }, "error_handler": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlerPayload.HandlerPayload" }, "success_handler": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlerPayload.HandlerPayload" } }, "required": [ "success_handler", "cancel_handler", "delete_handler", "error_handler" ], "type": "object" }, "App.Enums.UiLanguage": { "enum": [ "en-GB", "fi", "de", "pl", "sv" ], "type": "string" }, "Api.BrowserSession.Payload.CreateBrowserSessionPayload.CreateBrowserSessionPayload": { "additionalProperties": false, "properties": { "handlers": { "$ref": "#/components/schemas/App.Payload.Primitives.HandlersPayload.HandlersPayload" }, "ui_language": { "$ref": "#/components/schemas/App.Enums.UiLanguage" } }, "required": [ "handlers" ], "type": "object" }, "Api.BrowserSession.Data.BrowserSessionCreatedData.BrowserSessionCreatedData": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url" ], "type": "object" }, "App.Data.BrowserSession.BrowserSessionStateData.BrowserSessionStateData": { "additionalProperties": false, "properties": { "document_name": { "type": "string" }, "languages": { "items": { "type": "string" }, "type": "array" }, "template_id": { "type": "string" } }, "required": [ "template_id", "languages", "document_name" ], "type": "object" }, "App.Enums.BrowserSessionStatus": { "enum": [ "pending", "completed", "deleted" ], "type": "string" }, "Api.BrowserSession.Data.BrowserSessionData.BrowserSessionData": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "anyOf": [ { "$ref": "#/components/schemas/App.Data.BrowserSession.BrowserSessionStateData.BrowserSessionStateData" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/App.Enums.BrowserSessionStatus" } }, "required": [ "id", "status", "state" ], "type": "object" }, "Api.BuilderSession.Payload.ContractPayload.ContractPayload": { "additionalProperties": false, "properties": { "document_name": { "type": "string" }, "languages": { "items": { "type": "string" }, "type": "array" }, "template_id": { "type": "string" } }, "required": [ "template_id", "document_name", "languages" ], "type": "object" }, "App.Payload.Primitives.ParticipantPayload.ParticipantPayload": { "additionalProperties": false, "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "external_id": { "type": "string" } }, "required": [], "type": "object" }, "App.Data.Primitives.ParticipantData.ParticipantData": { "additionalProperties": false, "properties": { "display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "_data_type": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "email", "display_name", "external_id" ], "type": "object" }, "Api.BuilderSession.Data.BuilderSessionCreatedData.BuilderSessionCreatedData": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "participant": { "$ref": "#/components/schemas/App.Data.Primitives.ParticipantData.ParticipantData" }, "url": { "type": "string" } }, "required": [ "id", "url", "participant" ], "type": "object" }, "App.Enums.BuilderSessionStatus": { "enum": [ "pending", "completed", "deleted" ], "type": "string" }, "Api.BuilderSession.Participant.Data.ParticipantAuthenticatedData.ParticipantAuthenticatedData": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "participant": { "$ref": "#/components/schemas/App.Data.Primitives.ParticipantData.ParticipantData" }, "url": { "type": "string" } }, "required": [ "id", "url", "participant" ], "type": "object" } } }, "tags": [ { "name": "Workspaces", "description": "Endpoint for fetching information about the authenticated workspace. It can be used to test if the API authentication works." }, { "name": "Templates", "description": "Fetch a list of all available templates. Use this if you want to create a fully customized UI for selecting templates. If you prefer to use our ready-made UI, you can use the Template Browser instead." }, { "name": "Template browser", "description": "Hosted UI for end users to select the appropriate template. Use this if you want to take advantage of our UI." }, { "name": "Builder", "description": "Hosted UI for end users to draft their document." }, { "name": "Signing", "description": "Start a signing session by providing files and participants.\n\nSee [Sign Engine](/embed-api/signing) for integration concepts, invitations,\nand retrieving signed documents. See\n[Signing webhooks](/embed-api/signing/webhooks) for event types.\n" } ] }