{ "openapi": "3.0.3", "servers": [ { "url": "https://sign.sproof.com/api/v1", "description": "Default Server" } ], "info": { "description": "**Secure digital signatures made easy.** Developed by **sproof** in Salzburg, Austria, this API allows you to integrate legally binding signature workflows directly into your application. \n\nLearn more about our mission at [sproof.com](https://sproof.com).\n\n### 🎓 sproof Academy\nAccelerate your integration with our [Academy modules](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1178664961/sproof+Sign+Quick+Start+Guide+API). These guides cover essential use cases and implementation steps:\n\n* **[Collecting Signatures](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1178107908/sproof+Sign+Collecting+Signatures+API):** Learn how to send documents, handle real-time status updates via callbacks, and retrieve final signed files.\n* **[Signature Workflows](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1178075162/sproof+Sign+Collecting+Signatures+incl.+Workflow+API):** Streamline processes by merging dynamic documents with pre-configured workflows. Covers workflow creation, recipient invitations, and automated tracking.\n* **[Embedded Signing Widget](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1178697759/sproof+Widget+Embed+Signing+API):** Integrate the signing experience directly into your own website or application for a seamless user journey.\n\n### 🔗 Quick Links\n* **Base URL:** `https://sign.sproof.com/api/v1/`\n* **Web App:** [sign.sproof.com](https://sign.sproof.com/)\n* **Developer Support:** [Join our Discord Server](https://discord.gg/HjWe6MUMJ4)\n\n\n# Using the member ID\nThe member ID can be used to open the document directly within the sproof sign editor after creating a [signature request](#operation/createSignatureRequest). It can be found in the response object after a successful call.\n\nTo open the editor the member ID has to be appended to the URL as follows: `https://sign.sproof.com/#/editor/{memberId}`\n\n\n### Javascript code sample:\n\n```\nconst requestBody = {\n \"token\": \"XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n \"data\": base64File,\n \"callbackUrl\": \"https://webhook.site/abc\",\n \"fileName\": \"important_contract\",\n \"email\": \"max.mustermann@sproof.com\",\n \"firstName\": \"Max\",\n \"lastName\": \"Mustermann\",\n};\nconst requestOptions = {\n 'method': 'post',\n 'headers': { 'Content-Type': 'application/json' },\n 'body': JSON.stringify(requestBody),\n};\nconst response = await fetch(\"https://sign.sproof.com/api/v1/documents\", requestOptions);\nconst responseJson = await response.json();\n\n//open the document in the sproof sign editor\nwindow.open(\"https://sign.sproof.com/#/editor/\" + responseJson.member.id);\n```\n\n\n\n# Embed sproof sign in an iframe\n**Warning! This only works for qualified electronic signatures, as they provide a second factor for authentication!**\nThe [Create signature request](#operation/createSignatureRequest) call can be used to create a signature request. By default, the sproof sign backend sends out emails to all signers. \n\n - For this use case we set the `doNotSendEmail` property in the signer object of the request to `true`, to avoid sending extra emails to the signer.\n - set the `signatureTypes` to `qualified`, i.e. requires a signature with qualified electronic signature.\n - Parse the returned JSON object to get the ID of the created document for the respective signer.\n - Display an iframe and set the URL to https://sign.sproof.com/#/editor/{ID}\n - Optionally set the parameters `returnUrl` and `returnBtnText` to direct the signer to the next document after signing or to return them to a custom page of your application (see image below)\n\n\n\n# Text Placeholders Overview\nText placeholders are used in documents (e.g., Microsoft Word DOCX, Google Docs, PDF) to define signature positions or form fields. These placeholders are recognized and processed during the upload.\n\n## Key Features\n- **Customizable Appearance:** You can change the color of text placeholders to make them invisible within the document.\n- **Size Adjustment:** Prefixing a text placeholder with underscores `_` allows you to adjust its size.\n\n## Constraints\n- **Minimum Font Size:** Text placeholders must have a font size of at least 4pt to be recognized.\n- **Single Line Requirement:** Placeholders must not contain line breaks.\n\n## Signature Placeholders\nSignature placeholders specify where a document should be signed by designated individuals. The format for a signature placeholder is as follows:\n\n```\n{sproof{first_name, last_name, email_address, signing_order, [optional] doNotSendEmail}sproof}\n```\n\n### Field Descriptions\n1. **first_name**: \n - **Description**: The first name of the recipient.\n - **Example**: `John`\n - **Required**: Yes\n\n2. **last_name**: \n - **Description**: The last name of the recipient.\n - **Example**: `Doe`\n - **Required**: Yes\n\n3. **email_address**: \n - **Description**: The email address of the recipient. This address will be used to invite the person to sign the document.\n - **Example**: `john.doe@example.com`\n - **Required**: Yes\n\n4. **signing_order**: \n - **Description**: Specifies the order in which the recipients will sign the document. Recipients with the same order value will be invited to sign simultaneously. If you want the document to be signed sequentially, assign incremental values (e.g., `1`, `2`, `3`, etc.).\n - **Example**: `1`\n - **Required**: Yes\n\n5. **doNotSendEmail** (Optional): \n - **Description**: A flag that indicates whether the recipient should receive an email invitation to sign the document. If set to `true`, the signatory will not receive an email.\n - **Example**: `true`\n - **Default Value**: `false`\n - **Required**: No\n\n### Example\n```\n{sproof{John, Doe, john.doe@example.com, 1, true}sproof}\n```\n\n### Usage\n**To activate signature placeholders, set the `usePlaceholders` flag to `true` in the [Create Signature Request](#operation/createSignatureRequest) API call.**\n\nWhen a document containing signature placeholders is opened in the sproof sign interface, a dialog opens showing the specified recipients. Recipients can then be invited to the document with one click or edited further in the editor. The `signing_order` parameter controls whether all signatories are invited simultaneously or sequentially.\n\n![Signature Placeholder Example](../img/placeholder_popup.png)\n\n## Form Field Placeholders\nForm field placeholders define where users can enter information such as text, dates, or checkboxes. The format for a form field placeholder is as follows:\n\n```\n{sp{type, [optional] label, [optional] content, [optional] recipient_email, [optional] required}sp}\n```\n\n### Field Descriptions\n1. **type**: \n - **Description**: Specifies the type of form field to be created.\n - **Available Options**:\n - `TB` - TextBox\n - `IB` - IBAN Field\n - `DB` - Date Box\n - `CB` - Checkbox - **The checkbox requires only a single underscore (_) and its size depends on the font size of the underscore**\n - **Example**: `TB`\n - **Required**: Yes\n\n2. **label** (Optional): \n - **Description**: Defines the label that will be displayed for the form field. This provides a visual cue to the user about what information is expected.\n - **Example**: `Name`\n - **Required**: No\n\n3. **content** (Optional): \n - **Description**: Prefills the form field with the specified content. This is useful for providing default values or examples.\n - **Example**: `John Doe`\n - **Required**: No\n\n4. **recipient_email** (Optional): \n - **Description**: The email address of the recipient assigned to the form field. If not provided, the field is unassigned and can be filled out by anyone with access to the document.\n - **Example**: `john.doe@example.com`\n - **Required**: No\n\n5. **required** (Optional): \n - **Description**: Indicates whether the form field is mandatory for the user to fill out. If set to `true`, the form cannot be submitted until the field is completed.\n - **Example**: `true`\n - **Default Value**: `false`\n - **Required**: No\n\n### Example\n```\n{sp{TB, Name, John Doe, john.doe@example.com, true}sp}\n```\n### Usage\nTo include form field placeholders, simply insert them into your document and configure the fields as required.\n\n## Example Files\nDownload example files to see how placeholders are implemented in practice:\n- [Signature Placeholder Example File (German)](files/Platzhalter-Demo.docx)\n- [Signature Placeholder Example File (English)](files/Placeholder-Demo.docx)\n- [Formfield Example File (English)](files/FormField-Demo.docx)\n\n# Authentication\n\nsproof sign uses an **api key** for authentication. It can be obtained by purchasing an enterprise plan. The key can be found in the settings page of the administrator profile (see image below).\n\n\n\n# Changelog\n## 26/05/2026 - version 3.0.4\n\n- **Added**: [Create a new Ident](/#tag/idents/POST/ident) now supports Shufti as an auto-ident provider. Use the new `selectedAutoIdentProvider` request property with `fidentity` (default) or `shufti` when `identTypes` includes `autoident`.\n\n\n**[View Full Changelog](https://sign.sproof.com/api/v1/changelog)**\n", "version": "3.0.4", "title": "sign.sproof.com API Documentation", "contact": { "name": "API Support", "email": "support@sproof.com", "url": "https://sproof.com" }, "x-logo": { "url": "./img/sproof_logo.png", "altText": "sproof sign, the easiest way to sign documents" } }, "tags": [ { "name": "Signatures", "description": "Signature handling" }, { "name": "Signatures with workflows", "description": "Invite recipients with workflow" }, { "name": "Documents", "description": "Document operations" }, { "name": "Members", "description": "Plan member management" }, { "name": "Idents", "description": "Identity verification management for Relying Parties" }, { "name": "Fastlane", "description": "This section outlines the necessary API requests for managing Fastlane profiles. \n\nThe Fastlane is a streamlined user interface designed to accelerate the process of collecting signatures and other required data. It provides a guided, step-by-step flow, ensuring efficiency and ease of use for your recipients. Fastlane profiles allow for the customization of this process, enabling you to tailor the signing flow according to your specific needs.\n\nAll created Fastlane profiles are accessible to every member of your plan within the web application, making it simple to manage and use across your organization.\n\nFor more details on how Fastlane works, visit the [sproof Academy](https://sproof.atlassian.net/wiki/spaces/Academy/pages/1178402828/sproof+Fastlane+Collecting+Signatures+API).\n" } ], "x-tagGroups": [ { "name": "General", "tags": [ "Documents", "Envelopes", "Signatures", "Signatures with workflows", "Stack", "Fastlane", "Idents" ] }, { "name": "Member Management", "tags": [ "Members" ] } ], "components": { "schemas": { "NoContentResponse": { "type": "object", "description": "No content response for 204 status" }, "IdentResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "attributes": { "type": "array", "items": { "type": "string", "enum": [ "given_name", "family_name", "birthdate", "main_address", "nationality", "age_over_14", "age_over_16", "age_over_18", "age_over_21", "signature_image", "passport_data", "passport_portrait", "selfie_image", "id_document_image", "id_document_pdf" ] } }, "config": { "type": "object", "nullable": true, "properties": { "steps": { "type": "object", "properties": { "welcome": { "$ref": "#/components/schemas/StepConfigWithContent" }, "end": { "$ref": "#/components/schemas/StepConfigWithContent" } } } } }, "identTypes": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "eid", "autoident", "eudi" ] } }, "callback": { "type": "string", "nullable": true }, "returnUrl": { "type": "string", "nullable": true }, "returnUrlLabel": { "type": "string", "nullable": true }, "brandingDomain": { "type": "string", "nullable": true }, "selectedNationalProvider": { "$ref": "#/components/schemas/NationalProviderEnum" }, "selectedAutoIdentProvider": { "$ref": "#/components/schemas/AutoIdentProviderEnum" }, "canChangeNationalProvider": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } }, "additionalChecks": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/IdentData" }, "status": { "$ref": "#/components/schemas/StatusEnum" }, "errorCode": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "additionalChecks_data": { "nullable": true }, "additionalChecks_error": { "nullable": true }, "language": { "$ref": "#/components/schemas/LanguageEnum" }, "isDemo": { "type": "boolean", "default": false }, "completedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deliveryMethod": { "type": "string", "enum": [ "email", "sms", "qr" ] }, "identifier": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "id", "attributes", "config", "identTypes", "callback", "returnUrl", "returnUrlLabel", "brandingDomain", "metadata", "additionalChecks", "data", "status", "errorCode", "errorMessage", "language", "completedAt", "createdAt", "updatedAt", "deliveryMethod", "identifier", "description" ] }, "LanguageEnum": { "type": "string", "enum": [ "en", "de", "fr", "it", "es", "nl", "pt" ], "default": "en", "description": "Preferred language for UI and provider communication (ISO 639-1 code). Defaults to English" }, "StatusEnum": { "type": "string", "enum": [ "pending", "error", "success" ] }, "IdentData": { "type": "object", "nullable": true, "properties": { "given_name": { "type": "string", "nullable": true, "description": "First/given name of the End User" }, "family_name": { "type": "string", "nullable": true, "description": "Last/family name of the End User" }, "birthdate": { "type": "string", "nullable": true, "description": "Date of birth" }, "main_address": { "type": "object", "nullable": true, "properties": { "street_address": { "type": "string", "nullable": true, "description": "Street name (without building number)" }, "building_number": { "type": "string", "nullable": true, "description": "Building number or identifier on the street" }, "unit": { "type": "string", "nullable": true, "description": "Apartment, suite, staircase, door, or other secondary unit identifier" }, "sub_premise": { "type": "string", "nullable": true, "description": "Additional address details such as c/o, floor, or building name" }, "postal_code": { "type": "string", "nullable": true, "description": "Postal or ZIP code" }, "city": { "type": "string", "nullable": true, "description": "City or municipality" }, "district": { "type": "string", "nullable": true, "description": "District, borough, neighborhood, or locality" }, "region": { "type": "string", "nullable": true, "description": "Region, county, or major administrative area" }, "state_province": { "type": "string", "nullable": true, "description": "State or province distinct from city/region" }, "country": { "type": "string", "nullable": true, "description": "Country name" }, "country_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 or alpha-3 country code" }, "sort_code": { "type": "string", "nullable": true, "description": "Local administrative code used for sorting (e.g., Austrian Gemeindekennziffer)" } }, "description": "Primary address of the End User" }, "nationality": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "ISO 3166-1 alpha-3 country codes (e.g., [\"AUT\", \"DEU\"])" }, "age_over_14": { "type": "string", "nullable": true, "description": "\"true\" if End User is over 14, \"false\" otherwise" }, "age_over_16": { "type": "string", "nullable": true, "description": "\"true\" if End User is over 16, \"false\" otherwise" }, "age_over_18": { "type": "string", "nullable": true, "description": "\"true\" if End User is over 18, \"false\" otherwise" }, "age_over_21": { "type": "string", "nullable": true, "description": "\"true\" if End User is over 21, \"false\" otherwise" }, "signature_image": { "type": "string", "nullable": true, "description": "URI path to signature image - use media download endpoint" }, "passport_data": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "description": "Document type" }, "number": { "type": "string", "nullable": true, "description": "Document number" }, "valid_from": { "type": "string", "nullable": true, "description": "Date from which the document is valid" }, "valid_until": { "type": "string", "nullable": true, "description": "Date until which the document is valid" }, "issuing_authority": { "type": "string", "nullable": true, "description": "Issuing authority" }, "issuing_country": { "type": "string", "nullable": true, "description": "Country that issued the document (ISO 3166-1 alpha-3 code)" }, "issuing_date": { "type": "string", "nullable": true, "description": "Date when document was issued" }, "expiry_date": { "type": "string", "nullable": true, "description": "Date when document expires" }, "first_name": { "type": "string", "nullable": true, "description": "First name of the document holder" }, "last_name": { "type": "string", "nullable": true, "description": "Last name of the document holder" }, "birth_date": { "type": "string", "nullable": true, "description": "Date of birth of the document holder" }, "birth_place": { "type": "string", "nullable": true, "description": "Place of birth of the document holder" }, "gender": { "type": "string", "nullable": true, "description": "Gender of the document holder" }, "height": { "type": "string", "nullable": true, "description": "Height of the document holder in cm" } }, "description": "Identity document data (passport, ID card) with type, number, dates, issuing country and authority" }, "passport_portrait": { "type": "string", "nullable": true, "description": "URI path to passport photo - use media download endpoint" }, "selfie_image": { "type": "string", "nullable": true, "description": "URI path to selfie from liveness check - use media download endpoint" }, "id_document_image": { "type": "string", "nullable": true, "description": "URI path to ID document scan (front only, or front+back merged side-by-side for Shufti) - use media download endpoint" }, "id_document_pdf": { "type": "string", "nullable": true, "description": "URI path to ID document PDF report - use media download endpoint" } } }, "AutoIdentProviderEnum": { "type": "string", "enum": [ "fidentity", "shufti" ], "default": "fidentity", "description": "Vendor for `autoident`: Fidentity (default) or Shufti" }, "NationalProviderEnum": { "type": "string", "nullable": true, "enum": [ "idaustria-ident" ], "description": "Pre-selected national eID provider (e.g., idaustria-ident)" }, "StepConfigWithContent": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "enabled" ] }, "Uuid": { "type": "string", "format": "uuid" }, "IdentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdentResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "lastPage": { "type": "number" }, "perPage": { "type": "number" }, "currentPage": { "type": "number" }, "to": { "type": "number" } }, "required": [ "total", "lastPage", "perPage", "currentPage", "to" ] } }, "required": [ "data", "pagination" ] }, "CreateIdentResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "url": { "type": "string" } }, "required": [ "id", "url" ] }, "CreateIdentRequest": { "oneOf": [ { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "string", "enum": [ "given_name", "family_name", "birthdate", "main_address", "nationality", "age_over_14", "age_over_16", "age_over_18", "age_over_21", "signature_image", "passport_data", "passport_portrait", "selfie_image", "id_document_image", "id_document_pdf" ] }, "minItems": 1, "description": "Identity attributes requested by the Relying Party from the End User" }, "config": { "type": "object", "properties": { "steps": { "type": "object", "properties": { "welcome": { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, "end": { "allOf": [ { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, { "description": "Configuration for the end/success screen shown to the End User" } ] } } } }, "default": {}, "description": "UI flow configuration for the End User" }, "identTypes": { "type": "array", "items": { "type": "string", "enum": [ "eid", "autoident", "eudi" ] }, "minItems": 1, "description": "Available identification methods for the End User (eid, autoident, eudi)" }, "callback": { "type": "string", "nullable": true, "format": "uri", "default": null, "description": "Webhook URL to notify Relying Party when identification completes" }, "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect End User after successful identification" }, "returnUrlLabel": { "type": "string", "description": "Label text for the return URL button shown to End User" }, "brandingDomain": { "type": "string", "nullable": true, "default": null, "description": "Custom branding domain for white-label UI" }, "selectedNationalProvider": { "$ref": "#/components/schemas/NationalProviderEnum" }, "selectedAutoIdentProvider": { "$ref": "#/components/schemas/AutoIdentProviderEnum" }, "canChangeNationalProvider": { "type": "boolean", "default": true, "description": "Whether End User can change the pre-selected national provider" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "additionalChecks": { "$ref": "#/components/schemas/AdditionalChecks" }, "language": { "$ref": "#/components/schemas/LanguageEnum" }, "deliveryMethod": { "type": "string", "enum": [ "email" ], "description": "Send the ident invitation by email." }, "identifier": { "type": "string", "description": "Recipient email address for the invitation (e.g., test@example.com)." }, "description": { "type": "string", "nullable": true, "maxLength": 50, "description": "Optional description for the ident" } }, "required": [ "attributes", "identTypes", "deliveryMethod", "identifier" ], "description": "Ident creation with email delivery. `identifier` is the recipient email address.", "title": "email" }, { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "string", "enum": [ "given_name", "family_name", "birthdate", "main_address", "nationality", "age_over_14", "age_over_16", "age_over_18", "age_over_21", "signature_image", "passport_data", "passport_portrait", "selfie_image", "id_document_image", "id_document_pdf" ] }, "minItems": 1, "description": "Identity attributes requested by the Relying Party from the End User" }, "config": { "type": "object", "properties": { "steps": { "type": "object", "properties": { "welcome": { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, "end": { "allOf": [ { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, { "description": "Configuration for the end/success screen shown to the End User" } ] } } } }, "default": {}, "description": "UI flow configuration for the End User" }, "identTypes": { "type": "array", "items": { "type": "string", "enum": [ "eid", "autoident", "eudi" ] }, "minItems": 1, "description": "Available identification methods for the End User (eid, autoident, eudi)" }, "callback": { "type": "string", "nullable": true, "format": "uri", "default": null, "description": "Webhook URL to notify Relying Party when identification completes" }, "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect End User after successful identification" }, "returnUrlLabel": { "type": "string", "description": "Label text for the return URL button shown to End User" }, "brandingDomain": { "type": "string", "nullable": true, "default": null, "description": "Custom branding domain for white-label UI" }, "selectedNationalProvider": { "$ref": "#/components/schemas/NationalProviderEnum" }, "selectedAutoIdentProvider": { "$ref": "#/components/schemas/AutoIdentProviderEnum" }, "canChangeNationalProvider": { "type": "boolean", "default": true, "description": "Whether End User can change the pre-selected national provider" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "additionalChecks": { "$ref": "#/components/schemas/AdditionalChecks" }, "language": { "$ref": "#/components/schemas/LanguageEnum" }, "deliveryMethod": { "type": "string", "enum": [ "sms" ], "description": "Send the ident invitation by SMS." }, "identifier": { "type": "string", "description": "Recipient phone number for the SMS (+436761234567 format recommended)." }, "description": { "type": "string", "nullable": true, "maxLength": 50, "description": "Optional description for the ident" } }, "required": [ "attributes", "identTypes", "deliveryMethod", "identifier" ], "description": "Ident creation with SMS delivery. `identifier` is the recipient phone number.", "title": "sms" }, { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "string", "enum": [ "given_name", "family_name", "birthdate", "main_address", "nationality", "age_over_14", "age_over_16", "age_over_18", "age_over_21", "signature_image", "passport_data", "passport_portrait", "selfie_image", "id_document_image", "id_document_pdf" ] }, "minItems": 1, "description": "Identity attributes requested by the Relying Party from the End User" }, "config": { "type": "object", "properties": { "steps": { "type": "object", "properties": { "welcome": { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, "end": { "allOf": [ { "$ref": "#/components/schemas/ApiUserWelcomeEndStep" }, { "description": "Configuration for the end/success screen shown to the End User" } ] } } } }, "default": {}, "description": "UI flow configuration for the End User" }, "identTypes": { "type": "array", "items": { "type": "string", "enum": [ "eid", "autoident", "eudi" ] }, "minItems": 1, "description": "Available identification methods for the End User (eid, autoident, eudi)" }, "callback": { "type": "string", "nullable": true, "format": "uri", "default": null, "description": "Webhook URL to notify Relying Party when identification completes" }, "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect End User after successful identification" }, "returnUrlLabel": { "type": "string", "description": "Label text for the return URL button shown to End User" }, "brandingDomain": { "type": "string", "nullable": true, "default": null, "description": "Custom branding domain for white-label UI" }, "selectedNationalProvider": { "$ref": "#/components/schemas/NationalProviderEnum" }, "selectedAutoIdentProvider": { "$ref": "#/components/schemas/AutoIdentProviderEnum" }, "canChangeNationalProvider": { "type": "boolean", "default": true, "description": "Whether End User can change the pre-selected national provider" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "additionalChecks": { "$ref": "#/components/schemas/AdditionalChecks" }, "language": { "$ref": "#/components/schemas/LanguageEnum" }, "deliveryMethod": { "type": "string", "enum": [ "qr" ], "description": "No outbound invitation; you share the returned URL or a QR code yourself." }, "identifier": { "type": "string", "nullable": true, "description": "Optional label stored with the ident. If omitted or empty, defaults to ident-." }, "description": { "type": "string", "nullable": true, "maxLength": 50, "description": "Optional description for the ident" } }, "required": [ "attributes", "identTypes", "deliveryMethod" ], "description": "Ident creation with QR / self-serve link. `identifier` is optional; when omitted, a default label is generated server-side.", "title": "qr" } ], "discriminator": { "propertyName": "deliveryMethod" } }, "AdditionalChecks": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Additional verification checks to perform" }, "Metadata": { "type": "object", "additionalProperties": { "nullable": true }, "default": {}, "description": "Custom metadata attached to this ident transaction by Relying Party" }, "ApiUserWelcomeEndStep": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "title": { "type": "string", "nullable": true, "default": null }, "description": { "type": "string", "nullable": true, "default": null } }, "description": "Configuration for the welcome screen shown to the End User" }, "GetPlanMembersResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlanMembers" }, "pagination": { "$ref": "#/components/schemas/PlanMembersPagination" }, "all": { "type": "integer" }, "userPlus": { "type": "integer" }, "user": { "type": "integer" } }, "required": [ "data", "pagination", "all", "userPlus", "user" ] }, "PlanMembersPagination": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "lastPage": { "type": "integer" }, "perPage": { "type": "integer" }, "to": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "currentPage", "lastPage", "perPage", "to", "total" ] }, "PlanMembers": { "type": "array", "items": { "$ref": "#/components/schemas/PlanMember" } }, "PlanMember": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the member", "example": "max.mustermann@sproof.com" }, "firstName": { "type": "string", "description": "First name of the member" }, "lastName": { "type": "string", "description": "Last name of the member" }, "identification": { "$ref": "#/components/schemas/MemberIdentification" }, "blockedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date when the member was blocked" }, "entraBlocked": { "anyOf": [ { "type": "string", "enum": [ "userLimitReached" ] }, { "type": "string", "enum": [ "userPlusLimitReached" ] }, { "nullable": true } ], "description": "Reason for blocked (qualified or normal) member" }, "entraManaged": { "type": "boolean", "description": "Whether the member is managed by the Entra sync" }, "isPending": { "type": "boolean", "description": "If you create a new member without choosing to \"register\" the user, the member will be pending. This means that the user first have to create an account and login then accept the invitation to join the plan. If the user does not accept the invitation, the member will remain pending." }, "userPlus": { "type": "boolean", "description": "This is a boolean that indicates if the member is a qualified user. This means this member will have a userPlus license and is not currently blocked." }, "lastLoginAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Last login date of the member" } }, "required": [ "email", "firstName", "lastName", "identification", "isPending", "userPlus" ] }, "MemberIdentification": { "type": "object", "properties": { "identifiedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date when the member was identified" }, "identificationStarted": { "type": "boolean", "description": "Whether identification has started" }, "isIdentified": { "type": "boolean", "description": "Whether the member is identified" } }, "description": "Identification details, empty if userPlus is false" }, "DeletePlanMemberResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True if the member was successfully deleted" } }, "required": [ "success" ] }, "UpdatePlanMemberRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "Your api token, you can find it in the settings page of the administrator profile" }, "email": { "type": "string", "description": "Email address of the member to update", "example": "max.mustermann@sproof.com" }, "firstName": { "type": "string", "minLength": 1, "description": "Updated first name" }, "lastName": { "type": "string", "minLength": 1, "description": "Updated last name" }, "blocked": { "type": "boolean", "description": "If this is set to true, the member will be blocked starting with the date of this update request, and will not be able to use the plans resources." }, "userPlus": { "type": "boolean", "description": "If true, upgrade member to userPlus. If false, downgrades userPlus to user. Requires available userPlus counters for upgrades." } }, "required": [ "token", "email" ] }, "CreatePlanMemberRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "Your api token, you can find it in the settings page of the administrator profile" }, "email": { "type": "string", "description": "Email address of the new member", "example": "max.mustermann@sproof.com" }, "firstName": { "type": "string", "description": "First name of the new member" }, "lastName": { "type": "string", "description": "Last name of the new member" }, "register": { "type": "boolean", "default": false, "description": "If true, also create a user if one does not exist. An email will be sent out with a link to create a password for the account. Once the account is created, the user will be already added to the plan and will be able to login" }, "userPlus": { "type": "boolean", "default": false, "description": "If true, this user will have userPlus license, this will enable your user to identify with a qualified signature provider and sign documents with a qualified signature if required" }, "sendEmail": { "type": "boolean", "default": true, "description": "If true, send invite email. Use false for SSO use cases." } }, "required": [ "token", "email", "firstName", "lastName" ] }, "PrepareRecipientsWithWorkflowResponse": { "type": "object", "properties": { "editorUrl": { "type": "string", "format": "uri", "description": "The URL to open the draft document in the sproof sign editor and send out the invitations", "example": "https://sign.sproof.com/editor/0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3" }, "name": { "type": "string", "description": "The name of the document", "example": "Contract.pdf" } }, "required": [ "editorUrl", "name" ] }, "PrepareEnvelopeWithWorkflowRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "workflowId": { "type": "string", "minLength": 1, "description": "The **workflow memberId** (`documentMembers.id`) of the workflow to use. The workflow has to be created in the UI first. You can find this memberId in the workflow URL. The amount of recipient placeholders has to match the recipients you specify in the request body.", "example": "14e78eb0f4dedde5976f689b799b1c0c5be9ab10073658dcc70a5b0f8af6eec8081ec5" }, "callbackUrl": { "type": "string", "description": "URL to receive callbacks when signatures are added or document status changes after the invitation is sent", "example": "https://yourserver.com/callback" }, "returnUrl": { "type": "string", "default": "", "description": "URL to redirect the user to after signing is complete", "example": "https://yourserver.com/success" }, "returnBtnText": { "type": "string", "description": "The text of the return button after signing a document", "example": "Return to sproof" }, "inviteSuccessUrl": { "type": "string", "default": "", "description": "URL to redirect the user to after the invite is successfully sent. **Only applies to the prepare endpoints** (e.g. `/documents/prepare-recipients-with-workflow` and `/documents/prepare-recipients-with-workflow-envelope`). It is ignored by the invite endpoints that send invitations immediately.", "example": "https://yourserver.com/invite-success" }, "sender": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the sender", "example": "sender@sproof.com" }, "firstName": { "type": "string", "description": "First name of the sender", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the sender", "example": "Doe" } }, "required": [ "email", "firstName", "lastName" ], "description": "Information about the sender of the signature request. Must be a member of your plan." }, "dueDate": { "type": "string", "nullable": true, "description": "The date until which the document can be signed. This due date is displayed to the recipient in the invite email and is also visible in the document details section of the dashboard. It serves as a deadline for completing the signing process.", "example": "YYYY-MM-DD" }, "reminderInterval": { "type": "number", "nullable": true, "description": "Specifies the number of days between reminder emails. If provided, this overrides the reminder interval defined in the workflow.", "example": 7 }, "startSendingReminders": { "type": "string", "nullable": true, "description": "The date from which reminders should be sent out. The format is YYYY-MM-DD HH:mm.", "example": "YYYY-MM-DD HH:mm" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRecipient" }, "description": "Array of recipients to be invited to sign the document. Each recipient must match a placeholder in the workflow by placeholderText (to get the signature position) and by index (to get specific recipient settings like role, signingOrder, signatureTypes).", "example": [ { "email": "recipient@example.com", "firstName": "Jane", "lastName": "Smith", "phoneNumber": "+43123456789", "placeholderText": "{{signer1}}", "index": 1 } ] }, "folderName": { "type": "string", "minLength": 1, "description": "The envelope (folder) name that will be created.", "example": "HR onboarding - ACME Corp" }, "pdfs": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "description": "The name of the PDF file for this workflow document.", "example": "Employment Contract.pdf" }, "data": { "type": "string", "nullable": true, "description": "Base64 encoded PDF data for this workflow document.", "example": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." } }, "required": [ "fileName" ] }, "description": "One PDF per workflow document, in the same order as the workflow documents. Each item must include a fileName and base64 PDF data.", "example": [ { "fileName": "Contract.pdf", "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." }, { "fileName": "NDA.pdf", "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." } ] } }, "required": [ "token", "workflowId", "sender", "recipients", "folderName", "pdfs" ] }, "WorkflowRecipient": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the recipient", "example": "recipient@sproof.com" }, "firstName": { "type": "string", "description": "First name of the recipient", "example": "Jane" }, "lastName": { "type": "string", "description": "Last name of the recipient", "example": "Smith" }, "phoneNumber": { "type": "string", "nullable": true, "description": "Phone number of the recipient. Used for SMS notifications if enabled.", "example": "+43123456789" }, "placeholderText": { "type": "string", "nullable": true, "description": "Text placeholder identifier used to match this recipient to a signature position specified on the document.", "example": "{{signer1}}" }, "index": { "type": "integer", "minimum": 1, "description": "Index of the recipient placeholder in the workflow. The index starts at 1 and corresponds to the order of placeholders defined in the workflow.", "example": 1 } }, "required": [ "email", "firstName", "lastName" ] }, "InviteRecipientsWithWorkflowResponse": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "startSendingReminders": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when reminders start being sent (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "sendReminder": { "type": "boolean" }, "reminderSent": { "type": "boolean", "nullable": true }, "reminderInterval": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the document was created (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "callbackUrl": { "type": "string", "nullable": true }, "returnUrl": { "type": "string", "nullable": true }, "returnBtnText": { "type": "string", "nullable": true }, "inPersonSigning": { "type": "boolean", "nullable": true }, "signingRound": { "type": "number", "nullable": true }, "isTemplate": { "type": "boolean", "nullable": true }, "templateId": { "type": "string", "nullable": true }, "linkId": { "type": "string", "nullable": true }, "linkExpiresAt": { "type": "string", "nullable": true }, "derivedFromLink": { "type": "boolean", "nullable": true }, "state": { "type": "string", "nullable": true }, "complianceLevel": { "type": "string", "nullable": true }, "allowForwarding": { "type": "boolean", "nullable": true }, "linkExpires": { "type": "boolean", "nullable": true }, "setDueDate": { "type": "boolean", "nullable": true }, "dueDate": { "type": "string", "nullable": true, "format": "date-time", "description": "Due date for the document (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "focusedSigningMode": { "type": "boolean", "nullable": true }, "linkMaxSignaturesEnabled": { "type": "boolean", "nullable": true }, "linkMaxSignatures": { "type": "number", "nullable": true }, "fastlaneProfileId": { "type": "string", "nullable": true }, "refId": { "type": "string", "nullable": true }, "sendOutFinishedPdf": { "type": "boolean", "nullable": true }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MemberResponseSchema" } }, "member": { "allOf": [ { "$ref": "#/components/schemas/MemberResponseSchema" }, { "description": "The owner of the document" } ] }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponseBox" }, "default": [], "description": "A form field box in the document response. This is only returned if the document has form fields. If the document is signed the document will return boxes with the values that were filled out." }, "overdue": { "type": "boolean" } }, "required": [ "id", "name", "language", "sendReminder", "member", "overdue" ] } } }, "required": [ "documents" ] }, "DocumentResponseBox": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "nullable": true } ], "description": "The value of the box field. Can be a string (including empty string), boolean, or null depending on the box type." }, "label": { "type": "string" } }, "required": [ "id", "type", "label" ] }, "MemberResponseSchema": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "email": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "isAdmin": { "type": "boolean" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the member was created (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "sentDeleteNotificationAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when delete notification was sent (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "manuallyLastEmailSent": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the last manual email was sent (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "signaturePosition": { "$ref": "#/components/schemas/MemberSignaturePositionResponse" }, "doNotSendEmails": { "type": "boolean" }, "declinedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the member declined (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "signingOrder": { "type": "number" }, "onDemand": { "type": "string", "nullable": true }, "recipientId": { "type": "string", "nullable": true }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "signatureTypesActive": { "type": "boolean" }, "privateMessage": { "type": "string", "nullable": true }, "customId": { "type": "string", "nullable": true }, "useFastlane": { "type": "boolean", "nullable": true }, "role": { "type": "string", "nullable": true }, "approvedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the member was approved (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "verificationConfig": { "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "signatures": { "type": "array", "nullable": true, "items": { "type": "string" } }, "signedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the member signed (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" } }, "required": [ "id", "documentId" ] }, "MemberSignaturePositionResponse": { "anyOf": [ { "$ref": "#/components/schemas/SignaturePositionResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/SignaturePositionResponse" }, "default": [] }, { "nullable": true } ], "default": [], "description": "The signature position(s) for this member. Contains position data when the member has a pending signature on the document. Will be an empty array if no signature is required or if the member has already signed.", "example": [ { "x": 0.6150627615062761, "y": 0.3836805555555556, "page": 0, "width": 0.27742807420298443, "height": 0.1, "cardStyle": "default", "pageWidth": 478, "pageHeight": 675 } ] }, "SignaturePositionResponse": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page number, starting with 0." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "x coordinate of the signatures' top left position" }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "y coordinate of the signatures' top left position" }, "width": { "type": "number", "minimum": 0, "maximum": 1, "description": "Width of the signature." }, "height": { "type": "number", "minimum": 0, "maximum": 1, "description": "Height of the signature." }, "cardStyle": { "type": "string", "description": "The visual style of the signature card. This field is optional and may not be returned in all responses.", "example": "default" }, "pageWidth": { "type": "number", "description": "The width of the page in pixels. This field is optional and may not be returned in all responses.", "example": 478 }, "pageHeight": { "type": "number", "description": "The height of the page in pixels. This field is optional and may not be returned in all responses.", "example": 675 } }, "required": [ "page", "x", "y", "width", "height" ], "description": "Signature position data with additional response-specific fields. The cardStyle, pageWidth, and pageHeight fields are optional and may not be present in all API responses." }, "InviteRecipientsToWorkflowRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "workflowId": { "type": "string", "minLength": 1, "description": "The **workflow memberId** (`documentMembers.id`) of the workflow to use. The workflow has to be created in the UI first. You can find this memberId in the workflow URL. The amount of recipient placeholders has to match the recipients you specify in the request body.", "example": "14e78eb0f4dedde5976f689b799b1c0c5be9ab10073658dcc70a5b0f8af6eec8081ec5" }, "callbackUrl": { "type": "string", "description": "URL to receive callbacks when signatures are added or document status changes after the invitation is sent", "example": "https://yourserver.com/callback" }, "returnUrl": { "type": "string", "default": "", "description": "URL to redirect the user to after signing is complete", "example": "https://yourserver.com/success" }, "returnBtnText": { "type": "string", "description": "The text of the return button after signing a document", "example": "Return to sproof" }, "inviteSuccessUrl": { "type": "string", "default": "", "description": "URL to redirect the user to after the invite is successfully sent. **Only applies to the prepare endpoints** (e.g. `/documents/prepare-recipients-with-workflow` and `/documents/prepare-recipients-with-workflow-envelope`). It is ignored by the invite endpoints that send invitations immediately.", "example": "https://yourserver.com/invite-success" }, "sender": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the sender", "example": "sender@sproof.com" }, "firstName": { "type": "string", "description": "First name of the sender", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the sender", "example": "Doe" } }, "required": [ "email", "firstName", "lastName" ], "description": "Information about the sender of the signature request. Must be a member of your plan." }, "dueDate": { "type": "string", "nullable": true, "description": "The date until which the document can be signed. This due date is displayed to the recipient in the invite email and is also visible in the document details section of the dashboard. It serves as a deadline for completing the signing process.", "example": "YYYY-MM-DD" }, "reminderInterval": { "type": "number", "nullable": true, "description": "Specifies the number of days between reminder emails. If provided, this overrides the reminder interval defined in the workflow.", "example": 7 }, "startSendingReminders": { "type": "string", "nullable": true, "description": "The date from which reminders should be sent out. The format is YYYY-MM-DD HH:mm.", "example": "YYYY-MM-DD HH:mm" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRecipient" }, "description": "Array of recipients to be invited to sign the document. Each recipient must match a placeholder in the workflow by placeholderText (to get the signature position) and by index (to get specific recipient settings like role, signingOrder, signatureTypes).", "example": [ { "email": "recipient@example.com", "firstName": "Jane", "lastName": "Smith", "phoneNumber": "+43123456789", "placeholderText": "{{signer1}}", "index": 1 } ] }, "data": { "type": "string", "nullable": true, "description": "Base64 encoded PDF data. If provided, this PDF will be used instead of the document stored in the workflow. If not provided, the workflow document will be used.", "example": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." }, "fileName": { "type": "string", "minLength": 1, "description": "The name of the file to be signed", "example": "Contract.pdf" } }, "required": [ "token", "workflowId", "sender", "recipients", "fileName" ] }, "PrepareSignatureRequestResponse": { "type": "object", "properties": { "folderId": { "type": "string", "nullable": true }, "folderName": { "type": "string", "nullable": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "members": { "type": "array", "items": { "nullable": true }, "default": [], "description": "As this is a prepare signature request response, the members array will be empty. This is because the members are not invited yet.", "example": [] }, "member": { "allOf": [ { "$ref": "#/components/schemas/MemberResponseSchema" }, { "description": "The owner of the document" } ] } }, "required": [ "id", "name", "language", "member" ] } } }, "required": [ "documents" ] }, "DeleteQualifiedMemberResponse": { "title": "Delete Qualified Member Response", "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } }, "_QualifiedMemberRequestObject": { "description": "Qualified member request object", "type": "object", "required": [ "token", "email" ], "properties": { "token": { "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "type": "string" }, "email": { "description": "Email address of the qualified member", "type": "string", "example": "max.mustermann@sproof.com" }, "register": { "description": "Boolean which indicates that sproof will automatically create an account for the qualified member, If set to `true` then `firstName` and `lastName` become required also .", "type": "boolean", "default": false, "example": true }, "firstName": { "description": "First name of qualified member, becomes `required` parameter if `register` is set to `true`", "type": "string", "example": "Max" }, "lastName": { "description": "Last name of qualified member, becomes `required` parameter if `register` is set to `true`", "type": "string", "example": "Mustermann" }, "phoneNumber": { "description": "Phone number of qualified member", "type": "string", "example": "+4312345678" }, "doNotSendEmail": { "description": "If set to `true` no email is sent to the newly created member", "type": "boolean", "example": true, "default": false } } }, "CreateQualifiedMemberResponse": { "allOf": [ { "title": "Create Qualified Member Response" }, { "$ref": "#/components/schemas/_PlanMember" } ] }, "_PlanMember": { "title": "Plan Member", "type": "object", "properties": { "email": { "description": "Email of plan member", "type": "string", "example": "max.mustermann@sproof.com" }, "firstName": { "description": "First name of member", "type": "string", "example": "Max" }, "lastName": { "description": "Last name of member", "type": "string", "example": "Mustermann" }, "identificationStarted": { "description": "Boolean which indicates if the identification process was started", "type": "boolean", "example": false }, "isIdentified": { "description": "Boolean which indicates if the plan member is identified for qualified signing", "type": "boolean", "example": false }, "identifiedAt": { "type": "string", "format": "date-time", "description": "Date of the last time the user went through the identification process" }, "isAdvancedUser": { "description": "Boolean which indicates if the plan member is an advanced user", "type": "boolean", "example": false }, "isQualifiedUser": { "description": "Boolean which indicates if the plan member is a qualifed user", "type": "boolean", "example": false }, "isBlocked": { "description": "Boolean which indicates if the plan member is blocked but not deleted", "type": "boolean" }, "isPending": { "description": "Boolean which indicates that a plan member wants to join a plan which need to be updated.", "type": "boolean", "example": false }, "role": { "description": "Role of the user in the plan", "type": "string", "example": "user", "enum": [ "owner", "user", "poweruser" ] }, "planTransferPending": { "description": "Plan transfer is in progress", "type": "boolean", "example": false }, "isDeletable": { "description": "Boolean which indicates that a plan member can be deleted. You need to wait at lease 30 days after the identification of a plan member before you can delete the member", "type": "boolean", "example": true }, "remainingDaysToDelete": { "description": "Remaining days to wait until the plan member can be finally deleted", "type": "integer" }, "lastLoginAt": { "type": "string", "format": "date-time", "description": "Date of the last time the member logged into their account" }, "verificationLink": { "description": "A link to set the password and complete the registration process", "type": "string" } } }, "_DocumentRequestBody": { "title": "Document Request Body", "type": "object", "required": [ "token", "data" ], "properties": { "token": { "description": "Token for authentication", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "type": "string" }, "data": { "description": "Base64 Encoded Pdf File as string, represented by the BASE64PDF token", "example": "{{BASE64PDF}}", "type": "string" }, "signature": { "description": "Base64 Encoded PNG File as a string which represents the signature or seal, represented by the BASE64PNGorJPG token", "example": "{{BASE64PNGorJPG}}", "type": "string" }, "page": { "description": "Page number, starting at 0 ,if you pass a page number that is not out of bounds, the last page of the document will be used", "default": 0, "type": "number", "example": 0 }, "x": { "description": "x coordinate of the signature image, default is bottom right position, where 0 is the leftmost edge and 1 is the rightmost edge of the page", "type": "number", "minimum": 0, "maximum": 1, "default": 0.7, "example": 0.142 }, "y": { "description": "y coordinate of the signature image, default values are for bottom right, where 0 is the bottom edge and 1 is the top edge of the page", "type": "number", "minimum": 0, "maximum": 1, "default": 0.9, "example": 0.79 }, "width": { "description": "Width of the signature, relative to the page width, where 1 represents the full width of the page", "type": "number", "minimum": 0, "maximum": 1, "default": 0.3, "example": 0.26 }, "height": { "description": "Height of the signature, relative to the page height, where 1 represents the full height of the page", "type": "number", "minimum": 0, "maximum": 1, "default": 0.1, "example": 0.085 }, "name": { "description": "Name of the signer, defaults to API token holder name", "type": "string", "example": "Max Mustermann" }, "email": { "description": "Email of the signer, defaults to API token holder email", "type": "string", "example": "max.mustermann@sproof.com" }, "key": { "description": "PKCS #12-File including the private key and the X.509 certificate", "type": "string", "example": "" }, "password": { "description": "Password of the key file", "type": "string", "example": "" }, "signatureCard": { "description": "Flag to add a signature card with a visual timestamp that can include a custom image or name based on above parameters, defaults to true if no signature image is provided and uses the api token holder name and email as default values", "type": "boolean", "default": false, "example": true } } }, "_DocumentResponseBody": { "title": "Document Response Body", "type": "object", "properties": { "data": { "description": "Base64 Encoded Signed PDF File", "example": "{{BASE64SIGNEDPDF}}", "type": "string" }, "signatures": { "description": "List of signature details", "type": "array", "items": { "$ref": "#/components/schemas/_SignatureDetail" } } } }, "_SignatureDetail": { "type": "object", "description": "Details about a signature operation", "properties": { "success": { "description": "Indicates if the signature operation was successful", "type": "boolean", "example": true }, "errorMessage": { "description": "Error message if the signature operation failed", "type": "string", "nullable": true, "example": null }, "name": { "description": "Name and email of the signer", "type": "string", "example": "Max Mustermann [max.mustermann@sproof.com]" }, "reason": { "description": "Reason for the signature", "type": "string", "example": "Signature export for Max Mustermann [max.mustermann@sproof.com]" }, "location": { "description": "Location where the signature was created", "type": "string", "example": "sproof sign" }, "date": { "description": "Date and time of the signature", "type": "string", "format": "date-time", "example": "Wed, 10 Jul 2024 09:08:24 GMT" }, "signerInfo": { "description": "Additional signer information", "type": "string", "nullable": true, "example": null }, "page": { "description": "Page number where the signature is located", "type": "integer", "example": 0 }, "width": { "description": "Width of the signature on the page", "type": "string", "example": "0.236" }, "height": { "description": "Height of the signature on the page", "type": "string", "example": "0.085" }, "x": { "description": "x coordinate of the signature's top left position on the page", "type": "string", "example": "0.142" }, "y": { "description": "y coordinate of the signature's top left position on the page", "type": "string", "example": "0.79" }, "valid": { "$ref": "#/components/schemas/_SignatureValidationResult" } } }, "_SignatureValidationResult": { "type": "object", "description": "Validation results of a signature", "properties": { "success": { "description": "Indicates if the validation operation was successful", "type": "boolean", "example": true }, "errorMessage": { "description": "Error message if the validation operation failed", "type": "string", "nullable": true, "example": null }, "valid": { "description": "Indicates if the signature is valid", "type": "boolean", "example": true }, "signatureValid": { "description": "Indicates if the signature itself is valid", "type": "boolean", "example": true }, "certificateValid": { "description": "Indicates if the certificate used for the signature is valid", "type": "boolean", "example": true }, "signatureVerificationResult": { "description": "Result of the signature verification", "type": "string", "example": "signature verified successfully" }, "certificateVerificationResult": { "description": "Result of the certificate verification", "type": "string", "example": "certificate validated successfully" }, "subject": { "description": "Subject of the certificate", "type": "string", "example": "sproof GmbH" }, "issuer": { "description": "Issuer of the certificate", "type": "string", "example": "D-Trust GmbH" }, "signatureQualification": { "description": "Qualification of the signature", "type": "string", "example": "urn:cef:dss:signatureQualification:notApplicable" } } }, "DeleteDocumentResponse": { "title": "Delete Document Response", "type": "string", "enum": [ "deleted single document", "deleted folder" ], "example": "deleted single document" }, "_FolderRequestBody": { "title": "Folder Request Body", "type": "object", "required": [ "signers" ], "properties": { "signers": { "description": "List of signers **without the sender of the document.**", "type": "array", "items": { "$ref": "#/components/schemas/_FolderSigner" } } } }, "_FolderSigner": { "title": "Folder Signer", "type": "object", "properties": { "email": { "description": "Email address of signer", "type": "string", "example": "signer@sproof.com" }, "firstName": { "description": "First name of signer", "type": "string", "example": "maria" }, "lastName": { "description": "Last name of signer", "type": "string", "example": "musterfrau" }, "isSigner": { "description": "Indicates if the person should be able to sign the document or can only view it", "type": "boolean" }, "documents": { "description": "List of document ids and signature positions", "type": "array", "items": { "$ref": "#/components/schemas/_FolderDocumentInvite" } } } }, "_FolderDocumentInvite": { "title": "Folder Document Invite", "type": "object", "properties": { "id": { "description": "Id of the document", "type": "string" }, "signingOrder": { "description": "The order when the signer will be notified to sign the document. The values for signingOrder start at 1. If there exists a smaller signingOrder then this signer needs to sign the document before.", "type": "integer" }, "signaturePosition": { "description": "Array or one single signaturePosition Object. The signature position **relative to the height and width of the page**.", "oneOf": [ { "$ref": "#/components/schemas/_SignaturePosition" }, { "type": "array", "items": { "$ref": "#/components/schemas/_SignaturePosition" } } ] } } }, "_SignaturePosition": { "title": "Signature Position", "type": "object", "properties": { "page": { "description": "Page number, starting with 0", "type": "integer" }, "x": { "description": "x coordinate of the signatures' top left position", "type": "number", "minimum": 0, "maximum": 1, "example": 0.57489 }, "y": { "description": "y coordinate of the signatures' top left position", "type": "number", "minimum": 0, "maximum": 1, "example": 0.8455 }, "width": { "description": "Width of the signature", "type": "number", "minimum": 0, "maximum": 1, "example": 0.35 }, "height": { "description": "Height of the signature", "type": "number", "minimum": 0, "maximum": 1, "example": 0.1 } } }, "_AddFolderDocumentsRequest": { "title": "Add Folder Documents Request", "type": "object", "description": "Request body for adding documents to an envelope", "required": [ "documentIds" ], "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "List of document IDs to be added to the envelope", "example": [ "doc1", "doc2" ] } } }, "AddFolderDocumentsResponse": { "title": "Add Folder Documents Response", "type": "string", "example": "done" }, "_DeleteFolderDocumentsRequest": { "title": "Delete Folder Documents Request", "type": "object", "description": "Request body for deleting documents from an envelope", "required": [ "documentIds" ], "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "List of document IDs to be removed from the envelope", "example": [ "doc1", "doc2" ] } } }, "DeleteFolderDocumentsResponse": { "title": "Delete Folder Documents Response", "type": "string", "example": "deleted: <>, <> from envelope: <>" }, "_UpdateFolderRequest": { "title": "Update Folder Request", "type": "object", "description": "Request body for updating an envelope name", "required": [ "folderName" ], "properties": { "folderName": { "type": "string", "description": "New name for the envelope", "example": "Updated Contract Envelope" } } }, "UpdateFolderResponse": { "title": "Update Folder Response", "type": "string", "example": "done" }, "DeleteFolderResponse": { "title": "Delete Folder Response", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully deleted envelope: <>" } } }, "_FolderResponse": { "title": "Folder Response", "type": "object", "allOf": [ { "$ref": "#/components/schemas/_Folder" } ] }, "_Folder": { "title": "Folder", "type": "object", "properties": { "name": { "description": "Folder name", "type": "string", "example": "important_contract" }, "createdAt": { "description": "Creation date of folder", "example": "2023-03-28T14:36:06.314Z", "type": "string", "format": "date" }, "state": { "description": "State of the folder", "type": "string", "enum": [ "draft", "pending", "done" ], "default": "draft", "example": "draft" }, "isAdmin": { "description": "Indicates if the logged in person is the admin of this folder", "type": "boolean" }, "members": { "description": "A list of invited contacts", "type": "array", "items": { "$ref": "#/components/schemas/_FolderMember" } }, "documents": { "description": "List of documents", "type": "array", "items": { "$ref": "#/components/schemas/_FolderDocument" } } } }, "_FolderDocument": { "title": "Folder Document", "type": "object", "properties": { "name": { "description": "Document Name", "type": "string", "example": "important_contract" }, "state": { "description": "State of the document", "type": "string", "enum": [ "draft", "pending", "done" ], "default": "draft", "example": "draft" }, "documentId": { "description": "Id of the document", "type": "string" }, "memberId": { "description": "MemberId of the user for this document", "type": "string" } } }, "_FolderMember": { "title": "Folder Member", "type": "object", "properties": { "id": { "type": "string", "description": "The member ID can be used to open the document within the sproof sign editor. A more detailed description can be found [here](#section/Using-the-member-ID)", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3" }, "documentId": { "description": "Document ID of the document the member is on", "type": "string", "example": "dd7b88f7c24808372891b54e507988283e30d694dd75c52eb91c466e7a36972a851119" }, "email": { "description": "Email of document owner", "type": "string", "format": "email", "example": "max.mustermann@sproof.com" }, "firstName": { "description": "Firstname of document owner", "type": "string", "example": "Max" }, "lastName": { "description": "Lastname of document owner", "type": "string", "example": "Mustermann" }, "lastActivityAt": { "type": "string", "format": "date", "example": "2022-04-05T08:58:04.206Z" }, "createdAt": { "description": "Date and time of document upload", "type": "string", "format": "date", "example": "2022-04-05T08:58:04.206Z" }, "isAdmin": { "type": "boolean", "description": "Indicates whether the member has Admin status", "example": true }, "signaturePosition": { "description": "Based on what is sent in the request you can expect.", "oneOf": [ { "$ref": "#/components/schemas/_SignaturePosition" }, { "type": "array", "items": { "$ref": "#/components/schemas/_SignaturePosition" } } ] }, "signingOrder": { "type": "number", "example": 1 }, "declinedAt": { "type": "string", "format": "date", "example": null } } }, "_CreateFolderRequest": { "type": "object", "required": [ "name", "documentIds" ], "properties": { "name": { "type": "string", "example": "New Envelope", "description": "Name of the envelope" }, "documentIds": { "type": "array", "description": "Document IDs of draft documents that should be combined into an envelope", "xml": { "wrapped": true }, "items": { "type": "string", "example": [ "1ebf5b4afdc8f421a848b694037a3beb66f7bc70fba1b16c75e223d7f9987b06b091bd", "5e316c52cfcbe810cd12108a6b36141d3cc8116069b4ee1cb66e8a04381ce1ec958176" ], "xml": { "name": "documentId" } } } } }, "CreateFolderResponse": { "title": "Create Folder Response", "type": "object", "properties": { "state": { "type": "string", "example": "envelope created: true" } } }, "_FolderListResponse": { "title": "Folder List Response", "type": "object", "properties": { "data": { "description": "List of envelopes", "type": "array", "items": { "$ref": "#/components/schemas/_FolderResponse" } }, "pagination": { "allOf": [ { "description": "Pagination object" }, { "$ref": "#/components/schemas/_PaginationObject" } ] } } }, "_PaginationObject": { "title": "Pagination Object", "type": "object", "properties": { "total": { "description": "Total number of elements (e.g., documents) in a view (e.g., allDocuments)", "type": "integer", "example": 43 }, "lastPage": { "description": "Number of the last page", "type": "integer", "example": 5 }, "perPage": { "description": "Number of documents per page", "type": "integer", "example": 10 }, "currentPage": { "description": "Number of the current page", "type": "integer", "example": 1 }, "to": { "description": "Index of the last document", "type": "integer", "example": 10 } } }, "_SignatureValidationResponse": { "title": "Signature Validation Response", "type": "object", "description": "Response object for signature validation", "properties": { "success": { "type": "boolean", "description": "Whether the validation was successful", "example": true }, "errorMessage": { "type": "string", "description": "Error message if validation failed", "nullable": true }, "valid": { "type": "boolean", "description": "Whether the signature is valid", "example": true }, "signatureValid": { "type": "boolean", "description": "Whether the signature itself is valid", "example": true }, "certificateValid": { "type": "boolean", "description": "Whether the certificate is valid", "example": true }, "signatureVerificationResult": { "type": "string", "description": "Detailed result of signature verification", "example": "signature verified successfully" }, "certificateVerificationResult": { "type": "string", "description": "Detailed result of certificate verification", "example": "certificate validated successfully" } } }, "VerifyDocumentRequest": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64 encoded file (PDF)", "example": "JVBERi0xLjQKJe... (truncated)" }, "token": { "type": "string", "description": "Token for authentication (e.g. your API key). Can be provided here or as a query parameter.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" } } }, "_SignatureRequestBody": { "title": "Signature Request Body", "type": "object", "required": [ "token", "data", "email", "firstName", "lastName", "fileName" ], "properties": { "token": { "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "type": "string" }, "data": { "description": "Base64 encoded file (PDF or DOCX). If the file is DOCX, mimetype must be set accordingly.", "type": "string", "example": "string Base64 encoded file (PDF or DOCX)" }, "mimetype": { "description": "MIME type of the Base64-encoded file. Required for DOCX files.", "default": "application/pdf", "type": "string", "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ] }, "email": { "description": "Email of the sender. It must belong to a member of your plan.", "type": "string", "format": "email", "example": "max.mustermann@sproof.com" }, "firstName": { "description": "First name of the sender", "type": "string", "example": "Max" }, "lastName": { "description": "Last name of the sender", "type": "string", "example": "Mustermann" }, "fileName": { "description": "Name of the file", "type": "string", "example": "important_contract" }, "callbackUrl": { "description": "A post request including the document will be sent to this Url when a new signature is created", "type": "string" }, "returnUrl": { "type": "string", "description": "The link of the return button after signing a document", "example": "https://sign.sproof.com" }, "returnBtnText": { "type": "string", "description": "The text of the return button after signing a document", "example": "Back to the Dashboard" }, "language": { "description": "Specifies the language of the emails sent to anonymous users who do not have an account. For users with an account, the language they have selected in their profile will be used instead.", "default": "en", "type": "string" }, "signatureTypes": { "description": "This parameter accepts an array containing a single string that specifies the allowed signature type. \n- Set to [\"qualified\"] to allow only qualified signatures.\n- Set to [\"advanced\"] to allow only advanced signatures.\n- If the array is left empty, all signature types are allowed.\n", "type": "array", "items": { "type": "string" }, "default": [], "example": [ "qualified" ] }, "subject": { "description": "The subject line of the email sent to the signers.", "type": "string", "example": "This is a custom subject." }, "message": { "description": "A custom message sent to the signers within the email", "type": "string", "example": "This is a custom message." }, "dueDate": { "description": "For historical reasons, this date marks the start of reminder email notifications. To precisely manage the actual due date—when the document must be signed—as well as the sendReminders and reminderInterval settings, we recommend using the new [createSignatureRequest](#operation/createSignatureRequest) feature", "type": "string", "format": "date YYYY-MM-DD", "example": "2022-03-28" }, "focusedSigningMode": { "description": "When this option is enabled, the recipient of the signature request will be limited to signing or declining the document, and will not be able to navigate away from the page", "type": "boolean", "default": false, "example": false }, "usePlaceholders": { "description": "If set we will use the placeholders stored in the document for inviting signers.", "type": "boolean", "default": false, "example": false }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/Box" }, "default": [], "description": "The boxes of the document." }, "isMailMerge": { "default": false, "type": "boolean", "description": "When set to `true`, the [mail merge document](https://www.sproof.com/en/help-resources/sproof-academy/send-out-mail-merges) included in the request will be automatically split and sent out to all detected recipients within the document. The return value will be an array of document objects representing all successfully created and sent documents." }, "signers": { "description": "List of signers **without the sender of the document.**", "type": "array", "items": { "$ref": "#/components/schemas/_Signer" } }, "label": { "description": "A custom label that can be sent to organize documents.", "type": "string", "example": "Urgent" }, "refId": { "type": "string", "description": "The refId is an optional field used to cross-reference the uploaded document. If provided, it allows you to assign a custom reference identifier to the document, which will be returned as part of the document object in future API responses. This can be useful for tracking or organizing documents by an external system or workflow.\n", "example": "Aug24-1234" }, "useFastlane": { "type": "boolean", "default": false, "example": true, "description": "If set to true all signers receive a fastlane link to the document in the invitation email." }, "fastlaneProfileId": { "type": "string", "format": "uuid", "example": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "description": "Specify the Fastlane profile which should be used with this document. useFastlane needs to be set to true." } } }, "_Signer": { "title": "Signer", "type": "object", "required": [ "email" ], "properties": { "email": { "description": "Email address of signer", "type": "string", "example": "signer@sproof.com" }, "firstName": { "description": "First name of signer", "type": "string", "example": "maria" }, "lastName": { "description": "Last name of signer", "type": "string", "example": "musterfrau" }, "doNotSendEmail": { "description": "If set to `true` no email is sent to the signer", "type": "boolean" }, "useFastlane": { "description": "If set to ``true`` the signer receives a Fastlane link in the invitation email", "type": "boolean" }, "customId": { "description": "The customId can be used to create a document link for a recipient instead of using the memberId provided by the return object of the createSignatureRequest. Check [Using the custom ID](#section/Using-the-Custom-ID) for more information.\n\n**Note: The customId can only be used to build the recipient link to a document. It can not be used for other requests instead of the memberId**\n", "type": "string" }, "isSigner": { "description": "Set to `false` if the signer should be treated as viewer only", "type": "boolean" }, "signingOrder": { "description": "The order when the signer will be notified to sign the document. The values for signingOrder start at 1. If there exists a smaller signingOrder then this signer needs to sign the document before.", "type": "integer" }, "defaultProvider": { "$ref": "#/components/schemas/_DefaultProvider" }, "signaturePosition": { "title": "DocumentMemberSignaturePosition", "description": "Array or one single signaturePosition Object. The signature position **relative to the height and width of the page**.", "oneOf": [ { "$ref": "#/components/schemas/_SignaturePosition" }, { "type": "array", "items": { "$ref": "#/components/schemas/_SignaturePosition" } } ] } } }, "_DefaultProvider": { "type": "object", "description": "Configuration for the default signature provider", "nullable": true, "properties": { "tag": { "type": "string", "description": "This tag determines the identity provider that will be used for the signing process. Choose from a predefined set of supported providers. \n>**Note1:** Some providers are only available for certain signatureTypes, for example ``onetimeqes`` will require ``\"signatureType\" : [\"qualifiedPlusIdent\"]`` \n**Note2:** When using ``sproof-qualified`` as default provider the recipient has to have an active sproof account with an active User+ licence.", "enum": [ "sproof-standard", "sproof-qualified", "simple", "dtrust", "evrotrust", "smartid", "mobileid", "idaustria", "swisscom", "prime", "yes", "spid", "beidcard", "fiidcard", "hridcard", "eeidcard", "uanataca", "lvidcard", "ptidcard", "frusbcard", "rousbcard", "simplysign", "primeeid", "certme", "onetimeqes" ] }, "canChange": { "type": "boolean", "description": "Boolean to indicate if the invited recipient should be able to change the signature provider", "example": false, "default": true }, "country": { "type": "string", "description": "The default country, if blank it's set to all, an error will be returned with what countries are available for the provider tag chosen", "example": "at", "default": "all", "enum": [ "all", "at", "be", "bg", "hr", "cy", "cz", "dk", "ee", "fi", "fr", "de", "gr", "hu", "ie", "it", "lv", "lt", "lu", "mt", "nl", "pl", "pt", "ro", "sk", "si", "es", "se", "al", "ad", "am", "by", "ba", "fo", "ge", "gi", "is", "im", "xk", "li", "mk", "md", "mc", "me", "no", "sm", "rs", "ch", "tr", "ua", "gb", "va" ] } } }, "Box": { "oneOf": [ { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "textBoxMultiLine" ] }, "multiline": { "type": "boolean", "default": false, "description": "Whether multiple lines are allowed." } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "TextBoxMultiLine" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "dateBox" ] } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "DateBox" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "chooseBox" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "displayValue": { "type": "string" }, "exportValue": { "type": "string" } }, "required": [ "displayValue", "exportValue" ] }, "description": "All the possible choices in this drop down box, displayValue and exportValue can be the same." } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "ChooseBox" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "radioBox" ] }, "group": { "type": "number", "default": 1, "description": "Each radio box can be assigned to a group." } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "RadioBox" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "checkBox" ] } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "CheckBox" }, { "type": "object", "properties": { "page": { "type": "integer", "description": "Number of the page the box is on, with the first page being 0." }, "pageWidth": { "type": "integer", "description": "Any integer value describing the page width. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 478 as a default value." }, "pageHeight": { "type": "integer", "description": "Any integer value describing the page height. The larger the number, the better the precision when positioning the box in x y space. On an A4 page, we have 676 as a default value." }, "x": { "type": "number", "description": "Represents the horizontal position of the box as a percentage of the page width. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page width from the left.", "format": "float" }, "y": { "type": "number", "description": "Represents the vertical position of the box as a percentage of the page height. The origin (0,0) is at the top left of the page. A value of 0.1 means the box is positioned at 10% of the page height from the top.", "format": "float" }, "width": { "type": "number", "description": "Width of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageWidth.", "format": "float" }, "height": { "type": "number", "description": "Height of the box based on page dimensions, similar to the x and y coordinates. It's a float representing a percentage of the pageHeight.", "format": "float" }, "id": { "type": "string", "description": "A unique ID for this box, generated in any way you wish." }, "label": { "type": "string", "description": "Placeholder text, such as the name of the field, e.g., \"Date of Birth.\"." }, "value": { "type": "string", "nullable": true, "description": "Default value for the box. Can be null. If the box is of type 'chooseBox', the value can be null or one of the strings defined in the options." }, "readonly": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot modify the value of this box." }, "required": { "type": "boolean", "default": false, "description": "If set to true, the invited person cannot sign the document without filling out this box." }, "type": { "type": "string", "enum": [ "ibanBox" ] } }, "required": [ "page", "x", "y", "width", "height", "id", "type" ], "title": "IbanBox" } ], "discriminator": { "propertyName": "type" }, "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] }, "_Document": { "title": "Document", "type": "object", "properties": { "name": { "description": "Document name", "type": "string", "example": "important_contract" }, "id": { "description": "Document ID", "type": "string", "example": "7c4d105bf2cc7a146ce00b873563770fc8be20fe8c9946552dd212cdc2b49a554a356a" }, "updatedAt": { "description": "Date of last document update", "example": "2022-03-28T14:40:06.698Z", "type": "string", "format": "date" }, "createdAt": { "description": "Creation date of document", "example": "2022-03-28T14:36:06.314Z", "type": "string", "format": "date" }, "signaturesTypes": { "type": "array", "items": { "type": "string" }, "description": "The types of signatures that are allowed for this recipient, can be overwritten by recipient signature types. Options: ['advanced', 'advancedPlus', 'qualified', 'simple','qualifiedPlusIdent']", "example": [] }, "callbackUrl": { "type": "string", "description": "A post request including the document will be sent to this Url when a new signature is created", "example": "string" }, "returnUrl": { "type": "string", "description": "The link of the return button after signing a document", "example": "https://sign.sproof.com" }, "returnBtnText": { "type": "string", "description": "The text of the return button after signing a document", "example": "Back to the Dashboard" }, "inPersonSigning": { "type": "boolean", "example": false }, "signingRound": { "type": "number", "example": 2 }, "state": { "type": "string", "description": "The current state of the document. Possible values are: draft, pending, declined, completed, attachment, manuallyPending, manuallyCompleted", "example": "pending" }, "member": { "allOf": [ { "description": "Usually the owner of the document, but if you use getSignatureStatus the member will be one who's id is provided in the request" }, { "$ref": "#/components/schemas/_Member" } ] }, "members": { "description": "A list of invited contacts", "type": "array", "items": { "$ref": "#/components/schemas/_Member" }, "example": [] }, "boxes": { "type": "array", "default": [], "description": "Signature position data with additional response-specific fields. The cardStyle, pageWidth, and pageHeight fields are optional and may not be present in all API responses.", "items": { "$ref": "#/components/schemas/DocumentResponseBox" }, "example": [] }, "refId": { "type": "string", "example": "Aug24-1234" }, "allSignersSigned": { "type": "boolean", "example": false }, "allMembersSigned": { "type": "boolean", "example": false }, "focusedSigningMode": { "type": "boolean", "example": false } } }, "_Member": { "type": "object", "properties": { "id": { "type": "string", "description": "The member ID can be used to open the document within the sproof sign editor. A more detailed description can be found [here](#section/Using-the-member-ID)", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3" }, "email": { "type": "string", "description": "Email of document owner", "example": "max.mustermann@sproof.com" }, "firstName": { "type": "string", "description": "Firstname of document owner", "example": "Max" }, "lastName": { "type": "string", "description": "Lastname of document owner", "example": "Mustermann" }, "lastActivityAt": { "type": "string", "format": "date-time", "description": "Date and time of last activity (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time of document upload (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "signed": { "type": "boolean", "description": "Indicates whether the document was signed by the owner", "example": false }, "isAdmin": { "type": "boolean", "description": "Indicates whether the member has Admin status", "example": true }, "isSigner": { "type": "boolean", "description": "Indicates whether the member is a signer", "example": false }, "isApprover": { "type": "boolean", "description": "Indicates whether the member is an approver", "example": false }, "isViewer": { "type": "boolean", "description": "Indicates whether the member is a viewer", "example": false }, "approvedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Only if isApprover is true. Date and time when the member was approved (ISO 8601 datetime string)", "example": null }, "viewedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Only if isViewer is true. Date and time when the member viewed the document (ISO 8601 datetime string)", "example": null }, "signaturePosition": { "anyOf": [ { "$ref": "#/components/schemas/SignaturePositionResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/SignaturePositionResponse" } } ], "description": "The signature position(s) for this member. Based on what is sent in the request you can expect either a single position object or an array of position objects." }, "signedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time of the signature (ISO 8601 datetime string)", "example": null }, "signingOrder": { "type": "number", "description": "The order in which this member should sign", "example": 1 }, "declinedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the member declined (ISO 8601 datetime string)", "example": null }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "signatureType": { "type": "string", "description": "Type of signature (e.g. aes_sproof)", "example": "aes_sproof" }, "signedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the signature was applied (ISO 8601 datetime string)", "example": "2023-05-26T08:03:42.946Z" } }, "required": [ "signatureType", "signedAt" ] }, "description": "Array of signatures", "example": [ { "signatureType": "aes_sproof", "signedAt": "2023-05-26T08:03:42.946Z" } ] } }, "required": [ "id", "email", "firstName", "lastName", "lastActivityAt", "createdAt", "signed", "isAdmin", "isSigner", "isApprover", "isViewer", "approvedAt", "viewedAt", "signaturePosition", "signedAt", "signingOrder", "declinedAt", "signatures" ] }, "_DocumentListResponse": { "title": "Document List Response", "type": "object", "description": "Response object for document list operations", "properties": { "data": { "type": "array", "description": "List of documents", "items": { "$ref": "#/components/schemas/_Document" } }, "pagination": { "$ref": "#/components/schemas/_PaginationObject" } } }, "EnvelopeResponse": { "type": "object", "properties": { "folderId": { "type": "string", "nullable": true }, "folderName": { "type": "string", "nullable": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "startSendingReminders": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when reminders start being sent (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "sendReminder": { "type": "boolean" }, "reminderSent": { "type": "boolean", "nullable": true }, "reminderInterval": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Date and time when the document was created (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "callbackUrl": { "type": "string", "nullable": true }, "returnUrl": { "type": "string", "nullable": true }, "returnBtnText": { "type": "string", "nullable": true }, "inPersonSigning": { "type": "boolean", "nullable": true }, "signingRound": { "type": "number", "nullable": true }, "isTemplate": { "type": "boolean", "nullable": true }, "templateId": { "type": "string", "nullable": true }, "linkId": { "type": "string", "nullable": true }, "linkExpiresAt": { "type": "string", "nullable": true }, "derivedFromLink": { "type": "boolean", "nullable": true }, "state": { "type": "string", "nullable": true }, "complianceLevel": { "type": "string", "nullable": true }, "allowForwarding": { "type": "boolean", "nullable": true }, "linkExpires": { "type": "boolean", "nullable": true }, "setDueDate": { "type": "boolean", "nullable": true }, "dueDate": { "type": "string", "nullable": true, "format": "date-time", "description": "Due date for the document (ISO 8601 datetime string)", "example": "2022-04-05T08:58:04.206Z" }, "focusedSigningMode": { "type": "boolean", "nullable": true }, "linkMaxSignaturesEnabled": { "type": "boolean", "nullable": true }, "linkMaxSignatures": { "type": "number", "nullable": true }, "fastlaneProfileId": { "type": "string", "nullable": true }, "refId": { "type": "string", "nullable": true }, "sendOutFinishedPdf": { "type": "boolean", "nullable": true }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MemberResponseSchema" } }, "member": { "allOf": [ { "$ref": "#/components/schemas/MemberResponseSchema" }, { "description": "The owner of the document" } ] }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponseBox" }, "default": [], "description": "A form field box in the document response. This is only returned if the document has form fields. If the document is signed the document will return boxes with the values that were filled out." }, "overdue": { "type": "boolean" } }, "required": [ "id", "name", "language", "sendReminder", "member", "overdue" ] } } }, "required": [ "documents" ] }, "CreateSignatureRequest": { "type": "object", "properties": { "token": { "type": "string", "description": "Optional token for authentication when not sent via X-API-Key header or query parameter.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "inviteData": { "$ref": "#/components/schemas/InviteData" }, "envelopeData": { "$ref": "#/components/schemas/EnvelopeData" } }, "required": [ "inviteData", "envelopeData" ] }, "EnvelopeData": { "type": "object", "properties": { "usePlaceholders": { "type": "boolean", "description": "If true, text placeholders/formFields stored in the document\n wil be used for inviting recipients.", "example": false }, "inPersonSigning": { "type": "boolean", "description": "When true, the recipient gets a popup where he needs to manually draw a signature", "example": false }, "folderName": { "type": "string", "description": "If given, an envelope will be created containing all documents in documentDataArray. (Required if more than one document is sent)", "example": "Important Documents." }, "callbackUrl": { "type": "string", "description": "A POST request, including the document, will be sent to this URL when a new signature is created or when a recipient declines the document. In case of failure, a retry mechanism is in place to ensure the request is retried.", "example": "https://yourserver.com/api/v1/documents/signature." }, "returnUrl": { "type": "string", "description": "The link of the return button after signing a document", "example": "https://www.sproof.com." }, "returnBtnText": { "type": "string", "description": "The text of the return button after signing a document", "example": "Return to sproof." }, "documentDataArray": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentData" }, "maxItems": 25, "description": "Array of the data of each document, if more than one document is sent, the folderName is required. Maximum 25 documents per envelope." }, "useFastlane": { "type": "boolean", "description": "If set to ``true`` the signer receives a Fastlane link in the invitation email." }, "fastlaneProfileId": { "type": "string", "format": "uuid", "description": "Specify the Fastlane profile which should be used with this document. (useFastlane must be set to true)." } }, "required": [ "documentDataArray" ], "description": "Can create either one document or multiple documents in an envelope. If more than one document is sent, the folderName is required.", "example": { "documentDataArray": [ { "data": "base64string", "fileName": "important_contract", "recipientDetails": { "max.mustermann@sproof.com": { "role": "signer", "signaturePositions": [ { "page": 0, "x": 0.57489, "y": 0.8455, "width": 0.35, "height": 0.1 } ] }, "maria.musterfrau@sproof.com": { "role": "viewer" } } } ] } }, "DocumentData": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "$ref": "#/components/schemas/Attachment" } ] }, "Attachment": { "type": "object", "properties": { "data": { "type": "string", "description": "The document (PDF or DOCX) data in base64 format.", "example": "base64string." }, "mimetype": { "type": "string", "nullable": true, "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ], "default": "application/pdf", "description": "MIME type of base64 encoded data PDF or DOCX, required if the document is not a pdf", "example": "application/pdf" }, "fileName": { "type": "string", "description": "Name of the file", "example": "important_contract." }, "label": { "type": "string", "description": "A custom label that can be sent to organize documents." }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/Box" }, "default": [], "description": "An array of form fields that can be added to a document, allowing for various types of user input. Box type can be one of the following: textBoxMultiLine, dateBox, chooseBox, radioBox, checkBox, ibanBox." }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [], "description": "The types of signatures that are allowed for this recipient, can be overwritten by recipient signature types. Options: ['advanced', 'advancedPlus', 'qualified', 'simple','qualifiedPlusIdent']" }, "refId": { "type": "string", "description": "The refId is an optional field used to cross-reference the uploaded document. If provided, it allows you to assign a custom reference identifier to the document, which will be returned as part of the document object in future API responses. This can be useful for tracking or organizing documents by an external system or workflow." }, "language": { "type": "string", "description": "The document language." }, "folderId": { "type": "string", "description": "The ID of a folder into which the documents should be inserted. This is only possible when both inviteData and folderName are undefined." }, "isAttachment": { "type": "boolean", "enum": [ true ], "description": "True to indicate the document is an attachment." }, "recipientDetails": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/DocumentRecipientDetails" } ], "title": "DocumentRecipientDetails", "x-additionalPropertiesName": "recipient email or customId" }, "description": "recipientDetails is not needed in this case.", "propertyNames": { "description": "The key (property name) is either the email of the recipient or the customId if provided." } } }, "required": [ "data", "fileName", "isAttachment" ] }, "DocumentRecipientDetails": { "oneOf": [ { "type": "object", "properties": { "signingOrder": { "type": "integer", "default": 1, "description": "The order when the recipient will be notified to interact with the document." }, "role": { "type": "string", "enum": [ "signer" ], "description": "The role must be signer in this case." }, "signaturePositions": { "type": "array", "items": { "$ref": "#/components/schemas/SignaturePosition" }, "description": "The signature position array of the signer, it is required when the role is signer." }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [], "description": "The types of signatures that are allowed for this recipient. Options: ['advanced', 'advancedPlus', 'qualified', 'simple']" } }, "required": [ "role", "signaturePositions" ], "title": "SignerRecipientDetails" }, { "type": "object", "properties": { "signingOrder": { "type": "integer", "default": 1, "description": "The order when the recipient will be notified to interact with the document." }, "role": { "type": "string", "enum": [ "viewer", "approver" ], "description": "The role for the recipient." }, "signaturePositions": { "type": "array", "items": { "$ref": "#/components/schemas/SignaturePosition" }, "description": "The signature position array is not needed in this case." }, "signatureTypes": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The signature types array is not needed in this case." } }, "required": [ "role" ], "title": "Non-SignerRecipientDetails" } ], "discriminator": { "propertyName": "role" }, "type": "object", "properties": { "role": { "type": "string" } }, "required": [ "role" ] }, "SignaturePosition": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page number, starting with 0." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "x coordinate of the signatures' top left position" }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "y coordinate of the signatures' top left position" }, "width": { "type": "number", "minimum": 0, "maximum": 1, "description": "Width of the signature." }, "height": { "type": "number", "minimum": 0, "maximum": 1, "description": "Height of the signature." } }, "required": [ "page", "x", "y", "width", "height" ] }, "Document": { "type": "object", "properties": { "data": { "type": "string", "description": "The document (PDF or DOCX) data in base64 format.", "example": "base64string." }, "mimetype": { "type": "string", "nullable": true, "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ], "default": "application/pdf", "description": "MIME type of base64 encoded data PDF or DOCX, required if the document is not a pdf", "example": "application/pdf" }, "fileName": { "type": "string", "description": "Name of the file", "example": "important_contract." }, "label": { "type": "string", "description": "A custom label that can be sent to organize documents." }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/Box" }, "default": [], "description": "An array of form fields that can be added to a document, allowing for various types of user input. Box type can be one of the following: textBoxMultiLine, dateBox, chooseBox, radioBox, checkBox, ibanBox." }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [], "description": "The types of signatures that are allowed for this recipient, can be overwritten by recipient signature types. Options: ['advanced', 'advancedPlus', 'qualified', 'simple','qualifiedPlusIdent']" }, "refId": { "type": "string", "description": "The refId is an optional field used to cross-reference the uploaded document. If provided, it allows you to assign a custom reference identifier to the document, which will be returned as part of the document object in future API responses. This can be useful for tracking or organizing documents by an external system or workflow." }, "language": { "type": "string", "description": "The document language." }, "folderId": { "type": "string", "description": "The ID of a folder into which the documents should be inserted. This is only possible when both inviteData and folderName are undefined." }, "isAttachment": { "type": "boolean", "description": "isAttachment is not needed in this case." }, "recipientDetails": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/DocumentRecipientDetails" } ], "title": "DocumentRecipientDetails", "x-additionalPropertiesName": "recipient email or customId" }, "description": "The details of each recipient for this document. The key (*property name*) is either the email of the recipient or the customId if provided.", "example": { "max.mustermann@sproof.com": { "role": "signer", "signaturePositions": [ { "page": 0, "x": 0.57489, "y": 0.8455, "width": 0.35, "height": 0.1 } ] }, "maria.musterfrau@sproof.com": { "role": "viewer" } }, "propertyNames": { "description": "The key (property name) is either the email of the recipient or the customId if provided." } } }, "required": [ "data", "fileName", "recipientDetails" ] }, "InviteData": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/Sender" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "List of recipients **without the sender of the document.**", "example": [ { "email": "max.mustermann@sproof.com", "firstName": "Max", "lastName": "Mustermann." }, { "email": "maria.musterfrau@sproof.com", "firstName": "Maria", "lastName": "Musterfrau." } ] }, "dueDate": { "type": "string", "nullable": true, "format": "YYYY-MM-DD", "description": "The date until which the document can be signed. This due date is displayed to the recipient in the invite email and is also visible in the document details section of the dashboard. It serves as a deadline for completing the signing process.", "example": "2032-12-31" }, "reminderInterval": { "type": "number", "nullable": true, "description": "Specifies the number of days between reminder emails.", "example": 3 }, "startSendingReminders": { "type": "string", "nullable": true, "format": "YYYY-MM-DD HH:MM", "description": "Date from which reminders should be sent out", "example": "2030-12-31 23:59" }, "inviteLanguage": { "type": "string", "nullable": true, "default": "en", "description": "Specifies the language of the emails sent to anonymous users who do not have an account. For users with an account, the language they have selected in their profile will be used instead.", "example": "en." }, "message": { "type": "string", "nullable": true, "maxLength": 5000, "description": "A custom message sent to the recipients within the email.", "example": "Please sign this document." }, "subject": { "type": "string", "nullable": true, "maxLength": 255, "description": "The subject line of the email sent to the recipients.", "example": "Signature required." }, "sendOutFinishedPdf": { "type": "boolean", "nullable": true, "description": "If set to true, the pdf is sent as an attachment to all recipients on the document (If it is smaller than 5MB).", "example": false }, "focusedSigningMode": { "type": "boolean", "nullable": true, "default": false, "description": "When this option is enabled, the recipient of the signature request will be limited to signing or declining the document, and will not be able to navigate away from the page.", "example": false }, "allowForwarding": { "type": "boolean", "nullable": true, "description": "Allow forwarding of the invite.", "example": false }, "collabSigningMode": { "$ref": "#/components/schemas/CollabSigningMode" } }, "required": [ "sender", "recipients" ], "description": "Data relevant for the invitation", "example": { "sender": { "email": "youremail@sproof.com", "firstName": "yourname", "lastName": "yourlastname." }, "recipients": [ { "email": "max.mustermann@sproof.com", "firstName": "Max", "lastName": "Mustermann." }, { "email": "maria.musterfrau@sproof.com", "firstName": "Maria", "lastName": "Musterfrau." } ] } }, "CollabSigningMode": { "type": "object", "additionalProperties": { "type": "boolean", "description": "Indicates whether only one person (true) or everyone (false) is required to sign the document in the specified signing round." }, "description": "An object where each key represents a signing round, and its corresponding value indicates whether collaborative signing is enabled for that round. If the value is true, only one signature is required to complete the specified signing round and proceed to the next round. For example, { '1': true } means that in signing round '1', only one signature is necessary.", "example": { "1": true } }, "Recipient": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of the recipient." }, "firstName": { "type": "string", "description": "First name of the recipient." }, "lastName": { "type": "string", "description": "Last name of the recipient." }, "doNotSendEmails": { "type": "boolean", "description": "If set to `true` no email is sent to the recipient." }, "customId": { "type": "string", "description": "To be used only when the recipient's email address is **unknown** at the time of inviting. This only works when you invite the recipients (not for prepare routes) and you want to use fastlane. The `customId` allows you to pre-generate a unique signing link for a recipient before sending an invitation.\nMust be a unique, alphanumeric string of at least 70 characters.\n\n **Note**: The customId can only be used to build the recipient link to a document. It can not be used for other requests instead of the memberId.\nFor details on URL construction, see [Opening a document with a Custom ID](#tag/fastlane/GET/fastlane/custom/{planId}/{customId})" }, "useFastlane": { "type": "boolean", "description": "If set to ``true`` the signer receives a Fastlane link in the invitation email." }, "phoneNumber": { "type": "string", "nullable": true, "description": "The phone number of this recipient. This is used for SMS verification. (eg: +43 699 1234 1234)." }, "privateMessage": { "type": "string", "nullable": true, "description": "A private message for this specific recipient." }, "inPersonMode": { "type": "boolean", "nullable": true, "default": false, "description": "When this option is enabled, the recipient of the signature request will be required to sign the document in person and no email is sent. This mode is only available using the SES signature type" }, "signatureTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [], "description": "The types of signatures that are allowed for this recipient. Options: ['advanced', 'advancedPlus', 'qualified', 'qualifiedPlusIdent', 'simple']" }, "defaultProvider": { "type": "object", "nullable": true, "properties": { "tag": { "type": "string", "description": "This tag determines the identity provider that will be used for the signing process. Choose from a predefined set of supported providers. \n\n >**Note1:** Some providers are only available for certain signatureTypes, for example ``onetimeqes`` will require ``\"signatureType\" : [\"qualifiedPlusIdent\"]`` \n\n **Note2:** When using ``sproof-qualified`` as default provider the recipient has to have an active sproof account with an active User+ licence.", "enum": [ "sproof-standard", "sproof-qualified", "simple", "dtrust", "evrotrust", "smartid", "mobileid", "idaustria", "swisscom-ciba", "swisscom-ciba-zertes", "prime", "yes", "spid", "beidcard", "fiidcard", "hridcard", "eeidcard", "uanataca", "lvidcard", "ptidcard", "frusbcard", "rousbcard", "simplysign", "primeeid", "certme", "onetimeqes" ] }, "canChange": { "type": "boolean", "description": "Boolean to indicate if the invited recipient should be able to change the signature provider", "example": false, "default": true }, "country": { "type": "string", "description": "The default country, if blank it's set to all, an error will be returned with what countries are available for the provider tag chosen", "example": "at", "default": "all", "enum": [ "all", "at", "be", "bg", "hr", "cy", "cz", "dk", "ee", "fi", "fr", "de", "gr", "hu", "ie", "it", "lv", "lt", "lu", "mt", "nl", "pl", "pt", "ro", "sk", "si", "es", "se", "al", "ad", "am", "by", "ba", "fo", "ge", "gi", "is", "im", "xk", "li", "mk", "md", "mc", "me", "no", "sm", "rs", "ch", "tr", "ua", "gb", "va" ] } }, "description": "Configure a default signature provider for the invited recipient" } } }, "Sender": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of the sender. It must belong to a member of your plan." }, "firstName": { "type": "string", "minLength": 1, "description": "First name of the sender." }, "lastName": { "type": "string", "description": "Last name of the sender." }, "role": { "type": "string", "enum": [ "signer", "viewer", "approver", "none" ], "description": "The role of the sender on all documents." } }, "required": [ "email", "firstName" ], "description": "The sender of the document, it must be a member of your plan.", "example": { "email": "youremail@sproof.com", "firstName": "yourname", "lastName": "yourlastname." } }, "_BatchDeleteResponse": { "title": "Batch Delete Response", "type": "object", "description": "Response for batch delete operations", "properties": { "deletedProfiles": { "type": "array", "description": "List of deleted profile IDs", "items": { "type": "string", "format": "uuid" }, "example": [ "54f82188-7461-48fe-882c-afbf98256b16", "ff093edf-2c18-4302-bb82-f3ca202694e5" ] } } }, "_BatchDeleteRequest": { "title": "Batch Delete Request", "type": "object", "description": "Request body for batch deleting Fastlane profiles", "properties": { "ids": { "type": "array", "description": "List of profile IDs to be deleted", "items": { "type": "string", "format": "uuid" }, "example": [ "54f82188-7461-48fe-882c-afbf98256b16", "ff093edf-2c18-4302-bb82-f3ca202694e5" ] } } }, "RemoveProfileFromDocumentResponse": { "title": "Remove Profile from Document Response", "type": "object", "properties": { "removed": { "type": "string", "example": "54f82188-7461-48fe-882c-afbf98256b16" } } }, "_RemoveFastlaneProfileRequest": { "title": "Remove Fastlane Profile Request", "type": "object", "description": "Request body for removing a Fastlane profile from documents", "properties": { "memberIds": { "type": "array", "description": "List of admin memberIds where the Fastlane profile should be removed from.", "items": { "type": "string", "example": "d46b68b53d2bef3025fd21a0737b0cd7425b1270b0115f39dafa46131023247cd46e7f" } } } }, "AddProfileToDocumentResponse": { "title": "Add Profile to Document Response", "type": "object", "properties": { "set": { "type": "string", "example": "54f82188-7461-48fe-882c-afbf98256b16" } } }, "AddProfileToDocumentRequest": { "type": "object", "properties": { "memberIds": { "type": "array", "description": "A list of unique admin memberIds. Each id corresponds to a document that will be configured to use the Fastlane profile specified.\n\n**Note: The Fastlane profile is only visible to recipients where the useFastlane flag was set at the time of the invite.**\n", "items": { "type": "string", "example": "d46b68b53d2bef3025fd21a0737b0cd7425b1270b0115f39dafa46131023247cd46e7f" } } } }, "DeleteFastlaneProfileResponse": { "title": "Delete Fastlane Profile Response", "type": "object", "properties": { "deletedProfiles": { "type": "array", "description": "A list of profile IDs that have been successfully deleted.", "items": { "type": "string", "format": "uuid", "example": "ff093edf-2c18-4302-bb82-f3ca202694e5" } } } }, "UpdateFastlaneProfileResponse": { "title": "Update Fastlane Profile Response", "type": "object", "properties": { "updatedProfile": { "$ref": "#/components/schemas/_FastlaneConfiguration" } } }, "_FastlaneConfiguration": { "type": "object", "description": "Configuration settings for the Fastlane profile, including customizable screens and success email.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the Fastlane profile that appears in the profile selector.", "minLength": 1, "maxLength": 100, "example": "Document Signing for HR" }, "screens": { "$ref": "#/components/schemas/_FastlaneScreensConfiguration" }, "successEmail": { "$ref": "#/components/schemas/_SuccessEmailConfiguration" }, "backgroundColor": { "type": "string", "description": "The background color of the Fastlane screens as a hex color.", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "example": "#e1e1e1", "default": "#FFFFFF" }, "showAppBar": { "type": "boolean", "description": "If set to false, hides the app bar of the Fastlane.", "default": true }, "showProgressBar": { "type": "boolean", "description": "If set to false, hides the progress bar of the Fastlane.", "default": true }, "showHeader": { "type": "boolean", "description": "If set to false, hides the header in the signing-screen.", "default": true } }, "additionalProperties": false }, "_SuccessEmailConfiguration": { "type": "object", "description": "Customization settings for the success email sent after completion.", "properties": { "subject": { "type": "string", "description": "Subject line of the success email.", "maxLength": 255, "example": "SUBJECT", "default": "[recipient_name] has signed [document_name]" }, "title": { "type": "string", "description": "Title of the success email.", "maxLength": 100, "example": "THIS IS THE CUSTOM TITLE", "default": "You have signed [document_name]" }, "text": { "type": "string", "description": "Body text of the success email.", "maxLength": 1000, "example": "CUSTOM TEXT THAT IS ADDED IN THE FASTLANE", "default": "[document_name] was signed successfully. You can find the document in the attachment or view it in the dashboard." }, "sendEmail": { "type": "boolean", "description": "If set to false, an email will not be sent to the signer.", "default": true } }, "additionalProperties": false }, "_FastlaneScreensConfiguration": { "type": "object", "description": "Customization options for the profile's screens.", "properties": { "welcome": { "$ref": "#/components/schemas/_WelcomeScreenConfiguration" }, "document": { "$ref": "#/components/schemas/_DocumentScreenConfiguration" }, "provider": { "$ref": "#/components/schemas/_ProviderScreenConfiguration" }, "sign": { "$ref": "#/components/schemas/_SignScreenConfiguration" }, "end": { "$ref": "#/components/schemas/_EndScreenConfiguration" } }, "additionalProperties": false }, "_EndScreenConfiguration": { "allOf": [ { "$ref": "#/components/schemas/_BaseScreenConfiguration" }, { "type": "object", "properties": { "helpText": { "type": "boolean", "description": "Displays help text on the end screen if enabled.", "default": true }, "shareDocumentBtn": { "type": "boolean", "description": "Displays the share document button if enabled.", "default": true }, "showDownloadDocBtn": { "type": "boolean", "description": "Shows the download document button if enabled.", "default": true } }, "additionalProperties": false } ], "description": "Settings for the end screen.\n" }, "_BaseScreenConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Determines whether the screen is enabled.", "default": true }, "title": { "type": "string", "description": "Title of the screen.", "maxLength": 100 }, "description": { "type": "string", "description": "Description text for the screen.", "maxLength": 500 }, "icon": { "type": "boolean", "description": "Displays an icon on the screen if enabled.", "default": true } }, "additionalProperties": false }, "_SignScreenConfiguration": { "type": "object", "properties": { "signOnDisplay": { "type": "boolean", "description": "Determines whether the signature screen supports sign-on-display.", "default": true }, "signatureCard": { "type": "boolean", "description": "If set to true, the visual representation includes a signature card.", "default": true }, "previewDocumentButton": { "type": "boolean", "description": "Displays the preview document button if enabled.", "default": true } }, "additionalProperties": false, "description": "Settings for the signature screen.\n" }, "_ProviderScreenConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Determines whether the provider screen is enabled.", "default": true }, "defaultCountry": { "$ref": "#/components/schemas/_CountryCode" }, "defaultProviderTag": { "$ref": "#/components/schemas/_ProviderTag" } }, "description": "Settings for the provider screen.\n" }, "_ProviderTag": { "type": "string", "description": "Identity provider tag for the signing process", "enum": [ "evrotrust", "primeeid", "swisscom", "smartid", "mobileid", "ptidcard", "beidcard", "frusbcard", "rousbcard", "dtrust", "lvidcard", "eeidcard", "fiidcard", "hridcard", "idaustria", "prime", "simplysign", "spid", "sproof-standard", "sproof-qualified", "uanataca", "yes", "" ], "x-enum-descriptions": [ "Evrotrust provider", "PrimeEID provider", "Swisscom provider", "SmartID provider", "MobileID provider", "Portuguese ID Card provider", "Belgian ID Card provider", "French USB Card provider", "Romanian USB Card provider", "D-Trust provider", "Latvian ID Card provider", "Estonian ID Card provider", "Finnish ID Card provider", "Croatian ID Card provider", "ID Austria provider", "Prime provider", "SimplySign provider", "SPID provider", "Sproof Standard provider", "Sproof Qualified provider (requires active User+ license)", "Uanataca provider", "Yes provider", "Empty/No provider selected" ], "default": "" }, "_CountryCode": { "type": "string", "description": "ISO country code or 'all' for all countries", "enum": [ "all", "at", "be", "bg", "hr", "cy", "cz", "dk", "ee", "fi", "fr", "de", "gr", "hu", "ie", "it", "lv", "lt", "lu", "mt", "nl", "pl", "pt", "ro", "sk", "si", "es", "se", "al", "ad", "am", "by", "ba", "fo", "ge", "gi", "is", "im", "xk", "li", "mk", "md", "mc", "me", "no", "sm", "rs", "ch", "tr", "ua", "gb", "va" ], "default": "at" }, "_DocumentScreenConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Determines whether the document screen is enabled.", "default": true }, "fullScreen": { "type": "boolean", "description": "Displays the document screen in full-screen mode if enabled.", "default": false }, "mandatoryScrolling": { "type": "boolean", "description": "Forces mandatory scrolling through the document.", "default": false } }, "description": "Settings for the document screen.\n" }, "_WelcomeScreenConfiguration": { "allOf": [ { "$ref": "#/components/schemas/_BaseScreenConfiguration" }, { "type": "object", "properties": { "showDocumentBtn": { "type": "boolean", "description": "Determines whether a button to preview the document is shown.", "default": true } }, "additionalProperties": false } ], "description": "Settings for the welcome screen.\n" }, "FastlaneProfileGetResponse": { "title": "Fastlane Profile Get Response", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the profile", "example": "54f82188-7461-48fe-882c-afbf98256b16" }, "name": { "type": "string", "description": "Name of the profile", "example": "Signing screen with custom email" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the profile was created", "example": "2024-10-02T08:21:53.305Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the profile was last updated", "example": "2024-10-02T08:21:53.305Z" }, "configuration": { "$ref": "#/components/schemas/_FastlaneConfiguration" } } }, "FastlaneProfileListResponse": { "title": "Fastlane Profile List Response", "type": "array", "description": "JSON array of Fastlane profiles returned by GET /fastlane (one object per profile, same shape as FastlaneProfileGetResponse / a single-profile GET).\n", "items": { "$ref": "#/components/schemas/FastlaneProfileGetResponse" } }, "CreateFastlaneProfileResponse": { "title": "Create Fastlane Profile Response", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the profile", "example": "54f82188-7461-48fe-882c-afbf98256b16" }, "name": { "type": "string", "description": "Name of the profile", "example": "Signing screen with custom email" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the profile was created", "example": "2024-10-02T08:21:53.305Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the profile was last updated", "example": "2024-10-02T08:21:53.305Z" }, "configuration": { "$ref": "#/components/schemas/_FastlaneConfiguration" } } }, "SignBatchRequest": { "title": "Sign Batch Request", "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email of the member from the stack you want to sign (only QES)" } } }, "SignStackResponse": { "title": "Sign Stack Response", "type": "string", "example": "done" }, "_AddToStackRequestBody": { "title": "Add to Stack Request Body", "type": "object", "required": [ "token", "memberId" ], "properties": { "token": { "description": "Token for authentication", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "type": "string" }, "memberId": { "description": "MemberId of the user for this document", "type": "string" }, "signature": { "description": "Base64 Encoded PNG File which represents the signature or seal, if a custom image is desired", "type": "string", "example": null }, "page": { "description": "Page number, starting at 0, default is last page of document", "default": null, "type": "number" }, "x": { "description": "x coordinate of the signatures' top left position", "type": "number", "minimum": 0, "maximum": 1, "default": 0.7 }, "y": { "description": "y coordinate of the signatures' top left position", "type": "number", "minimum": 0, "maximum": 1, "default": 0.9 }, "width": { "description": "width of the signature", "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 }, "height": { "description": "height of the signature", "type": "number", "minimum": 0, "maximum": 1, "default": 0.1 }, "signatureType": { "description": "Type of the signature", "type": "string", "enum": [ "aes_sproof", "qes_sproof" ], "default": "qes_sproof" } } }, "_ErrorResponse": { "title": "Error Response", "type": "object", "description": "Standard error response object", "properties": { "message": { "type": "string", "description": "General or specific error message", "example": "Example error message" }, "traceId": { "type": "string", "description": "Trace ID - Provide this to the sproof support team to help them debug the issue", "example": "db89cb064945cea8c361aca3638e05d3" } } }, "AddToStackResponse": { "title": "Add to Stack Response", "type": "object", "properties": { "status": { "type": "string", "example": "added" } } } }, "parameters": {} }, "paths": { "/user/pendingSignatures": { "post": { "tags": [ "Stack" ], "summary": "Add document to stack", "description": "Adds a document to a given user's stack. Users must be in the same userplan, a default signature card image includes the name, company name and logo if available, and timestamp", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddToStackResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_AddToStackRequestBody" } } }, "description": "Add document to stack Body", "required": true } } }, "/documents/user/signBatch": { "post": { "tags": [ "Stack" ], "summary": "Sign a user's stack", "description": "Sign the stack of a given user. Users must be in the same userplan", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignStackResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SignBatchRequest" } } } } } }, "/fastlane": { "post": { "tags": [ "Fastlane" ], "summary": "Create profile", "description": "This endpoint allows you to create a new Fastlane profile with customizable screens. A valid authentication token is required to create the profile.\n### Welcome Screen ![Welcome Screen](../img/welcome_screen.png)\n### Document Screen ![Document Screen](../img/document_screen.png)\n### Provider Screen ![Provider Screen](../img/provider_screen.png)\n### Sign Screen ![Sign Screen](../img/sign_screen.png)\n### End Screen ![End Screen](../img/end_screen.png)\n", "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_FastlaneConfiguration" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFastlaneProfileResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "Your plan does not allow {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "Your plan does not allow {{element}}", "value": { "message": "Your plan does not allow {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "get": { "tags": [ "Fastlane" ], "summary": "List profiles", "description": "Retrieve a list of Fastlane profiles with optional sorting and search query filters.", "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sorting criteria for listing profiles. Use the format `field:order`, where `field` is the profile attribute (e.g., `name`, `createdAt`) and `order` is either `true` for ascending or `false` for descending.\nExample: `name:true` for ascending sort by name, or `createdAt:false` for descending sort by creation date.\n", "required": false, "schema": { "type": "string" }, "example": "name:true" }, { "name": "query", "in": "query", "description": "Optional search query to filter profiles by name or other attributes. This query allows you to search for specific profiles that match the provided keyword.\n", "required": false, "schema": { "type": "string" }, "example": "Custom signing flow" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastlaneProfileListResponse" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/fastlane/custom/{planId}/{customId}": { "get": { "tags": [ "Fastlane" ], "summary": "Open Document Custom Id", "description": "This endpoint allows you to open a sent out document using a previously defined custom ID.\n", "parameters": [ { "name": "planId", "in": "path", "description": "Valid Plan identifier associated with an active user plan (contact discord or support for your PlanId).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "ce410b60-7966-4d96-b523-013b9b2b7cbb" }, { "name": "customId", "in": "path", "description": "customId that was used in the createSignatureRequest", "required": true, "schema": { "type": "string" }, "example": "d46b68b53d2bef3025fd21a0737b0cd7425b1270b0115f39dafa46131023247cd46e7f" } ], "responses": { "200": { "description": "Redirects to the sproof Fastlane" }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/fastlane/{id}": { "get": { "tags": [ "Fastlane" ], "summary": "Get profile", "description": "This endpoint allows you to get information about a Fastlane profile. Both the profile ID and an authentication token are required for access.\n", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the Fastlane profile to get.", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastlaneProfileGetResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "put": { "tags": [ "Fastlane" ], "summary": "Update profile", "description": "Update an existing profile with customizable screens.", "parameters": [ { "name": "id", "in": "path", "description": "ID of the profile to update", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_FastlaneConfiguration" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFastlaneProfileResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "delete": { "tags": [ "Fastlane" ], "summary": "Delete profile", "description": "Delete an existing profile using its ID and and authentication token.", "parameters": [ { "name": "id", "in": "path", "description": "ID of the profile to delete", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profiles successfully deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFastlaneProfileResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/fastlane/{id}/set": { "post": { "tags": [ "Fastlane" ], "summary": "Add profile to document", "description": "Adds an existing Fastlane profile to an already sent out document or multiple documents by providing a list of admin memberIds.\n", "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique identifier of the Fastlane profile\n", "required": true, "example": "54f82188-7461-48fe-882c-afbf98256b16", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProfileToDocumentRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProfileToDocumentResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/fastlane/{id}/remove": { "post": { "tags": [ "Fastlane" ], "summary": "Remove profile from document", "description": "Removes a specified Fastlane profile from a document.", "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "example": "54f82188-7461-48fe-882c-afbf98256b16", "description": "The unique identifier of the Fastlane profile", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_RemoveFastlaneProfileRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveProfileFromDocumentResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/fastlane/batch": { "post": { "tags": [ "Fastlane" ], "summary": "Delete profiles", "description": "Deletes multiple profiles based on the provided profile IDs.", "parameters": [ { "name": "token", "in": "query", "description": "Authentication token required to delete the profiles", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_BatchDeleteRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_BatchDeleteResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/signature": { "post": { "summary": "New: Create signature request", "description": "This is the new create signature request. In addition to creating a single document invitation, it now supports creating envelopes and uploading multiple documents at once when sending invitations.", "operationId": "createSignatureRequest", "callbacks": { "createSignatureRequestCallback": { "{$request.body#/envelopeData/callbackUrl}": { "post": { "summary": "New Signature added", "description": "A POST request is sent to the `callbackUrl` defined in the [Create signature request](#operation/createSignatureRequest) every time a new signature is added to the document.", "responses": { "200": { "description": "Callback successfully processed and no retries will be performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } } } } } } }, "tags": [ "Signatures" ], "requestBody": { "description": "Body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSignatureRequest" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "402": { "description": "Please upgrade your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_402_01": { "summary": "Please upgrade your plan", "value": { "message": "Please upgrade your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "At least one customId already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "At least one customId already exists", "value": { "message": "At least one customId already exists", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents": { "get": { "tags": [ "Documents" ], "summary": "Get documents", "description": "Returns documents created by the **API token holder** (authenticated user), regardless of whether those documents were created through the UI or via the API.\n\nDocuments created by **other members** of the same plan are not included. When **role management** is enabled for your plan, each user can have their own API token.\n", "operationId": "getDocumentList", "parameters": [ { "name": "token", "in": "query", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of entries per page", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "view", "in": "query", "description": "Document filter", "required": false, "schema": { "type": "string", "default": "allDocuments", "enum": [ "allDocuments", "completedDocuments", "createdIncompleteDocuments", "incompleteDocuments", "createdDocuments", "draftDocuments", "envelopeDocuments", "invitedDocuments", "declinedDocuments", "pendingInvitations", "openInvitedDocuments", "openInvitedToApproveDocuments", "openInvitedToViewDocuments", "openInvitedToSignDocuments", "openPositionedDocuments", "stackedDocuments", "templates", "derivedFromTemplates" ] } }, { "name": "sort", "in": "query", "description": "Document sorting. Append \":true\" for descending sorting.", "required": false, "schema": { "type": "string", "default": "createdAt", "enum": [ "createdAt", "name" ] } }, { "name": "query", "in": "query", "description": "Search query for various information.\n\nBehavior:\n- Generally case-insensitive\n- Single word or quoted phrase (e.g. \"Quarterly Report\") performs substring match\n- Multiple words separated by spaces (e.g. quarterly report Q1) must all match as substrings (AND condition)\n- Fields searched: document name, member emails, member first/last names, folder name\n- Wildcards/regex are not supported\n- If the internal search index is not updated yet, only the document name is searched\n", "required": false, "schema": { "type": "string" } }, { "name": "labels", "in": "query", "description": "Filter by label name", "required": false, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Filters the results starting from a specific **createdAt** date and time in UTC format (does **not** filter by **updatedAt**). Use this parameter in combination with 'endDate' to define a time range.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-08-20T12:00:00Z" } }, { "name": "endDate", "in": "query", "description": "Filters the results ending at a specific **createdAt** date and time in UTC format (does **not** filter by **updatedAt**). Use this parameter in combination with 'startDate' to define a time range.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-08-21T18:24:29Z" } } ], "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_DocumentListResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "post": { "tags": [ "Signatures" ], "summary": "Legacy: Create signature request", "description": "This is the **legacy** create signature request. It is maintained for backward compatibility and may not support the latest features. \n_Consider using the [NEW create signature request](#operation/createSignatureRequest) for enhanced functionality!_\n", "operationId": "legacyCreateSignatureRequest", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_Document" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_03": { "summary": "The provided data is invalid", "value": { "message": "The provided data is invalid", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "402": { "description": "Please upgrade your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_402_01": { "summary": "Please upgrade your plan", "value": { "message": "Please upgrade your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "Your plan does not allow {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "Your plan does not allow {{element}}", "value": { "message": "Your plan does not allow {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "Email is already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "Email is already in use", "value": { "message": "Email is already in use", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "422": { "description": "The provided data is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_422_01": { "summary": "The provided data is invalid", "value": { "message": "The provided data is invalid", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "callbacks": { "newSignature": { "{$request.body#/callbackUrl}": { "post": { "summary": "New Signature added", "description": "A POST request is sent to the `callbackUrl` defined in the [Create signature request](#operation/createSignatureRequest) every time a new signature is added to the document.", "responses": { "200": { "description": "Callback successfully processed and no retries will be performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_Document" } } } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_SignatureRequestBody" } } }, "description": "Body", "required": true } } }, "/documents/{memberId}/fda": { "get": { "tags": [ "Documents" ], "summary": "Download Audit Trail", "description": "Get the audit trail of a document.", "operationId": "getPdfFda", "security": [], "responses": { "200": { "description": "successful operation", "content": { "text/plain": { "schema": { "type": "string", "description": "Base64 encoded PDF audit trail" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "memberId", "in": "path", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3", "description": "Member ID", "required": true, "schema": { "type": "string" } } ] } }, "/documents/download/{memberId}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Get signed document as binary or Base64-encoded string.", "operationId": "getDocument", "security": [], "parameters": [ { "name": "memberId", "in": "path", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3", "description": "Member ID", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Specifies the response format. Use `pdf` for binary PDF and `base64` for a Base64-encoded response.\nExample `base64` response: ```json {\n \"base64\": \"JVBERi0xLjQKJe...\"\n} ```\n", "example": "pdf", "required": false, "schema": { "type": "string", "enum": [ "pdf", "base64" ], "default": "pdf" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/verify": { "post": { "tags": [ "Documents" ], "summary": "Verify Document", "description": "Validates the signatures on a document. Our signature verification follows the ETSI standard. Further details can be found at https://www.etsi.org/deliver/etsi_ts/102800_102899/102853/01.01.02_60/ts_102853v010102p.pdf\n\nThe API token can be provided either in the request body or as a query parameter.\n", "operationId": "postVerify", "security": [], "parameters": [ { "name": "token", "in": "query", "description": "Token for authentication (e.g. your API key). Can be provided here or in the request body.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Base64 encoded file (PDF) and optional API token", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDocumentRequest" } } } }, "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_SignatureValidationResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "The provided data is invalid", "value": { "message": "The provided data is invalid", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "422": { "description": "The provided data is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_422_01": { "summary": "The provided data is invalid", "value": { "message": "The provided data is invalid", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/folder": { "get": { "tags": [ "Envelopes" ], "summary": "Get envelopes", "description": "Get a list of envelopes created or invited with your API key.", "operationId": "getFolders", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_FolderListResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Token for authentication (e.g. your API key)", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ] }, "post": { "tags": [ "Envelopes" ], "summary": "Create envelope", "description": "Creates an envelope with the given documents.", "operationId": "createFolder", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_CreateFolderRequest" } } } } } }, "/folder/{folderId}": { "get": { "tags": [ "Envelopes" ], "summary": "Get envelope", "description": "Get the envelope information such as documents or members.", "operationId": "getFolder", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_FolderResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the requested envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "required": true, "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Envelopes" ], "summary": "Delete envelope", "description": "Delete an envelope with all the documents inside.", "operationId": "deleteFolder", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFolderResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ] }, "put": { "tags": [ "Envelopes" ], "summary": "Update envelope", "description": "Updates the envelope name.", "operationId": "updateFolder", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_UpdateFolderRequest" } } } } } }, "/folder/{folderId}/documents": { "post": { "tags": [ "Envelopes" ], "summary": "Remove documents", "description": "Remove the specified documents from a draft envelope. If no documents are left in the envelope, the envelope is deleted.", "operationId": "deleteFolderDocs", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFolderDocumentsResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_DeleteFolderDocumentsRequest" } } } } }, "put": { "tags": [ "Envelopes" ], "summary": "Add documents", "description": "Add the given Documents to the envelope.", "operationId": "addFolderDocs", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFolderDocumentsResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_AddFolderDocumentsRequest" } } } } } }, "/folder/{folderId}/invite": { "post": { "tags": [ "Envelopes" ], "summary": "Add user", "description": "Invite a user to a given envelope.", "operationId": "inviteFolder", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "folderId", "in": "path", "description": "ID of the envelope", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_FolderRequestBody" } } }, "description": "Body", "required": true } } }, "/documents/{memberId}": { "get": { "tags": [ "Signatures" ], "summary": "Get request status", "description": "Get the status of a signature request. Returns a document JSON object or an error. The parameter is returned by the post request on document and is associated with the senders email.", "operationId": "getSignatureStatus", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_Document" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An internal database error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An internal database error occurred", "value": { "message": "An internal database error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "memberId", "in": "path", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3", "description": "Member ID", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ] }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a document or removes a member's access to it, depending on whether the\nprovided `memberId` belongs to the sender or a recipient, and whether the document\nis part of an envelope.\n\n**Documents in an envelope**\n\nThe query parameter `all` has no effect for documents in an envelope.\n\nWith the sender `memberId`:\n- A single document is deleted for the sender and all recipients.\n- The document is removed from the envelope.\n\nWith the recipient `memberId`:\n- All documents in the envelope are removed for the recipient.\n- The recipient is marked as `declined` on all documents that were deleted for the recipient.\n- The documents remain available for all other members on the document.\n\n**Single documents**\n\nWith the sender `memberId` and `all=true`:\n- The document is deleted for the sender and all recipients.\n\nWith the sender `memberId` and `all=false`:\n- The document is deleted only for the sender.\n- The document remains available for the other recipients on the document.\n\nWith the recipient `memberId`:\n- The recipient is marked as `declined` on the document.\n- The document remains available for all other members on the document.", "operationId": "deleteDocument", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentResponse" }, "examples": { "deletedSingleDocument": { "summary": "Single document deleted", "value": "deleted single document" }, "deletedFolder": { "summary": "Envelope deletion handled", "value": "deleted folder" } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "memberId", "in": "path", "example": "0dd4a4718ad3669c7133a615d955b4a89f5f11452de55d21d7ca0fff859a08c698b5a3", "description": "Member ID", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "Only relevant for single documents when the provided `memberId` belongs to the sender. If set to `true`, the document is deleted for the sender and all recipients. If set to `false`, the document is deleted only for the sender and remains available for the other recipients. This parameter has no effect for documents in an envelope (default = `true`) or when the provided `memberId` belongs to a recipient.", "required": false, "schema": { "type": "boolean", "default": false } } ] } }, "/documents/auto/sign": { "post": { "tags": [ "Signatures" ], "summary": "Seal document", "description": "Returns a JSON object of the signed Base64 document including a signature verification object, or an error.", "operationId": "signDocument", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_DocumentResponseBody" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "402": { "description": "Please upgrade your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_402_01": { "summary": "Please upgrade your plan", "value": { "message": "Please upgrade your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "Your Plan expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "Your Plan expired", "value": { "message": "Your Plan expired", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "500": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_500_01": { "summary": "An unknown error occurred", "value": { "message": "An unknown error occurred", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_DocumentRequestBody" } } }, "description": "Body", "required": true } } }, "/plans/members/{email}": { "get": { "tags": [ "Members" ], "summary": "Legacy - Get plan member", "description": "Legacy - Get a single plan member by email, new endpoint is /plans/planmembers/{email}", "operationId": "getPlanMember", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_PlanMember" } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "path", "description": "Email of the member", "required": true, "schema": { "type": "string" } } ] } }, "/plans/members": { "get": { "tags": [ "Members" ], "summary": "Legacy - Get plan members", "description": "Legacy - Get a list of all plan members, new endpoint is /plans/planmembers", "operationId": "getPlanMembers", "security": [], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/_PlanMember" } } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to use this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to use this {{element}}", "value": { "message": "You do not have permissions to use this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "Your Plan expired", "value": { "message": "Your Plan expired", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } } ] } }, "/plans/qualifiedMembers": { "post": { "tags": [ "Members" ], "summary": "Legacy - Create qualified plan member", "description": "Legacy - Create a qualified plan member. New endpoint is /plans/planmembers", "operationId": "createQualifiedMember", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQualifiedMemberResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "Your domain is not verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "Your domain is not verified", "value": { "message": "Your domain is not verified", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "This user can not be added", "value": { "message": "This user can not be added", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_03": { "summary": "{{element}} limit reached", "value": { "message": "{{element}} limit reached", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_04": { "summary": "You can not add a qualified member who is not part of your plan", "value": { "message": "You can not add a qualified member who is not part of your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_05": { "summary": "This user is already a qualified member of your plan", "value": { "message": "This user is already a qualified member of your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_QualifiedMemberRequestObject" } } }, "description": "Body", "required": true } } }, "/plans/qualifiedMembers/{email}": { "delete": { "tags": [ "Members" ], "summary": "Legacy - Delete qualified plan member", "description": "Legacy - Delete a qualified plan member. New endpoint is /plans/planmembers/{email} Delete a qualified plan member. Returns a JSON object, or an error. The boolean isDeleted is returned in case that the qualified member will be deleted. In case that the qualified member is blocked the member object is returned.", "operationId": "deleteQualifiedMember", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteQualifiedMemberResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to use this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to use this {{element}}", "value": { "message": "You do not have permissions to use this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "Your Plan expired", "value": { "message": "Your Plan expired", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "You must transfer ownership before this member can be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "You must transfer ownership before this member can be deleted", "value": { "message": "You must transfer ownership before this member can be deleted", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } }, "parameters": [ { "name": "token", "in": "query", "description": "Valid API-Token associated with an active user plan.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "path", "description": "Email of the member", "required": true, "schema": { "type": "string" } } ] } }, "/documents/prepare": { "post": { "summary": "Prepare signature request", "description": "Creates a signature request with all recipient information stored in the document state. This does not send invitation emails to recipients. This creates a **draft document** that can be processed later to send invitations. The request body format is identical to the /signature endpoint, and the response format is also the same, but no recipients are actually invited. You can use the the member id of any document in the documents array to get the member details to create an editor link to complete invitation the signature request.", "operationId": "prepareSignatureRequest", "callbacks": { "createSignatureRequestCallback": { "{$request.body#/envelopeData/callbackUrl}": { "post": { "summary": "New Signature added", "description": "A POST request is sent to the `callbackUrl` defined in the [Create signature request](#operation/createSignatureRequest) every time a new signature is added to the document.", "responses": { "200": { "description": "Callback successfully processed and no retries will be performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } } } } } } }, "tags": [ "Signatures" ], "requestBody": { "description": "Signature request data (same format as /signature endpoint)", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSignatureRequest" } } } }, "responses": { "200": { "description": "Signature request prepared successfully (same format as /signature endpoint, but no recipients invited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareSignatureRequestResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "402": { "description": "Please upgrade your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_402_01": { "summary": "Please upgrade your plan", "value": { "message": "Please upgrade your plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "At least one customId already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "At least one customId already exists", "value": { "message": "At least one customId already exists", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/invite-recipients-with-workflow": { "post": { "summary": "Invite with workflow", "description": "This endpoint creates and sends a signature request by merging a dynamic document with a pre-configured workflow. Unlike the prepare endpoint, this immediately sends invitation emails to all recipients. The mapping works as follows:\n\n**Signature Placement:** You provide a document containing placeholder text (e.g., {{signer1}}). In the API request, you link a recipient to this specific text to define where they will sign.\n\n**Workflow Configuration:** The workflow contains recipient placeholders with pre-defined settings (such as signature type, signing round, or role). You link your API recipient to these settings using their positional index (starting at 1) from the workflow.\n\n**Invitation Settings:** The workflow also applies high-level configurations like due dates, invite messages, and reminder intervals.", "operationId": "inviteRecipientsToWorkflow", "callbacks": { "inviteRecipientsToWorkflowCallback": { "{$request.body#/callbackUrl}": { "post": { "summary": "New Signature added", "description": "A POST request is sent to the `callbackUrl` defined in the [Invite recipients to workflow](#operation/inviteRecipientsToWorkflow) request every time a new signature is added to the document.", "responses": { "200": { "description": "Callback successfully processed and no retries will be performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } } } } } } }, "tags": [ "Signatures with workflows" ], "requestBody": { "description": "Workflow signature request data including recipients and workflow configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRecipientsToWorkflowRequest" } } } }, "responses": { "200": { "description": "Signature request created and invitations sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRecipientsWithWorkflowResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_401_02": { "summary": "Token incorrect", "value": { "message": "Token incorrect", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/invite-recipients-with-workflow-envelope": { "post": { "summary": "Invite with workflow envelope", "description": "This endpoint creates and sends a multi-document envelope signature request from a workflow that contains multiple documents. You must provide one PDF per workflow document (in order) via `pdfs[]` and a `folderName`.", "operationId": "inviteRecipientsWithWorkflowEnvelope", "tags": [ "Signatures with workflows" ], "requestBody": { "description": "Workflow envelope request data including recipients and PDFs", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareEnvelopeWithWorkflowRequest" } } } }, "responses": { "200": { "description": "Envelope created and invitations sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeResponse" } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_401_02": { "summary": "Token incorrect", "value": { "message": "Token incorrect", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/prepare-recipients-with-workflow": { "post": { "summary": "Prepare with workflow", "description": "This endpoint prepares a **draft signature request** by merging a dynamic document with a pre-configured workflow. It allows reviewing signature positions and form fields before sending. The mapping works as follows:\n\n**Signature Placement:** You provide a document containing placeholder text (e.g., {{signer1}}). In the API request, you link a recipient to this specific text to define where they will sign.\n\n**Workflow Configuration:** The workflow contains recipient placeholders with pre-defined settings (such as signature type, signing round, or role). You link your API recipient to these settings using their positional index (starting at 1) from the workflow.\n\n**Invitation Settings:** The workflow also applies high-level configurations like due dates, invite messages, and reminder intervals.", "operationId": "prepareRecipientsWithWorkflow", "tags": [ "Signatures with workflows" ], "requestBody": { "description": "Workflow signature request data including recipients and workflow configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRecipientsToWorkflowRequest" } } } }, "responses": { "200": { "description": "Workflow signature request prepared successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrepareRecipientsWithWorkflowResponse" } } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_401_02": { "summary": "Token incorrect", "value": { "message": "Token incorrect", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/prepare-recipients-with-workflow-envelope": { "post": { "summary": "Prepare with workflow envelope", "description": "This endpoint prepares a multi-document envelope **draft** from a workflow that contains multiple documents. No invitations are sent. Returns one editor URL per created document.", "operationId": "prepareRecipientsWithWorkflowEnvelope", "tags": [ "Signatures with workflows" ], "requestBody": { "description": "Workflow envelope request data including recipients and PDFs", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareEnvelopeWithWorkflowRequest" } } } }, "responses": { "200": { "description": "Envelope prepared successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrepareRecipientsWithWorkflowResponse" } } } } }, "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_401_02": { "summary": "Token incorrect", "value": { "message": "Token incorrect", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/documents/{memberId}/pdfAuditTrail": { "get": { "summary": "Download Audit Trail PDF (binary)", "description": "Retrieves the audit trail for a document as a PDF file in binary format.", "operationId": "getAuditTrailPdf", "tags": [ "Documents" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The member ID of the document", "example": "13a3ce9b24fa5e87acee8c9743711d30488ca88f081e1f19cb753bf6776467fd44d29b" }, "required": true, "name": "memberId", "in": "path" }, { "schema": { "type": "string", "description": "Optional authentication token (API key) for API access. Can be provided as query parameter or in Authorization header.", "example": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "required": false, "name": "token", "in": "query" } ], "responses": { "200": { "description": "Binary PDF audit trail file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Binary PDF file data" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "Document not found for memberId {{memberId}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "Document not found for memberId {{memberId}}", "value": { "message": "Document not found for memberId {{memberId}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/plans/planmembers/": { "get": { "summary": "Get a single plan member by email", "description": "Returns a single plan member by their email address.", "operationId": "getPlanMember_v2", "tags": [ "Members" ], "parameters": [ { "schema": { "type": "string", "description": "Your api token, you can find it in the settings page of the administrator profile" }, "required": true, "description": "Your api token, you can find it in the settings page of the administrator profile", "name": "token", "in": "query" }, { "schema": { "type": "string", "description": "Email address of the member in your plan", "example": "max.mustermann@sproof.com" }, "required": true, "description": "Email address of the member in your plan", "name": "email", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "description": "If true, also delete the user account and all their data (documents, contacts, groups, workflows, templates). Only allowed for plan members with verified domains." }, "required": false, "description": "If true, also delete the user account and all their data (documents, contacts, groups, workflows, templates). Only allowed for plan members with verified domains.", "name": "deleteUser", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanMember" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "post": { "summary": "Add new plan member", "description": "Creates a new plan member. Handles user creation, plan assignment, and invitation logic. See error codes for edge cases.", "operationId": "createPlanMember", "tags": [ "Members" ], "requestBody": { "description": "Plan member creation payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanMemberRequest" } } } }, "responses": { "200": { "description": "Plan member created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanMember" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "This user can not be added", "value": { "message": "This user can not be added", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "Email is already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "Email is already in use", "value": { "message": "Email is already in use", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_409_02": { "summary": "User already added to plan", "value": { "message": "User already added to plan", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "put": { "summary": "Update plan member", "description": "Updates a plan member. Use to update member details, block/unblock a member, or upgrade/downgrade userPlus status.", "operationId": "updatePlanMember", "tags": [ "Members" ], "requestBody": { "description": "Plan member update payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanMemberRequest" } } } }, "responses": { "200": { "description": "Plan member updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanMember" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "{{element}} limit reached", "value": { "message": "{{element}} limit reached", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "delete": { "summary": "Delete plan member", "description": "Removes a member from the plan. Optionally, with the deleteUser parameter set to true, the user account and all their data (documents, contacts, groups, workflows, templates) can be also deleted. User deletion is only allowed for plan members whose email domain matches a verified domain in the plan.", "operationId": "deletePlanMember", "tags": [ "Members" ], "parameters": [ { "schema": { "type": "string", "description": "Your api token, you can find it in the settings page of the administrator profile" }, "required": true, "description": "Your api token, you can find it in the settings page of the administrator profile", "name": "token", "in": "query" }, { "schema": { "type": "string", "description": "Email address of the member in your plan", "example": "max.mustermann@sproof.com" }, "required": true, "description": "Email address of the member in your plan", "name": "email", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "description": "If true, also delete the user account and all their data (documents, contacts, groups, workflows, templates). Only allowed for plan members with verified domains." }, "required": false, "description": "If true, also delete the user account and all their data (documents, contacts, groups, workflows, templates). Only allowed for plan members with verified domains.", "name": "deleteUser", "in": "query" } ], "responses": { "200": { "description": "Plan member deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePlanMemberResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to use this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to use this {{element}}", "value": { "message": "You do not have permissions to use this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_02": { "summary": "You do not have permissions to {{element}}", "value": { "message": "You do not have permissions to {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_403_03": { "summary": "You do not have permissions to modify this {{element}}", "value": { "message": "You do not have permissions to modify this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "409": { "description": "You must transfer ownership before this member can be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_409_01": { "summary": "You must transfer ownership before this member can be deleted", "value": { "message": "You must transfer ownership before this member can be deleted", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/plans/planmembers/list": { "get": { "summary": "List all plan members, paginated and with filters", "description": "Returns a paginated list of all members for the current plan. Use filters to narrow down the results.", "operationId": "getPlanMembers_v2", "tags": [ "Members" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number for pagination" }, "required": false, "description": "Page number for pagination", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of items per page" }, "required": false, "description": "Number of items per page", "name": "perPage", "in": "query" }, { "schema": { "type": "string", "default": "", "description": "Search query for members, filter by email, firstName, lastName" }, "required": false, "description": "Search query for members, filter by email, firstName, lastName", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "blocked", "pending", "identified", "user", "userPlus" ], "description": "Filter criteria - only \"blocked\", \"pending\", \"identified\", \"user\" or \"userPlus\" are allowed" }, "required": false, "description": "Filter criteria - only \"blocked\", \"pending\", \"identified\", \"user\" or \"userPlus\" are allowed", "name": "filter", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Sorting parameter in format \"key:direction\". Valid keys: firstName, lastName, lastLoginAt, blockedAt, email. Valid directions: asc, desc" }, "required": false, "description": "Sorting parameter in format \"key:direction\". Valid keys: firstName, lastName, lastLoginAt, blockedAt, email. Valid directions: asc, desc", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "Your api token, you can find it in the settings page of the administrator profile" }, "required": true, "description": "Your api token, you can find it in the settings page of the administrator profile", "name": "token", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPlanMembersResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/ident": { "post": { "summary": "Create a new ident", "description": "Creates a new identity verification transaction (ident) and returns a unique URL for the end user.\n\n**Workflow:**\n1. Relying Party creates an ident with desired attributes (e.g., name, birthdate)\n2. API returns an `id` and unique `url`\n3. Relying Party shares the URL with their end user via email, QR code, etc.\n4. End user opens URL and completes verification using their preferred method (national eID, video ident, EUDI wallet)\n5. Upon completion, sproof Ident sends verification result to your `callback` webhook URL\n\n**Important - Account Configuration:**\nBefore you can create idents, your account must be configured with organization details (name, address, city, zip, country). If you receive error code 400019, please contact our support team to complete your account setup.\n\n**Key Parameters:**\n- `attributes`: Identity claims you need from the end user (e.g., given_name, birthdate)\n- `identTypes`: Available verification methods for the end user (eid, autoident, eudi)\n- `selectedAutoIdentProvider`: When using `autoident`, which vendor runs the flow: `fidentity` (default) or `shufti`\n- `deliveryMethod` and `identifier`: Required together as one of three shapes (`email` + recipient email, `sms` + phone number, or `qr` with optional label); see the generated request schema `oneOf` and discriminator `deliveryMethod` in Scalar\n- `callback`: Your webhook URL to receive completion notifications\n- `returnUrl`: (Optional) Where to redirect the end user after successful verification\n- `config`: (Optional) Customize the UI flow (welcome screen, end screen)\n- `brandingDomain`: (Optional) White-label the verification page with your domain", "tags": [ "Idents" ], "parameters": [ { "schema": { "type": "string", "description": "Your API key for authentication" }, "required": true, "description": "Your API key for authentication", "name": "X-API-Key", "in": "header" } ], "requestBody": { "description": "Ident creation data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdentRequest" } } } }, "responses": { "201": { "description": "Ident created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdentResponse" } } } }, "400": { "description": "Invalid format/content for parameter(s): {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Invalid format/content for parameter(s): {{parameter}}", "value": { "message": "Invalid format/content for parameter(s): {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_02": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_03": { "summary": "Plan is expired or required organization details (name, address, city, zip, country) are not configured", "value": { "message": "Plan is expired or required organization details (name, address, city, zip, country) are not configured", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_04": { "summary": "National provider selection is required when provider cannot be changed", "value": { "message": "National provider selection is required when provider cannot be changed", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_05": { "summary": "No branding found for the specified domain", "value": { "message": "No branding found for the specified domain", "traceId": "db89cb064945cea8c361aca3638e05d3" } }, "ex_400_06": { "summary": "Return URL is required when end step is disabled", "value": { "message": "Return URL is required when end step is disabled", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "Check your userplan - you do not have any identifications left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "Check your userplan - you do not have any identifications left", "value": { "message": "Check your userplan - you do not have any identifications left", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "get": { "summary": "Get all idents", "description": "Returns all identity verification transactions for your account with pagination support.\n\n**Filtering:**\n- Status values: `pending` (in progress), `success` (verified), `error` (failed)\n\n**Pagination:**\n- Default: 20 per page\n- Max: 100 per page\n- Use `offset` and `limit` query parameters", "tags": [ "Idents" ], "parameters": [ { "schema": { "type": "string", "description": "Your API key for authentication" }, "required": true, "description": "Your API key for authentication", "name": "X-API-Key", "in": "header" } ], "responses": { "200": { "description": "List of idents retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentListResponse" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to use this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to use this {{element}}", "value": { "message": "You do not have permissions to use this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/ident/{id}": { "get": { "summary": "Get ident by ID", "description": "Retrieves the full details of an identity verification transaction, including verified data if status is 'success'.\n\n**Response includes:**\n- `status`: Current state (pending, success, error)\n- `data`: Verified identity attributes returned by the provider (only present if status is 'success')\n- `attributes`: The attributes you originally requested\n- `config`, `metadata`: Your original configuration", "tags": [ "Idents" ], "parameters": [ { "schema": { "$ref": "#/components/schemas/Uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Your API key for authentication" }, "required": true, "description": "Your API key for authentication", "name": "X-API-Key", "in": "header" } ], "responses": { "200": { "description": "Ident retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentResponse" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } }, "delete": { "summary": "Delete ident by ID", "description": "Permanently deletes an identity verification transaction and all associated data.\n\n**Important:**\n- This action is irreversible\n- Deletes all verified identity data returned by the provider\n- Use for GDPR compliance or when data is no longer needed\n- Returns 404 if the ident doesn't exist or doesn't belong to your account", "tags": [ "Idents" ], "parameters": [ { "schema": { "$ref": "#/components/schemas/Uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Your API key for authentication" }, "required": true, "description": "Your API key for authentication", "name": "X-API-Key", "in": "header" } ], "responses": { "204": { "description": "Ident deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoContentResponse" } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } }, "/ident/{id}/media/{attribute}": { "get": { "summary": "Download ident media", "description": "Downloads a media file (image or PDF) for a specific ident attribute.\n\n **Supported attributes:**\n - `passport_portrait`: Photo from passport/ID document (image)\n - `signature_image`: Signature from the identity document (image)\n - `selfie_image`: Selfie from liveness verification (image, Fidentity only)\n - `id_document_image`: ID document scan (image; Fidentity; Shufti front, or front+back merged side-by-side when `additional_proof` exists)\n - `id_document_pdf`: PDF report of the identity verification (PDF, Fidentity only)\n\n **Response:**\n - Returns binary file data (image or PDF) with appropriate Content-Type header\n - Content-Disposition header allows inline viewing or download\n\n **Note:** Only attributes that were requested and successfully verified will have media available.", "tags": [ "Idents" ], "parameters": [ { "schema": { "$ref": "#/components/schemas/Uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "given_name", "family_name", "birthdate", "main_address", "nationality", "age_over_14", "age_over_16", "age_over_18", "age_over_21", "signature_image", "passport_data", "passport_portrait", "selfie_image", "id_document_image", "id_document_pdf" ] }, "required": true, "name": "attribute", "in": "path" }, { "schema": { "type": "string", "description": "Your API key for authentication" }, "required": true, "description": "Your API key for authentication", "name": "X-API-Key", "in": "header" } ], "responses": { "400": { "description": "Required parameter(s) not provided: {{parameter}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_400_01": { "summary": "Required parameter(s) not provided: {{parameter}}", "value": { "message": "Required parameter(s) not provided: {{parameter}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "401": { "description": "User authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_401_01": { "summary": "User authentication failed", "value": { "message": "User authentication failed", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "403": { "description": "You do not have permissions to access this {{element}}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_403_01": { "summary": "You do not have permissions to access this {{element}}", "value": { "message": "You do not have permissions to access this {{element}}", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } }, "404": { "description": "{{element}} not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ErrorResponse" }, "examples": { "ex_404_01": { "summary": "{{element}} not found", "value": { "message": "{{element}} not found", "traceId": "db89cb064945cea8c361aca3638e05d3" } } } } } } } } } } }