{ "openapi": "3.0.1", "info": { "title": "Doctavian", "version": "v1", "description": "Combined Doctavian OpenAPI specification." }, "servers": [ { "url": "https://api.doctavian.com" } ], "security": [ { "bearerAuth": [], "apiKeyHeader": [] }, { "bearerAuth": [], "apiKeyQuery": [] } ], "tags": [ { "name": "Limits" }, { "name": "Service" }, { "name": "Settings" }, { "name": "Status" }, { "name": "Summary" }, { "name": "User" }, { "name": "Data Source" }, { "name": "Data" }, { "name": "Document" }, { "name": "Option Value" }, { "name": "Document Request" }, { "name": "Document Solution Configuration" }, { "name": "Document Solution" }, { "name": "Document Template" }, { "name": "Template" }, { "name": "Comment" }, { "name": "Envelope" }, { "name": "Attachment" }, { "name": "AuditTrail" }, { "name": "Content" }, { "name": "Folder" }, { "name": "MFA" }, { "name": "Signature" }, { "name": "Auth" } ], "paths": { "/v1/common/limits/get": { "get": { "tags": [ "Limits" ], "summary": "Get metered-dimension limits", "description": "Returns the caller's metered-dimension limit configuration (subscription- and user-level, monthly and yearly).", "operationId": "common-limits-get", "parameters": [ { "name": "scope", "in": "query", "description": "Case-insensitive match against the allowed values below. An unrecognized value returns `INVALID_SCOPE_VALUE` (400).", "schema": { "enum": [ "Global", "User", "Subscription", "Account" ], "type": "string" } }, { "name": "application", "in": "query", "description": "Case-insensitive match against the allowed values below. An unrecognized value returns `INVALID_APPLICATION_VALUE` (400).", "schema": { "enum": [ "MDS", "MD", "MCLM", "MHCW", "MH" ], "type": "string" } }, { "name": "subscriptionId", "in": "query", "description": "If present, must be a GUID belonging to the caller; substitutes that subscription's context for the caller's own subscription. Otherwise the caller's own subscription context is used.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Raw dimension name from the database." }, "allocatedResources": { "type": "string", "description": "Human-readable display string, not a machine-parseable number — e.g. \"1000 per month\", \"500 per year\", \"250 per 2 years\", or \"Unlimited\". Clients needing the numeric limit should read subscriptionLimits/userLimits instead." }, "displayName": { "type": "string" }, "groups": { "type": "string", "description": "Comma-joined string of group names (e.g. \"Group A,Group B\") — NOT a JSON array, despite representing a list conceptually." }, "pricePerUnit": { "type": "number", "description": "Omitted from the response when null.", "format": "float", "nullable": true }, "subscriptionLimits": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_MONTH/*_USER_MONTH setting exists." }, "yearly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_YEAR/*_USER_YEAR setting exists." } } }, "userLimits": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_MONTH/*_USER_MONTH setting exists." }, "yearly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_YEAR/*_USER_YEAR setting exists." } } } }, "description": "One metered dimension's limit configuration, as returned inside the `settings` array of GET /common/limits/get.", "example": { "name": "ENVELOPES", "allocatedResources": "1000 per month", "displayName": "Envelopes Sent", "groups": "Signature,Core", "pricePerUnit": 0.05, "subscriptionLimits": { "monthly": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ENVELOPES_LIMIT_SUBSCRIPTION_MONTH", "value": "1000", "defaultValue": "500", "meta": { "application": "MH", "scope": { "name": "Subscription" }, "category": { "name": "Limits" }, "subCategory": { "name": "Envelopes" }, "group": { "key": "limits", "name": "Limits" } } } ], "yearly": [] }, "userLimits": { "monthly": [], "yearly": [] } } } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "settings": [ { "name": "ENVELOPES", "allocatedResources": "1000 per month", "displayName": "Envelopes Sent", "groups": "Signature,Core", "pricePerUnit": 0.05, "subscriptionLimits": { "monthly": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ENVELOPES_LIMIT_SUBSCRIPTION_MONTH", "value": "1000", "defaultValue": "500", "meta": { "application": "MH", "scope": { "name": "Subscription" }, "category": { "name": "Limits" }, "subCategory": { "name": "Envelopes" }, "group": { "key": "limits", "name": "Limits" } } } ], "yearly": [] }, "userLimits": { "monthly": [], "yearly": [] } } ] }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "Query parameter failed validation (`INVALID_APPLICATION_VALUE` or `INVALID_SCOPE_VALUE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "INVALID_SCOPE_VALUE", "message": "The provided scope value is not recognized.", "userMessage": "Invalid scope value provided." } ], "message": "The provided scope value is not recognized.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-limits-get", "origin": "" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-limits-get", "origin": "" } } } } } } }, "/v1/common/service/token": { "post": { "tags": [ "Service" ], "summary": "Issue a new encrypted service token", "description": "Issues a short-lived, encrypted bearer token for the already-authenticated caller.", "operationId": "common-service-token-post", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "Opaque, symmetrically-encrypted blob containing a newly-issued, \"Bearer \"-prefixed, Key-Vault-signed JWT. Not directly decodable by the client without the server-side decryption key. This is NOT wrapped in the GenericResponse envelope used elsewhere in this group." }, "example": "CfDJ8N3x...opaque-encrypted-token...==" } } }, "500": { "description": "Any failure during token generation — including an auth failure from the underlying token validation step — is caught uniformly and surfaced under this single generic code. Deliberately not documented as a range of specific auth error codes, since the masking is real code behavior, not a documentation gap to correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "TOKEN_GENERATION_FAILED", "message": "Failed to generate a service token.", "userMessage": "Something went wrong. Please contact support." } ], "message": "Failed to generate a service token.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-service-token-post", "origin": "" } } } } } } }, "/v1/common/settings/get": { "get": { "tags": [ "Settings" ], "summary": "Get visible setting definitions and values", "description": "Returns setting definitions with their current effective values, filtered to those the caller's role/scope permits.", "operationId": "common-settings-get", "parameters": [ { "name": "scope", "in": "query", "description": "Case-insensitive match against the allowed values below. An unrecognized value returns `INVALID_SCOPE_VALUE` (400).", "schema": { "enum": [ "Global", "User", "Subscription", "Account" ], "type": "string" } }, { "name": "application", "in": "query", "description": "Case-insensitive match against the allowed values below. An unrecognized value returns `INVALID_APPLICATION_VALUE` (400).", "schema": { "enum": [ "MDS", "MD", "MCLM", "MHCW", "MH" ], "type": "string" } }, { "name": "subscriptionId", "in": "query", "description": "If present, must be a GUID belonging to the caller; substitutes that subscription's context for the caller's own subscription. Otherwise the caller's own subscription context is used.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "value": { "type": "string" }, "defaultValue": { "type": "string" }, "type": { "type": "string", "description": "Free-form string describing the setting's value type." }, "icon": { "type": "string" }, "allowedValues": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } } }, "description": "Null (not an empty array) when the setting has no enumerated allowed values configured.", "nullable": true }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single setting definition with its current effective value, as returned by GET /common/settings/get.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ALLOWED_SIGNATURE_INPUT_METHOD", "label": "Allowed Signature Input Method", "description": "Controls which signature input methods are permitted.", "value": "Draw,Type", "defaultValue": "Draw,Type,Upload", "type": "string", "icon": "signature", "allowedValues": "", "meta": { "application": "MH", "scope": { "name": "Account" }, "category": { "name": "Signing" }, "subCategory": { "name": "Input" }, "group": { "key": "signing", "name": "Signing" } } } } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "settings": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ALLOWED_SIGNATURE_INPUT_METHOD", "label": "Allowed Signature Input Method", "description": "Controls which signature input methods are permitted.", "value": "Draw,Type", "defaultValue": "Draw,Type,Upload", "type": "string", "icon": "signature", "allowedValues": "", "meta": { "application": "MH", "scope": { "name": "Account" }, "category": { "name": "Signing" }, "subCategory": { "name": "Input" }, "group": { "key": "signing", "name": "Signing" } } } ] }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "Query parameter failed validation (`INVALID_APPLICATION_VALUE` or `INVALID_SCOPE_VALUE`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "INVALID_SCOPE_VALUE", "message": "The provided scope value is not recognized.", "userMessage": "Invalid scope value provided." } ], "message": "The provided scope value is not recognized.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-settings-get", "origin": "" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-settings-get", "origin": "" } } } } } } }, "/v1/common/settings/update": { "put": { "tags": [ "Settings" ], "summary": "Update one or more setting values", "description": "Applies a batch of setting writes. Each item is checked against the caller's role/scope permission and the per-setting validation rules before being persisted as a single batch.", "operationId": "common-settings-update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsRequestDto" }, "example": { "settings": [ { "settingDefinitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "settingScopeId": "5a2e7b10-8c3e-4a1a-9e3a-1f2b3c4d5e6f", "scope": "account", "value": "5", "entityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "enum": [ "Success" ], "type": "string", "description": "Plain literal success string — not an object." }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": "Success", "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "Validation failed for one or more settings in the batch. Possible codes: VALIDATION_ERROR, ENVELOPE_FIRST_REMINDER_DAYS_OUT_OF_RANGE, ENVELOPE_REPEATING_REMINDER_DAYS_OUT_OF_RANGE, ENVELOPE_EXPIRY_DAYS_TOO_LOW, ENVELOPE_EXPIRY_ALERT_DAYS_TOO_LOW, ENVELOPE_EXPIRY_ALERT_DAYS_EXCEEDS_EXPIRATION, NO_SIGNATURE_INPUT_METHOD, NO_DOCUMENT_SOURCE, INVALID_REDIRECT_AFTER_SIGNING_URL, INVALID_CONTACT_EMAIL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "INVALID_LIMIT_VALUE", "message": "Limit value must be a non-negative integer or blank.", "userMessage": "Please provide a valid limit value." } ], "message": "Limit value must be a non-negative integer or blank.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-settings-update", "origin": "" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller's role does not permit this write (`PERMISSION_DENIED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "UPDATE_SETTINGS_PERMISSION_DENIED", "message": "Caller is not permitted to update this setting.", "userMessage": "You do not have permission to update this setting." } ], "message": "Caller is not permitted to update this setting.", "statusCode": 403 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-settings-update", "origin": "" } } } }, "500": { "description": "Unexpected server error; the whole batch is rolled back if this occurs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "SETTING_UPDATE_FAILED", "message": "Failed to persist one or more settings.", "userMessage": "Something went wrong. Please contact support." } ], "message": "Failed to persist one or more settings.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-settings-update", "origin": "" } } } } } } }, "/v1/common/status": { "get": { "tags": [ "Status" ], "summary": "Health-ping placeholder", "description": "The only fully anonymous, unauthenticated operation in this group (AuthorizationLevel.Anonymous; never calls the custom bearer/JWT validation used by every other operation here). It is a genuine placeholder: no dependencies, no logic, always returns HTTP 200 with an empty string body as long as the Function host itself is up. Do not confuse this with the unrelated GET /common/diagnostic/status endpoint (not in this group), which uses the StatusResult model and requires standard auth. The APIM-level subscription-key gate (X-Api-Key / x-api-key) may still legitimately apply at the gateway regardless of this operation's own Anonymous auth level — that is a distinct layer from the Function's own (absent, here) auth check.", "operationId": "common-status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "enum": [ "" ], "type": "string", "description": "Always the literal empty string, as long as the Function host is up. No version info, no dependency health checks. This is NOT the StatusResult shape used by the unrelated /common/diagnostic/status endpoint." }, "example": "" } } } } } }, "/v1/common/summary": { "get": { "tags": [ "Summary" ], "summary": "Get a dashboard or self-service summary", "description": "Returns one of two response shapes, selected by the required `type` query parameter: `dashboard` returns per-caller envelope/task counts; `self-service` returns subscription/user/limit-breach aggregates the caller can administer.", "operationId": "common-summary", "parameters": [ { "name": "type", "in": "query", "description": "Matched case-insensitively against `dashboard`/`self-service`. A missing or unrecognized value returns `INVALID_SUMMARY_TYPE` (400).", "required": true, "schema": { "enum": [ "dashboard", "self-service" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "todo": { "type": "integer", "description": "Count of \"In Progress\" envelopes where the caller is the current/next signer.", "nullable": true }, "pending": { "type": "integer", "description": "\"In Progress\" envelopes waiting on someone else, or already completed by this signer.", "nullable": true }, "inbox": { "type": "integer", "description": "Envelopes not Draft/Deleted where the caller is next signer in order.", "nullable": true }, "expiring": { "type": "integer", "description": "\"In Progress\" envelopes expiring within [0, AlertDaysBeforeExpiry] days.", "nullable": true }, "completed": { "type": "integer", "description": "Envelopes with Status = 'Completed'.", "nullable": true }, "recentEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" } }, "description": "One row of the dashboard summary's recentEnvelopes list." }, "description": "Top 3, terminal-status envelopes owned by the caller, ordered by send date descending." }, "oldestTodoEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sendDate": { "type": "string", "format": "date-time" }, "userName": { "type": "string", "description": "Submitter's full name." }, "tid": { "type": "string", "description": "Transaction token GUID; may be absent/null if none exists for this envelope.", "format": "uuid", "nullable": true } }, "description": "One row of the dashboard summary's oldestTodoEnvelopes list." }, "description": "Top 5 oldest \"todo\" envelopes, ordered by send date ascending." }, "latestPendingEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "action": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "person": { "type": "string", "description": "Coalesced: submitter full name, else signer name, else literal \"N/A\"." } }, "description": "One row of the dashboard summary's latestPendingEnvelopes list (the latest audit event per pending envelope)." }, "description": "Top 5, latest audit event per pending envelope." } }, "description": "Response data for GET /common/summary?type=dashboard.", "example": { "todo": 3, "pending": 1, "inbox": 5, "expiring": 0, "completed": 42, "recentEnvelopes": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "NDA - Acme Corp", "status": "Completed" } ], "oldestTodoEnvelopes": [ { "id": "5a2e7b10-8c3e-4a1a-9e3a-1f2b3c4d5e6f", "name": "Vendor Agreement", "sendDate": "2026-06-01T12:00:00.0000000+00:00", "userName": "Jane Submitter", "tid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "latestPendingEnvelopes": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Offer Letter", "action": "Viewed", "timestamp": "2026-07-01T12:00:00.0000000+00:00", "person": "John Signer" } ] } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "todo": 3, "pending": 1, "inbox": 5, "expiring": 0, "completed": 42, "recentEnvelopes": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "NDA - Acme Corp", "status": "Completed" } ], "oldestTodoEnvelopes": [ { "id": "5a2e7b10-8c3e-4a1a-9e3a-1f2b3c4d5e6f", "name": "Vendor Agreement", "sendDate": "2026-06-01T12:00:00.0000000+00:00", "userName": "Jane Submitter", "tid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "latestPendingEnvelopes": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Offer Letter", "action": "Viewed", "timestamp": "2026-07-01T12:00:00.0000000+00:00", "person": "John Signer" } ] }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "The `type` query parameter was missing, empty, or did not match one of the two recognized literal values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "INVALID_SUMMARY_TYPE", "message": "The provided summary type is not recognized.", "userMessage": "Please provide a valid summary type." } ], "message": "The provided summary type is not recognized.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-summary", "origin": "" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-summary", "origin": "" } } } } } } }, "/v1/common/user/contact/create": { "post": { "tags": [ "User" ], "summary": "Create a user contact", "description": "Creates a contact owned by the calling user. `sharedWithAccount` is always derived from the caller's account settings; any value sent in the request body is ignored.", "operationId": "common-user-contact-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserContactCreateRequestDto" }, "example": { "name": "Jane Doe", "email": "jane.doe@example.com" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Absent from the response when false, rather than serialized as an explicit false (global WhenWritingDefault default-omission policy) — a missing key means false/not-shared, not \"unspecified\"." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; identifies the contact's owning user. Omitted when Guid.Empty.", "format": "uuid", "nullable": true } }, "description": "Response representation of a user contact.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "userContact": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "The caller's account is missing the ALLOW_CONTACT_SHARE setting required to derive sharedWithAccount on Create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Missing contact share setting.", "userMessage": "Please contact your administrator to complete account setup." } ], "message": "Missing contact share setting.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-create", "origin": "" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-create", "origin": "" } } } } } } }, "/v1/common/user/contact/{userContactId}/delete": { "delete": { "tags": [ "User" ], "summary": "Delete a user contact", "description": "Deletes a user contact owned by the calling user. Returns success even if no matching contact existed.", "operationId": "common-user-contact-delete", "parameters": [ { "name": "userContactId", "in": "path", "description": "GUID of the user contact. A non-GUID value returns a 400 with a different response shape than the standard error envelope.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "description": "Returned with HTTP 200 regardless of whether a matching contact existed and was deleted.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "message": "User contact successfully deleted." } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "userContact": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "message": "User contact successfully deleted." } }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "A non-GUID `userContactId` returns a 400 with a different response shape than the standard error envelope.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-delete", "origin": "" } } } } } } }, "/v1/common/user/contact/{userContactId}/get": { "get": { "tags": [ "User" ], "summary": "Get a user contact", "description": "Retrieves a single user contact by id.", "operationId": "common-user-contact-get", "parameters": [ { "name": "userContactId", "in": "path", "description": "GUID of the user contact. A non-GUID value returns a 400 with a different response shape than the standard error envelope.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Absent from the response when false, rather than serialized as an explicit false (global WhenWritingDefault default-omission policy) — a missing key means false/not-shared, not \"unspecified\"." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; identifies the contact's owning user. Omitted when Guid.Empty.", "format": "uuid", "nullable": true } }, "description": "Response representation of a user contact.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "userContact": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "A non-GUID `userContactId` returns a 400 with a different response shape than the standard error envelope.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-get", "origin": "" } } } } } } }, "/v1/common/user/contact/list": { "get": { "tags": [ "User" ], "summary": "List the caller's user contacts", "description": "Returns the caller's entire contact list in one response (no pagination, sorting, or filtering).", "operationId": "common-user-contact-list", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userContacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Absent from the response when false, rather than serialized as an explicit false (global WhenWritingDefault default-omission policy) — a missing key means false/not-shared, not \"unspecified\"." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; identifies the contact's owning user. Omitted when Guid.Empty.", "format": "uuid", "nullable": true } }, "description": "Response representation of a user contact.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "userContacts": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ] }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-list", "origin": "" } } } } } } }, "/v1/common/user/contact/{userContactId}/update": { "put": { "tags": [ "User" ], "summary": "Update a user contact", "description": "Updates a user contact owned by the calling user. `subscriptionUserId` and `id` are always taken from the caller's identity and the path, respectively; any values sent for them in the request body are ignored.", "operationId": "common-user-contact-update", "parameters": [ { "name": "userContactId", "in": "path", "description": "GUID of the user contact. A non-GUID value returns a 400 with a different response shape than the standard error envelope.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserContactUpdateRequestDto" }, "example": { "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Absent from the response when false, rather than serialized as an explicit false (global WhenWritingDefault default-omission policy) — a missing key means false/not-shared, not \"unspecified\"." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; identifies the contact's owning user. Omitted when Guid.Empty.", "format": "uuid", "nullable": true } }, "description": "Response representation of a user contact.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "userContact": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "400": { "description": "A non-GUID `userContactId` returns a 400 with a different response shape than the standard error envelope.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "FUNCTION_EXECUTION_ERROR", "message": "An unexpected error occurred while processing the request.", "userMessage": "Something went wrong. Please contact support." } ], "message": "An unexpected error occurred while processing the request.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-contact-update", "origin": "" } } } } } } }, "/v1/common/user/get": { "get": { "tags": [ "User" ], "summary": "Get the calling user's profile", "description": "Returns the calling user's profile and membership details.", "operationId": "common-user-get", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "description": "Absent from the response when false (global default-omission policy)." }, "roleId": { "type": "string", "format": "uuid" }, "userEmail": { "type": "string" }, "settings": { "type": "array", "items": { "type": "object", "properties": { "settingKey": { "type": "string" }, "value": { "type": "string" } }, "description": "Partial, best-effort shape of the caller's settings." }, "description": "Best-effort partial shape — only `settingKey`/`value` are confirmed populated." }, "userDetails": { "type": "object", "properties": { "scope": { "type": "integer" }, "level": { "type": "integer" } }, "description": "Raw role scope/level ordinals. Do not assume a specific integer-to-label mapping when consuming this." } }, "description": "Response data for GET /common/user/get. Note: startDate/endDate/isActive are read directly off the membership record (SubscriptionMembers), while fullName/userEmail/id/settings are read off its nested SubscriptionUser sub-object — two distinct nested objects on an external type, flattened here with no naming cue as to which sub-object each field originated from.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "startDate": "2025-01-01T12:00:00.0000000+00:00", "isActive": true, "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "userEmail": "jane.doe@example.com", "settings": [ { "settingKey": "ALLOW_CONTACT_SHARE", "value": "true" } ], "userDetails": { "scope": 1, "level": 1 } } } } }, "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header, unvalidated." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } } }, "example": { "result": { "data": { "user": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "startDate": "2025-01-01T12:00:00.0000000+00:00", "isActive": true, "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "userEmail": "jane.doe@example.com", "settings": [ { "settingKey": "ALLOW_CONTACT_SHARE", "value": "true" } ], "userDetails": { "scope": 1, "level": 1 } } }, "statusCode": 200, "message": "OK" }, "origin": "string", "dateTime": "string", "operationId": "string" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "403": { "description": "Caller is authenticated but not authorized to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "innerErrors": [ { "code": "GET_USER_FAILED", "message": "Failed to load the current user.", "userMessage": "Something went wrong. Please contact support." } ], "message": "Failed to load the current user.", "statusCode": 500 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "common-user-get", "origin": "" } } } } } } }, "/v1/documents/datasource/create": { "post": { "tags": [ "Data Source" ], "summary": "Data Source Create", "description": "Creates a new data source.", "operationId": "documents-data-source-create", "requestBody": { "description": "The DataSourceModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceModel" }, "example": { "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "loadMethod": "Storage" } } } }, "responses": { "200": { "description": "Data source created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "required": [ "name", "loadMethod" ], "type": "object", "properties": { "dataSourceGuid": { "type": "string", "description": "Unique identifier of the data source.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the data source. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the underlying source.", "format": "uuid", "nullable": true }, "query": { "type": "string", "description": "Optional free-form query used to fetch data. Stored as-is; its syntax depends on the chosen loadMethod and is interpreted downstream. This API does not validate the format beyond rejecting a blank/whitespace value when the field is supplied.", "nullable": true }, "variables": { "type": "string", "description": "Optional free-form variables associated with the query. Stored as-is and interpreted downstream. Must not be blank/whitespace when supplied.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How data is loaded. Required.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/datasource/{dataSourceGuid}/delete": { "delete": { "tags": [ "Data Source" ], "summary": "Data Source Delete", "description": "Soft-deletes a data source by its GUID.", "operationId": "documents-data-source-delete", "parameters": [ { "name": "dataSourceGuid", "in": "path", "description": "GUID of the data source to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } ], "responses": { "200": { "description": "Data source deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dataSourceGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "Data source deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "message": "Data source deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "message": "Data source deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/datasource/{dataSourceGuid}/get": { "get": { "tags": [ "Data Source" ], "summary": "Data Source Get", "description": "Retrieves a single data source by its GUID.", "operationId": "documents-data-source-get", "parameters": [ { "name": "dataSourceGuid", "in": "path", "description": "GUID of the data source.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } ], "responses": { "200": { "description": "Data source retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "required": [ "name", "loadMethod" ], "type": "object", "properties": { "dataSourceGuid": { "type": "string", "description": "Unique identifier of the data source.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the data source. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the underlying source.", "format": "uuid", "nullable": true }, "query": { "type": "string", "description": "Optional free-form query used to fetch data. Stored as-is; its syntax depends on the chosen loadMethod and is interpreted downstream. This API does not validate the format beyond rejecting a blank/whitespace value when the field is supplied.", "nullable": true }, "variables": { "type": "string", "description": "Optional free-form variables associated with the query. Stored as-is and interpreted downstream. Must not be blank/whitespace when supplied.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How data is loaded. Required.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/datasource/list": { "get": { "tags": [ "Data Source" ], "summary": "Data Source List", "description": "Returns a paginated, optionally filtered and sorted list of data sources.", "operationId": "documents-data-source-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of data sources retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dataSources": { "type": "array", "items": { "required": [ "name", "loadMethod" ], "type": "object", "properties": { "dataSourceGuid": { "type": "string", "description": "Unique identifier of the data source.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the data source. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the underlying source.", "format": "uuid", "nullable": true }, "query": { "type": "string", "description": "Optional free-form query used to fetch data. Stored as-is; its syntax depends on the chosen loadMethod and is interpreted downstream. This API does not validate the format beyond rejecting a blank/whitespace value when the field is supplied.", "nullable": true }, "variables": { "type": "string", "description": "Optional free-form variables associated with the query. Stored as-is and interpreted downstream. Must not be blank/whitespace when supplied.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How data is loaded. Required.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "dataSources": [ { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "dataSources": [ { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/datasource/{dataSourceGuid}/update": { "put": { "tags": [ "Data Source" ], "summary": "Data Source Update", "description": "Updates an existing data source.", "operationId": "documents-data-source-update", "parameters": [ { "name": "dataSourceGuid", "in": "path", "description": "GUID of the data source to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } ], "requestBody": { "description": "The DataSourceModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceModel" }, "example": { "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "loadMethod": "Storage" } } } }, "responses": { "200": { "description": "Data source updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "required": [ "name", "loadMethod" ], "type": "object", "properties": { "dataSourceGuid": { "type": "string", "description": "Unique identifier of the data source.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the data source. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the underlying source.", "format": "uuid", "nullable": true }, "query": { "type": "string", "description": "Optional free-form query used to fetch data. Stored as-is; its syntax depends on the chosen loadMethod and is interpreted downstream. This API does not validate the format beyond rejecting a blank/whitespace value when the field is supplied.", "nullable": true }, "variables": { "type": "string", "description": "Optional free-form variables associated with the query. Stored as-is and interpreted downstream. Must not be blank/whitespace when supplied.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How data is loaded. Required.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/data/upload": { "post": { "tags": [ "Data" ], "summary": "Data Upload", "description": "Uploads a structured JSON data file to Storage so it can be referenced as a data source in later requests (e.g. document generation). Two request shapes are accepted, selected by Content-Type: (1) multipart/form-data with one or more `.json` files; (2) a raw JSON body with Content-Type: application/json, stored as-is as an opaque blob. Uploaded data is automatically removed from Storage after the next document-generation request that consumes it, whether that request succeeds or fails — re-upload if you need it again. Max size is enforced at the gateway (20MB Production, 10MB Staging).", "operationId": "documents-data-upload", "parameters": [ { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Origin", "in": "header", "description": "Free-form caller-supplied origin identifier. Not validated; echoed back verbatim into the response envelope's origin field. Optional.", "schema": { "type": "string" }, "example": "https://app.mavenmule.com" }, { "name": "X-Storage-Type", "in": "header", "description": "Selects which storage container handles the request. This operation expects the value `document-data`.", "required": true, "schema": { "type": "string" }, "example": "document-data" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "array", "description": "One or more JSON data files to upload (multi-file capable — one blob per file). Accepted extension: .json only, validated by filename suffix, not by parsing content. Order is preserved in the response.", "required": true } }, "type": "object" } }, "application/json": { "schema": { "description": "Arbitrary JSON payload. Content-Type must be exactly application/json for this path to apply. The raw request body is stored as a single opaque blob (named data${guid}.json) with no shape/schema validation performed on it whatsoever — any well-formed or malformed JSON is accepted as-is." }, "example": { "customerId": "12345", "records": [ { "field": "value" } ] } } } }, "responses": { "201": { "description": "File(s) uploaded. Returns a storage id per file, usable as a data source in subsequent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSuccessResponse" }, "examples": { "formData": { "summary": "multipart/form-data upload", "value": { "result": { "data": { "files": [ { "id": "3f9a7c14-2b8e-4d6a-9f01-5c7e2a1b3d4e", "fileName": "customer-data.json" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } }, "jsonBody": { "summary": "raw application/json upload", "value": { "result": { "data": { "files": [ { "id": "8e2c4a91-1d3b-4f5a-9c7e-2b6d8a1f3e05", "fileName": "data$8e2c4a91-1d3b-4f5a-9c7e-2b6d8a1f3e05.json" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } }, "400": { "description": "Missing Content-Type header (VALIDATION_ERROR); a Content-Type other than exactly application/json combined with an empty/absent form body (FORM_DATA_EXPECTED); or a form-data file whose extension isn't .json (INVALID_DATA_FORMAT — note: extension-only check, file content is never parsed as JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 400, "message": "The file 'payload.xml' has an unsupported extension. Allowed: .json", "innerErrors": [ { "code": "INVALID_DATA_FORMAT", "message": "The file 'payload.xml' has an unsupported extension. Allowed: .json", "userMessage": "Only .json files can be uploaded here. Convert your data to .json and try again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be stored due to a server/storage error, or an unrecognized X-Storage-Type value. Real code: FILE_UPLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/documents/document/create": { "post": { "tags": [ "Document" ], "summary": "Document Create", "description": "Creates a new document.", "operationId": "documents-document-create", "requestBody": { "description": "The DocumentModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentModel" }, "example": { "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com" } } } }, "responses": { "200": { "description": "Document created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "required": [ "title", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentGuid": { "type": "string", "description": "Unique identifier of the document.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "title": { "type": "string", "description": "Document title. Required, must be non-empty.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the document file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the document file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the document file.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the document. Required.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the document is delivered. Required.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Anonymous view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Anonymous edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Authenticated-user view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Authenticated-user edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Organization view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Organization edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "succeededViewUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "succeededEditUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedViewUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedEditUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/{documentGuid}/delete": { "delete": { "tags": [ "Document" ], "summary": "Document Delete", "description": "Soft-deletes a document by its GUID.", "operationId": "documents-document-delete", "parameters": [ { "name": "documentGuid", "in": "path", "description": "GUID of the document to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "16fd2706-8baf-433b-82eb-8c7fada847da" } } ], "responses": { "200": { "description": "Document deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "Document deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "message": "Document deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "message": "Document deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/{documentId}/download": { "get": { "tags": [ "Document" ], "summary": "Document Download", "description": "Downloads a previously stored document by its storage id and returns the raw file as an octet-stream. The caller must own the file (ownership is verified against the stored subscription-user metadata). Use the id returned by an upload or by document generation delivered to Storage.", "operationId": "documents-download-document", "parameters": [ { "name": "documentId", "in": "path", "description": "Storage id (GUID) of the document to download, as returned by an upload or generation response.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Storage-Type", "in": "header", "description": "Container-type key used to look up the blob. Must match whichever container the file was originally uploaded to: document-data, document-template, or document-input. Not strictly enforced as a closed enum; an unrecognized value surfaces as a generic FILE_DOWNLOAD_FAILED.", "required": true, "schema": { "type": "string" }, "example": "document-data" } ], "responses": { "200": { "description": "Returns the stored document as a binary stream. The Content-Disposition file name and Content-Type reflect the stored file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "403": { "description": "The file exists but belongs to a different user. Real code: FILE_ACCESS_DENIED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 403, "message": "The requested file does not belong to the authenticated user.", "innerErrors": [ { "code": "FILE_ACCESS_DENIED", "message": "The requested file does not belong to the authenticated user.", "userMessage": "You don't have access to this file." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "404": { "description": "No file exists for the supplied id. Real code: NOT_FOUND_BY_ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 404, "message": "No file was found for the supplied id.", "innerErrors": [ { "code": "NOT_FOUND_BY_ID", "message": "No file was found for the supplied id.", "userMessage": "We couldn't find that file. Check the id and try again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be retrieved due to a server/storage error. Real code: FILE_DOWNLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to read the requested file from storage.", "innerErrors": [ { "code": "FILE_DOWNLOAD_FAILED", "message": "Failed to read the requested file from storage.", "userMessage": "Something went wrong while downloading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/documents/document/generate": { "post": { "tags": [ "Document" ], "summary": "Document Generate", "description": "This is an object representing a document request in the system. You can use this endpoint to generate documents (e.g. PDF, DOCX, XLSX) by specifying a template, providing the data to populate that template, and choosing where and how the final file should be delivered.
\n\nThe document output can be stored in Storage, Salesforce, or OneDrive, and may include advanced options like anonymous sharing, file ownership, and metadata tagging.
\n\nYou can also attach additional related templates, pass custom variables, and render dynamic content using GraphQL queries or stored data sources.
\n\nRelated guide: [Document Template Configuration](https://docs.mavenmule.com/maven-documents/elements-reference)", "operationId": "documents-post-documentsgenerate", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side. The JWT must contain the following claims:

\n**sub**: Current user session.
\n**Destination**: Path to which should be used to make a callback.
\n**full_name**: Name of the user that made the request.
\n**email**: The email address of the user that made the request.
\n**iss**: The issuer claim identifies the principal that issued the JWT. URL of the issuer.
\n**oid**: Object Id claim represents a unique Id of the user that made the request, for example in Salesforce case this will be User record Id.
\n**clientId**: Id representing the client. Eg OrgId.
\n**zoneInfo**: Zone information.
\n**locale**: Localization information.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription. The JWT must contain the following claims:

\n**amp_subscription**: The offering subscription key which is used to validate that the client has a valid license.
\n**full_name**: Name of the user that made the request.
\n**email**: The email address of the user that made the request.
\n**iss**: The issuer claim identifies the principal that issued the JWT. URL of the issuer.
\n**oid**: Object Id claim represents a unique Id of the user that made the request, for example in Salesforce case this will be User record Id.
\n**zoneInfo**: Zone information.
\n**locale**: Localization information.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "\n**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**template**
\nDefines the primary document template to be used for generating the document. It includes the template’s metadata, source, file format, and any related templates used during processing.\n\n**template.options**
\nProvides additional configuration for how the template is loaded or processed (e.g., preserving unsupported features or applying file-specific handling options).\n\n**template.relatedItems**
\nAn array of additional templates associated with the primary template. These may be appended or merged during document generation.\n\n---\n\n**data**
\nDefines the source of data and variables that populate the template's placeholders or fields. It includes the method of data retrieval (e.g., from storage, Salesforce, OneDrive) and any static or dynamic content used in the final document.\n\n**data.variables**
\nList of reusable name–value pairs injected into the data. Useful for passing static values, global variables, GraphQL expressions, or field formulas. \n**Note:** This section is should be reviewed by Tomislav and Ivan A.\n\n**data.embedded**
\nAn optional string providing inline key–value metadata pairs that may be embedded in the output file (e.g., in a PDF's metadata section).\n\n---\n\n**document**
\nDefines the configuration and metadata of the final generated document, including its name, locale, format, timezone, delivery method, and storage destination.\n\n**document.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**document.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.\n\n**document.options.googledrive**
\nSpecifies how the document will be shared or stored via Google Drive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "template": { "required": [ "urn", "fileFormat", "loadMethod" ], "type": "object", "properties": { "name": { "type": "string", "description": "Template name (as known in Storage, Salesforce, or OneDrive).", "default": "" }, "urn": { "type": "string", "description": "Template identifier. Can be a Storage key, Salesforce ContentVersion ID, or OneDrive file ID.", "default": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5" }, "fileFormat": { "enum": [ "docx", "xlsx" ], "type": "string", "description": "Template file format without dot (e.g., docx, xlsx).", "default": "xlsx" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the template where it is stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "options": { "type": "object", "properties": { "docxLoadOptions": { "type": "string", "description": "JSON string for DOCX load options, default \"{\\\"PreserveUnsupportedFeatures\\\": true}\".", "default": "{ \"PreserveUnsupportedFeatures\": true }" } } }, "relatedItems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the related template. Must match the name used in the root template.", "default": "" }, "urn": { "type": "string", "description": "Identifier of the related template, used to locate the file.", "default": "" }, "fileFormat": { "type": "string", "description": "Format of the related template file (e.g., docx, xlsx).", "default": "" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source system from which to load the related template (e.g., Storage, Salesforce, OneDrive).", "default": "" } } } } } }, "data": { "required": [ "urn", "loadMethod" ], "type": "object", "properties": { "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the data (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "urn": { "type": "string", "description": "Data identifier for the data source used to populate the template provided in the template URN (e.g., GraphQL endpoint, Storage key, OneDrive file ID).", "default": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Variable name (e.g., myExpressionField).", "default": "" }, "value": { "type": "string", "description": "Raw value or expression placeholder.", "default": "" }, "type": { "enum": [ "fieldExpression", "graphql", "global" ], "type": "string", "description": "Type of variable.", "default": "" } } } }, "query": { "type": "string", "description": "JSON-encoded GraphQL query, used if loadMethod is GraphQL.", "default": "" }, "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } }, "document": { "required": [ "timezone", "locale", "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "timezone": { "type": "string", "description": "Timezone used for date/time formatting.", "default": "(GMT+01:00) Central European Standard Time (Europe/Zagreb)" }, "locale": { "type": "string", "description": "Locale for language-specific formatting. Supported values follow the [Unicode CLDR Project](https://cldr.unicode.org/), such as [`en-GB`, `es-MX`, and others](https://github.com/unicode-org/cldr-json/tree/main/cldr-json/cldr-dates-full/main).", "default": "en_US_POSIX" }, "name": { "type": "string", "description": "Name of the generated document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "Format of the generated document (e.g., docx, xlsx, pdf).", "default": "pdf" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "docxSaveOptions": { "type": "string", "description": "JSON string for DOCX output customizations.", "default": "" }, "salesforce": { "type": "object", "properties": { "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "template": { "name": "Standard Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "fileFormat": "docx", "loadMethod": "Storage", "options": { "docxLoadOptions": "{ \"PreserveUnsupportedFeatures\": true }" }, "relatedItems": [ { "name": "Invoice Terms Addendum", "urn": "4b1e2f3a-5c6d-47e8-9a0b-1c2d3e4f5a6b", "fileFormat": "docx", "loadMethod": "Storage" } ] }, "data": { "loadMethod": "Storage", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "variables": [ { "name": "createdDate", "value": "{!$now()}", "type": "fieldExpression" }, { "name": "requestId", "value": "{!requestId}", "type": "graphql" }, { "name": "customerName", "value": "Jane Doe", "type": "global" } ], "query": "{\"query\":\"{Account {Name Description Owner.Username Id Opportunities {StageName OpportunityLineItems {Name}} Contacts {Id}}}\"}", "embedded": "key:value" }, "document": { "timezone": "(GMT+00:00) Greenwich Mean Time (Europe/Dublin)", "locale": "en_IE_EURO", "name": "Q3 Sales Report", "fileFormat": "docx", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "docxSaveOptions": "{}", "salesforce": { "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] }, "googleDrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] }, "googleGenerate": { "nativeMergeEnabled": true, "nativeImageMergeEnabled": true } } } } } } }, "responses": { "201": { "description": "This response indicates that the document was successfully generated and delivered using the specified deliveryMethod. It includes metadata about the generated document (such as name, format, and unique URN), usage metrics (e.g., pages generated), and contextual information useful for tracking and auditing the operation.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully created." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the generated document is stored." }, "name": { "type": "string", "description": "The name of the generated document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the generated document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the generated document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-generated", "documents-generated" ], "type": "string", "description": "The type of resource consumed (e.g., pages-generated, documents-generated)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document generation request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the document generation was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this generation operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report", "fileFormat": "docx", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report.docx" } } }, "consumption": [ { "dimension": "pages-generated", "value": 4 }, { "dimension": "documents-generated", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the request was invalid or improperly formed. It provides details about the error that occurred, including specific error codes, messages, and guidance for the user on how to resolve the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document generation request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/v1/documents/document/{documentGuid}/get": { "get": { "tags": [ "Document" ], "summary": "Document Get", "description": "Retrieves a single document by its GUID.", "operationId": "documents-document-get", "parameters": [ { "name": "documentGuid", "in": "path", "description": "GUID of the document.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "16fd2706-8baf-433b-82eb-8c7fada847da" } } ], "responses": { "200": { "description": "Document retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "required": [ "title", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentGuid": { "type": "string", "description": "Unique identifier of the document.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "title": { "type": "string", "description": "Document title. Required, must be non-empty.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the document file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the document file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the document file.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the document. Required.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the document is delivered. Required.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Anonymous view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Anonymous edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Authenticated-user view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Authenticated-user edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Organization view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Organization edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "succeededViewUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "succeededEditUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedViewUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedEditUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/list": { "get": { "tags": [ "Document" ], "summary": "Document List", "description": "Returns a paginated, optionally filtered and sorted list of documents.", "operationId": "documents-document-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of documents retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "required": [ "title", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentGuid": { "type": "string", "description": "Unique identifier of the document.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "title": { "type": "string", "description": "Document title. Required, must be non-empty.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the document file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the document file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the document file.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the document. Required.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the document is delivered. Required.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Anonymous view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Anonymous edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Authenticated-user view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Authenticated-user edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Organization view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Organization edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "succeededViewUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "succeededEditUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedViewUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedEditUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documents": [ { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documents": [ { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/manage": { "post": { "tags": [ "Document" ], "summary": "Document Manage", "description": "This endpoint performs external file operations on existing documents, such as copying, moving, deleting (currently only supports OneDrive), or converting documents, without modifying their internal content. It allows you to manage how and where documents are stored across supported platforms like Storage, Salesforce, and OneDrive.

\n**Copy**: If both source and target are provided in the payload, the document is duplicated from the source location to the target location. Requires the same fileFormat in both source and target document and source.remove must be \"none\".
\n**Move**: Transfers the document from the source to the target location with deletion from the source. Requires the same fileFormat in both source and target document and source.remove must be \"delete\" or \"permanentDelete\".
\n**Delete**: Deletes the specified document if only the source document is provided and source.remove is \"delete\" or \"permanentDelete\". Target document is not in the payload in this case.
\n**Convert**: Transforms the document format (e.g., docx → pdf, xlsx → pdf) while transferring it between same or different locations. Requires both source and target document with differing fileFormat values.", "operationId": "documents-post-documentmanage", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**sourceDocument**
\nIdentifies the input document and its properties, serving as the starting point for file operations like copying to a new location, moving with deletion, deleting outright, or converting to a different format.\n\n**sourceDocument.options**
\nFine-tunes the loading process for the source document to meet specific requirements, such as retaining formatting or handling special features during operations like copying or conversion.\n\n---\n\n**targetDocument**
\nDefines the properties of the output document resulting from the file operation (e.g., the destination for Copy, Move, or Convert operations). It specifies the document’s metadata, format, delivery method, storage location, and processing options, determining how the processed document is saved and managed. This node is omitted for Delete operations, as no output document is generated.\n\n**targetDocument.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**targetDocument.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "sourceDocument": { "required": [ "urn", "fileFormat", "loadMethod", "remove" ], "type": "object", "properties": { "urn": { "type": "string", "description": "URN of the source document stored in the system.", "default": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "File format of the source document (e.g., docx, xlsx, pdf).", "default": "xlsx" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the document where it is stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "remove": { "type": "string", "description": "Flag indicating whether to remove the source document (e.g., none, delete, permanentDelete)", "default": "none" }, "options": { "type": "object", "properties": { "docxLoadOptions": { "type": "string", "description": "JSON string for DOCX load options, default \"{\\\"PreserveUnsupportedFeatures\\\": true}\".", "default": "{ \"PreserveUnsupportedFeatures\": true }" } } } } }, "targetDocument": { "required": [ "name", "fileFormat", "deliveryMethod", "path" ], "type": "object", "properties": { "name": { "type": "string", "description": "Name of the target document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "Format of the generated document (e.g., docx, xlsx, pdf).", "default": "xlsx" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "docxSaveOptions": { "type": "string", "description": "JSON string for DOCX output customizations.", "default": "" }, "salesforce": { "type": "object", "properties": { "networkId": { "type": "string", "description": "ID of specific Salesforce Experience Cloud site or community where the generated document should be stored or associated.", "default": "" }, "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } }, "data": { "type": "object", "properties": { "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "sourceDocument": { "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "fileFormat": "docx", "loadMethod": "Storage", "remove": "none", "options": { "docxLoadOptions": "{ \"PreserveUnsupportedFeatures\": true }" } }, "targetDocument": { "name": "Q3 Sales Report - Archived", "fileFormat": "docx", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "docxSaveOptions": "{}", "salesforce": { "networkId": "0DMXYZ0000000AAAA", "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] } } }, "data": { "embedded": "key:value" } } } } }, "responses": { "201": { "description": "This response confirms that the document management operation (such as copy, move, delete, or convert) was successfully completed. It returns metadata about the resulting document, including its name, format, storage location, and URN. The response also includes consumption metrics indicating how many documents and pages were processed, which are relevant for billing or quotas.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully managed." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the managed document is stored." }, "name": { "type": "string", "description": "The name of the managed document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the managed document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the managed document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-managed", "documents-managed" ], "type": "string", "description": "The type of resource consumed (e.g., pages-managed, documents-managed)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the request was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report - Archived", "fileFormat": "docx", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report - Archived.docx" } } }, "consumption": [ { "dimension": "pages-managed", "value": 4 }, { "dimension": "documents-managed", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the request was malformed or invalid due to missing or unsupported parameters, such as an incorrect file format or improperly structured payload. It includes detailed error information with specific error codes, messages, and a user-friendly explanation to help diagnose the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document manage request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/v1/documents/document/manage/async": { "post": { "tags": [ "Document" ], "summary": "Document Manage Async", "description": "This endpoint allows you to initiate asynchronous document management operations, such as copying, moving, deleting (currently only supports OneDrive), or converting documents, across platforms like Storage, Salesforce, and OneDrive, without modifying their internal content. Unlike the synchronous version, it returns immediately and processes the requested operation in the background. The result can be tracked or received via promise or callback, depending on your integration setup. This approach is ideal for handling large files, slower systems, or when non-blocking execution is preferred.", "operationId": "documents-manage-async", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**sourceDocument**
\nIdentifies the input document and its properties, serving as the starting point for file operations like copying to a new location, moving with deletion, deleting outright, or converting to a different format.\n\n**sourceDocument.options**
\nFine-tunes the loading process for the source document to meet specific requirements, such as retaining formatting or handling special features during operations like copying or conversion.\n\n---\n\n**targetDocument**
\nDefines the properties of the output document resulting from the file operation (e.g., the destination for Copy, Move, or Convert operations). It specifies the document’s metadata, format, delivery method, storage location, and processing options, determining how the processed document is saved and managed. This node is omitted for Delete operations, as no output document is generated.\n\n**targetDocument.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**targetDocument.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.\n\n**document.options.googledrive**
\nSpecifies how the document will be shared or stored via Google Drive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "sourceDocument": { "required": [ "urn", "fileFormat", "loadMethod", "remove" ], "type": "object", "properties": { "urn": { "type": "string", "description": "URN of the source document stored in the system.", "default": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "File format of the source document (e.g., docx, xlsx, pdf).", "default": "xlsx" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the document where it is store (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "remove": { "type": "string", "description": "Flag indicating whether to remove the source document (e.g., none, delete, permanentDelete).", "default": "none" }, "options": { "type": "object", "properties": { "docxLoadOptions": { "type": "string", "description": "JSON string for DOCX load options, default \"{\\\"PreserveUnsupportedFeatures\\\": true}\".", "default": "{ \"PreserveUnsupportedFeatures\": true }" } } } } }, "targetDocument": { "required": [ "name", "fileFormat", "deliveryMethod", "path" ], "type": "object", "properties": { "name": { "type": "string", "description": "Name of the target document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "Format of the generated document (e.g., docx, xlsx, pdf).", "default": "xlsx" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "docxSaveOptions": { "type": "string", "description": "JSON string for DOCX output customizations.", "default": "" }, "salesforce": { "type": "object", "properties": { "networkId": { "type": "string", "description": "ID of specific Salesforce Experience Cloud site or community where the generated document should be stored or associated.", "default": "" }, "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } }, "data": { "type": "object", "properties": { "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "sourceDocument": { "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "fileFormat": "docx", "loadMethod": "Storage", "remove": "none", "options": { "docxLoadOptions": "{ \"PreserveUnsupportedFeatures\": true }" } }, "targetDocument": { "name": "Q3 Sales Report - Archived", "fileFormat": "docx", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "docxSaveOptions": "{}", "salesforce": { "networkId": "0DMXYZ0000000AAAA", "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] } } }, "data": { "embedded": "key:value" } } } } }, "responses": { "201": { "description": "This response confirms that the document management operation (such as copy, move, delete, or convert) was successfully completed. It returns metadata about the resulting document, including its name, format, storage location, and URN. The response also includes consumption metrics indicating how many documents and pages were processed, which are relevant for billing or quotas.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully managed." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the managed document is stored." }, "name": { "type": "string", "description": "The name of the managed document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the managed document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the managed document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-managed", "documents-managed" ], "type": "string", "description": "The type of resource consumed (e.g., pages-managed, documents-managed)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the document manage was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report - Archived", "fileFormat": "docx", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report - Archived.docx" } } }, "consumption": [ { "dimension": "pages-managed", "value": 4 }, { "dimension": "documents-managed", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the request was malformed or invalid due to missing or unsupported parameters, such as an incorrect file format or improperly structured payload. It includes detailed error information with specific error codes, messages, and a user-friendly explanation to help diagnose the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document manage request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/v1/documents/document/merge": { "post": { "tags": [ "Document" ], "summary": "Document Merge", "description": "This endpoint allows you to merge multiple PDF documents into a single consolidated PDF file, preserving the order you specify. The sequence of merged files is determined in the payload in each source document, and all source files must be in PDF format. The merged output can be stored in Storage, Salesforce, or OneDrive and source documents can optionally be removed from the source after merging.", "operationId": "documents-post-documentmerge", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**sourceDocuments**
\nIdentifies the input documents (e.g., Word, Excel, or PDF files) and their properties, serving as the inputs for the merge and conversion process to create a unified target document.\n\n---\n\n**targetDocument**
\nDefines the properties of the output document resulting from merging the source documents. It specifies the document’s metadata, format (typically PDF for merged outputs), delivery method, storage location, and processing options, determining how the merged document is saved and managed.\n\n**targetDocument.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**targetDocument.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "sourceDocuments": { "type": "array", "items": { "required": [ "urn", "fileFormat", "loadMethod", "remove" ], "type": "object", "properties": { "urn": { "type": "string", "description": "URN of the source document stored in the system.", "default": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70" }, "fileFormat": { "enum": [ "pdf" ], "type": "string", "description": "File format of the source document (e.g., pdf).", "default": "pdf" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the document where it is stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "order": { "type": "integer", "description": "Order in which the document should be merged.", "default": 1 }, "remove": { "type": "string", "description": "Flag indicating whether to remove the source document after merging (e.g., none, delete, permanentDelete).", "default": "none" } } } }, "targetDocument": { "required": [ "name", "fileFormat", "deliveryMethod", "path" ], "type": "object", "properties": { "name": { "type": "string", "description": "Name of the target document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "pdf" ], "type": "string", "description": "Format of the generated document (e.g., pdf).", "default": "pdf" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "salesforce": { "type": "object", "properties": { "networkId": { "type": "string", "description": "ID of specific Salesforce Experience Cloud site or community where the generated document should be stored or associated.", "default": "" }, "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } }, "data": { "type": "object", "properties": { "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "sourceDocuments": [ { "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "loadMethod": "Storage", "order": 1, "remove": "none" }, { "urn": "5d8e9f0a-1b2c-43d4-95e6-7f8a9b0c1d2e", "loadMethod": "Storage", "order": 2, "remove": "none" } ], "targetDocument": { "name": "Q3 Sales Report - Merged", "fileFormat": "pdf", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "salesforce": { "networkId": "0DMXYZ0000000AAAA", "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] } } }, "data": { "embedded": "key:value" } } } } }, "responses": { "201": { "description": "This response confirms that the merge operation was successfully completed. It returns metadata about the newly created PDF document, including its name, delivery method, file format, and a unique URN that can be used to reference or download the file. Additionally, it provides consumption details, such as the number of documents merged and total pages processed.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully merged." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the merged document is stored." }, "name": { "type": "string", "description": "The name of the merged document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the merged document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the merged document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-merged", "documents-merged" ], "type": "string", "description": "The type of resource consumed (e.g., pages-merged, documents-merged)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document merge request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the document merge was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report - Merged", "fileFormat": "pdf", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report - Merged.pdf" } } }, "consumption": [ { "dimension": "pages-merged", "value": 4 }, { "dimension": "documents-merged", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the merge request was invalid or improperly formed. It includes detailed error information such as status code, internal error codes, developer-facing messages, and user-friendly error descriptions to help diagnose the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document merge request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/v1/documents/document/merge/async": { "post": { "tags": [ "Document" ], "summary": "Document Merge Async", "description": "This endpoint initiates an asynchronous operation to merge multiple source documents into a single PDF, preserving the order specified in the request. Just like synchronous merge endpoint, it supports platforms like Storage, Salesforce, and OneDrive. Unlike the synchronous version, it returns immediately and processes the requested operation in the background. The result can be tracked or received via promise or callback, depending on your integration setup. This approach is ideal for handling large files, slower systems, or when non-blocking execution is preferred.", "operationId": "documents-merge-async", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**sourceDocuments**
\nIdentifies the input documents (e.g., Word, Excel, or PDF files) and their properties, serving as the inputs for the merge and conversion process to create a unified target document.\n\n---\n\n**targetDocument**
\nDefines the properties of the output document resulting from merging the source documents. It specifies the document’s metadata, format (typically PDF for merged outputs), delivery method, storage location, and processing options, determining how the merged document is saved and managed.\n\n**targetDocument.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**targetDocument.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "sourceDocuments": { "type": "array", "items": { "required": [ "urn", "fileFormat", "loadMethod", "remove" ], "type": "object", "properties": { "urn": { "type": "string", "description": "URN of the source document stored in the system.", "default": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70" }, "fileFormat": { "enum": [ "pdf" ], "type": "string", "description": "File format of the source document (e.g., pdf).", "default": "pdf" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the document where it is stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "order": { "type": "integer", "description": "Order in which the document should be merged.", "default": 1 }, "remove": { "type": "string", "description": "Flag indicating whether to remove the source document after merging (e.g., none, delete, permanentDelete).", "default": "none" } } } }, "targetDocument": { "required": [ "name", "fileFormat", "deliveryMethod", "path" ], "type": "object", "properties": { "name": { "type": "string", "description": "Name of the target document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "pdf" ], "type": "string", "description": "Format of the generated document (e.g., pdf).", "default": "pdf" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "salesforce": { "type": "object", "properties": { "networkId": { "type": "string", "description": "ID of specific Salesforce Experience Cloud site or community where the generated document should be stored or associated.", "default": "" }, "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } }, "data": { "type": "object", "properties": { "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "sourceDocuments": [ { "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "loadMethod": "Storage", "order": 1, "remove": "none" }, { "urn": "5d8e9f0a-1b2c-43d4-95e6-7f8a9b0c1d2e", "loadMethod": "Storage", "order": 2, "remove": "none" } ], "targetDocument": { "name": "Q3 Sales Report - Merged", "fileFormat": "pdf", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "salesforce": { "networkId": "0DMXYZ0000000AAAA", "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] } } }, "data": { "embedded": "key:value" } } } } }, "responses": { "201": { "description": "This response confirms that the merge operation was successfully completed. It returns metadata about the newly created PDF document, including its name, delivery method, file format, and a unique URN that can be used to reference or download the file. Additionally, it provides consumption details, such as the number of documents merged and total pages processed.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully merged." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the merged document is stored." }, "name": { "type": "string", "description": "The name of the merged document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the merged document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the merged document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-merged", "documents-merged" ], "type": "string", "description": "The type of resource consumed (e.g., pages-merged, documents-merged)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document merge request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the document merge was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report - Merged", "fileFormat": "pdf", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report - Merged.pdf" } } }, "consumption": [ { "dimension": "pages-merged", "value": 4 }, { "dimension": "documents-merged", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the merge request was invalid or improperly formed. It includes detailed error information such as status code, internal error codes, developer-facing messages, and user-friendly error descriptions to help diagnose the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document merge request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/v1/documents/option/{entityType}/{entityId}/create": { "post": { "tags": [ "Option Value" ], "summary": "Option Value Create", "description": "Creates one option value for the entity named in the path. Provide EITHER `optionDefinitionId` (system option) OR `customKey` (custom option), never both.", "operationId": "documents-option-value-create", "parameters": [ { "name": "entityType", "in": "path", "description": "Type of the owning entity, e.g. \"DocumentSolutionConfiguration\" or \"DocumentTemplate\".", "required": true, "schema": { "type": "string", "example": "DocumentSolutionConfiguration" } }, { "name": "entityId", "in": "path", "description": "GUID of the owning entity.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "requestBody": { "description": "The option value to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionValueModel" }, "example": { "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL" } } } }, "responses": { "200": { "description": "Option value created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "optionValue": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "OPTION_VALUE_MISSING_DEFINITION_OR_KEY", "message": "Either optionDefinitionId or customKey must be supplied." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/option/{optionValueGuid}/delete": { "delete": { "tags": [ "Option Value" ], "summary": "Option Value Delete", "description": "Deletes a single option value by its GUID.", "operationId": "documents-document-option-value-delete", "parameters": [ { "name": "optionValueGuid", "in": "path", "description": "GUID of the option value to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c9bf9e57-1685-4c89-bafb-ff5af830be8a" } } ], "responses": { "200": { "description": "Option value deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "Option value deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "message": "Option value deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "message": "Option value deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/option/{optionValueGuid}/get": { "get": { "tags": [ "Option Value" ], "summary": "Option Value Get", "description": "Retrieves a single option value by its GUID.", "operationId": "documents-document-option-value-get", "parameters": [ { "name": "optionValueGuid", "in": "path", "description": "GUID of the option value.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c9bf9e57-1685-4c89-bafb-ff5af830be8a" } } ], "responses": { "200": { "description": "Option value retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "optionValue": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/option/{entityType}/{entityId}/list": { "get": { "tags": [ "Option Value" ], "summary": "Option Value List", "description": "Returns all option values attached to the entity named in the path. This endpoint does not paginate.", "operationId": "documents-document-option-value-list", "parameters": [ { "name": "entityType", "in": "path", "description": "Type of the owning entity, e.g. \"DocumentSolutionConfiguration\" or \"DocumentTemplate\".", "required": true, "schema": { "type": "string", "example": "DocumentSolutionConfiguration" } }, { "name": "entityId", "in": "path", "description": "GUID of the owning entity.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "responses": { "200": { "description": "Option values retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "optionValues": { "type": "array", "items": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "optionValues": [ { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "optionValues": [ { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/option/{entityType}/{entityId}/replace": { "put": { "tags": [ "Option Value" ], "summary": "Option Value Replace", "description": "Bulk-replaces the full set of option values for the entity named in the path. Every item in the array is validated with the same rules as create.", "operationId": "documents-document-option-value-replace", "parameters": [ { "name": "entityType", "in": "path", "description": "Type of the owning entity, e.g. \"DocumentSolutionConfiguration\" or \"DocumentTemplate\".", "required": true, "schema": { "type": "string", "example": "DocumentSolutionConfiguration" } }, { "name": "entityId", "in": "path", "description": "GUID of the owning entity.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "requestBody": { "description": "The complete new set of option values for the entity.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } } }, "example": [ { "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL" }, { "optionDefinitionId": 42, "value": "true" } ] } } }, "responses": { "200": { "description": "Entity options replaced successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "entityId": { "type": "string", "format": "uuid" }, "entityType": { "type": "string", "example": "DocumentSolutionConfiguration" }, "message": { "type": "string", "example": "Entity options replaced successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "entityType": "DocumentSolutionConfiguration", "message": "Entity options replaced successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "entityType": "DocumentSolutionConfiguration", "message": "Entity options replaced successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/option/{optionValueGuid}/update": { "put": { "tags": [ "Option Value" ], "summary": "Option Value Update", "description": "Updates a single option value by its GUID.", "operationId": "documents-document-option-value-update", "parameters": [ { "name": "optionValueGuid", "in": "path", "description": "GUID of the option value to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c9bf9e57-1685-4c89-bafb-ff5af830be8a" } } ], "requestBody": { "description": "The option value with updated fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionValueModel" }, "example": { "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL" } } } }, "responses": { "200": { "description": "Option value updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "optionValue": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "optionValue": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/reference": { "post": { "tags": [ "Document" ], "summary": "Document Reference", "description": "Document Reference", "operationId": "documents-document-reference", "responses": { "200": { "description": "" } } } }, "/v1/documents/request/create": { "post": { "tags": [ "Document Request" ], "summary": "Document Request Create", "description": "Creates a new document request.", "operationId": "documents-request-create", "requestBody": { "description": "The DocumentRequestModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequestModel" }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "viewOrganization": true, "viewUser": true, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com" } } } }, "responses": { "200": { "description": "Document request created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRequest": { "required": [ "name", "status", "fileFormat", "deliveryMethod", "documentTemplateGuid", "dataGuid" ], "type": "object", "properties": { "documentRequestGuid": { "type": "string", "description": "Unique identifier of the request.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "documentTemplateGuid": { "type": "string", "description": "Template to generate from. Required (must be a non-empty GUID).", "format": "uuid" }, "dataGuid": { "type": "string", "description": "Data source to merge. Required (must be a non-empty GUID).", "format": "uuid" }, "documentGuid": { "type": "string", "description": "Resulting document, once generated.", "format": "uuid", "nullable": true, "readOnly": true }, "documentSolutionConfigurationGuid": { "type": "string", "description": "Optional configuration that governs generation & delivery.", "format": "uuid", "nullable": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "recordId": { "type": "string", "description": "Optional caller-supplied correlation/record id.", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the request. Required, must be non-empty.", "nullable": true }, "status": { "type": "string", "description": "Request status. Required, must be non-empty.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into this request.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (pdf only).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (pdf only).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "completedDate": { "type": "string", "description": "Completion timestamp (UTC), when finished. Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/request/{documentRequestGuid}/delete": { "delete": { "tags": [ "Document Request" ], "summary": "Document Request Delete", "description": "Soft-deletes a document request by its GUID.", "operationId": "documents-document-request-delete", "parameters": [ { "name": "documentRequestGuid", "in": "path", "description": "GUID of the document request to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } } ], "responses": { "200": { "description": "Document request deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRequestGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "DocumentRequest deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "message": "DocumentRequest deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "message": "DocumentRequest deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/request/{documentRequestGuid}/get": { "get": { "tags": [ "Document Request" ], "summary": "Document Request Get", "description": "Retrieves a single document request by its GUID.", "operationId": "documents-document-request-get", "parameters": [ { "name": "documentRequestGuid", "in": "path", "description": "GUID of the document request.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } } ], "responses": { "200": { "description": "Document request retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRequest": { "required": [ "name", "status", "fileFormat", "deliveryMethod", "documentTemplateGuid", "dataGuid" ], "type": "object", "properties": { "documentRequestGuid": { "type": "string", "description": "Unique identifier of the request.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "documentTemplateGuid": { "type": "string", "description": "Template to generate from. Required (must be a non-empty GUID).", "format": "uuid" }, "dataGuid": { "type": "string", "description": "Data source to merge. Required (must be a non-empty GUID).", "format": "uuid" }, "documentGuid": { "type": "string", "description": "Resulting document, once generated.", "format": "uuid", "nullable": true, "readOnly": true }, "documentSolutionConfigurationGuid": { "type": "string", "description": "Optional configuration that governs generation & delivery.", "format": "uuid", "nullable": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "recordId": { "type": "string", "description": "Optional caller-supplied correlation/record id.", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the request. Required, must be non-empty.", "nullable": true }, "status": { "type": "string", "description": "Request status. Required, must be non-empty.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into this request.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (pdf only).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (pdf only).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "completedDate": { "type": "string", "description": "Completion timestamp (UTC), when finished. Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/request/list": { "get": { "tags": [ "Document Request" ], "summary": "Document Request List", "description": "Returns a paginated, optionally filtered and sorted list of document requests.", "operationId": "documents-document-request-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of document requests retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRequests": { "type": "array", "items": { "required": [ "name", "status", "fileFormat", "deliveryMethod", "documentTemplateGuid", "dataGuid" ], "type": "object", "properties": { "documentRequestGuid": { "type": "string", "description": "Unique identifier of the request.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "documentTemplateGuid": { "type": "string", "description": "Template to generate from. Required (must be a non-empty GUID).", "format": "uuid" }, "dataGuid": { "type": "string", "description": "Data source to merge. Required (must be a non-empty GUID).", "format": "uuid" }, "documentGuid": { "type": "string", "description": "Resulting document, once generated.", "format": "uuid", "nullable": true, "readOnly": true }, "documentSolutionConfigurationGuid": { "type": "string", "description": "Optional configuration that governs generation & delivery.", "format": "uuid", "nullable": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "recordId": { "type": "string", "description": "Optional caller-supplied correlation/record id.", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the request. Required, must be non-empty.", "nullable": true }, "status": { "type": "string", "description": "Request status. Required, must be non-empty.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into this request.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (pdf only).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (pdf only).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "completedDate": { "type": "string", "description": "Completion timestamp (UTC), when finished. Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentRequests": [ { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentRequests": [ { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/request/{documentRequestGuid}/update": { "put": { "tags": [ "Document Request" ], "summary": "Document Request Update", "description": "Updates an existing document request.", "operationId": "documents-document-request-update", "parameters": [ { "name": "documentRequestGuid", "in": "path", "description": "GUID of the document request to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } } ], "requestBody": { "description": "The DocumentRequestModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequestModel" }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "viewOrganization": true, "viewUser": true, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com" } } } }, "responses": { "200": { "description": "Document request updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRequest": { "required": [ "name", "status", "fileFormat", "deliveryMethod", "documentTemplateGuid", "dataGuid" ], "type": "object", "properties": { "documentRequestGuid": { "type": "string", "description": "Unique identifier of the request.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "documentTemplateGuid": { "type": "string", "description": "Template to generate from. Required (must be a non-empty GUID).", "format": "uuid" }, "dataGuid": { "type": "string", "description": "Data source to merge. Required (must be a non-empty GUID).", "format": "uuid" }, "documentGuid": { "type": "string", "description": "Resulting document, once generated.", "format": "uuid", "nullable": true, "readOnly": true }, "documentSolutionConfigurationGuid": { "type": "string", "description": "Optional configuration that governs generation & delivery.", "format": "uuid", "nullable": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "recordId": { "type": "string", "description": "Optional caller-supplied correlation/record id.", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the request. Required, must be non-empty.", "nullable": true }, "status": { "type": "string", "description": "Request status. Required, must be non-empty.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into this request.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (pdf only).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (pdf only).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "completedDate": { "type": "string", "description": "Completion timestamp (UTC), when finished. Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentRequest": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "{\"invoiceNumber\":\"INV-2026-000123\"}", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/configuration/create": { "post": { "tags": [ "Document Solution Configuration" ], "summary": "Document Solution Configuration Create", "description": "Creates a new document solution configuration.", "operationId": "documents-configuration-create", "requestBody": { "description": "The DocumentSolutionConfigurationModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSolutionConfigurationModel" }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com" } } } }, "responses": { "200": { "description": "Document solution configuration created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionConfiguration": { "required": [ "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "description": "Unique identifier of the configuration.", "format": "uuid", "readOnly": true }, "documentSolutionGuid": { "type": "string", "description": "Parent document solution this configuration belongs to.", "format": "uuid" }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the configuration. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode. When supplied must be one of the allowed values.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (applies when fileFormat is pdf).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (applies when fileFormat is pdf).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code applied during generation.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone used for date/time formatting.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into every generation.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/configuration/{documentSolutionConfigurationGuid}/delete": { "delete": { "tags": [ "Document Solution Configuration" ], "summary": "Document Solution Configuration Delete", "description": "Soft-deletes a document solution configuration by its GUID.", "operationId": "documents-document-solution-configuration-delete", "parameters": [ { "name": "documentSolutionConfigurationGuid", "in": "path", "description": "GUID of the document solution configuration to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "responses": { "200": { "description": "Document solution configuration deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "DocumentSolutionConfiguration deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "message": "DocumentSolutionConfiguration deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "message": "DocumentSolutionConfiguration deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/configuration/{documentSolutionConfigurationGuid}/get": { "get": { "tags": [ "Document Solution Configuration" ], "summary": "Document Solution Configuration Get", "description": "Retrieves a single document solution configuration by its GUID.", "operationId": "documents-document-solution-configuration-get", "parameters": [ { "name": "documentSolutionConfigurationGuid", "in": "path", "description": "GUID of the document solution configuration.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "responses": { "200": { "description": "Document solution configuration retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionConfiguration": { "required": [ "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "description": "Unique identifier of the configuration.", "format": "uuid", "readOnly": true }, "documentSolutionGuid": { "type": "string", "description": "Parent document solution this configuration belongs to.", "format": "uuid" }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the configuration. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode. When supplied must be one of the allowed values.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (applies when fileFormat is pdf).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (applies when fileFormat is pdf).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code applied during generation.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone used for date/time formatting.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into every generation.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/configuration/list": { "get": { "tags": [ "Document Solution Configuration" ], "summary": "Document Solution Configuration List", "description": "Returns a paginated, optionally filtered and sorted list of document solution configurations.", "operationId": "documents-document-solution-configuration-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of document solution configurations retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionConfigurations": { "type": "array", "items": { "required": [ "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "description": "Unique identifier of the configuration.", "format": "uuid", "readOnly": true }, "documentSolutionGuid": { "type": "string", "description": "Parent document solution this configuration belongs to.", "format": "uuid" }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the configuration. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode. When supplied must be one of the allowed values.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (applies when fileFormat is pdf).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (applies when fileFormat is pdf).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code applied during generation.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone used for date/time formatting.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into every generation.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionConfigurations": [ { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionConfigurations": [ { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/configuration/{documentSolutionConfigurationGuid}/update": { "put": { "tags": [ "Document Solution Configuration" ], "summary": "Document Solution Configuration Update", "description": "Updates an existing document solution configuration.", "operationId": "documents-document-solution-configuration-update", "parameters": [ { "name": "documentSolutionConfigurationGuid", "in": "path", "description": "GUID of the document solution configuration to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a3bb189e-8bf9-3888-9912-ace4e6543002" } } ], "requestBody": { "description": "The DocumentSolutionConfigurationModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSolutionConfigurationModel" }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com" } } } }, "responses": { "200": { "description": "Document solution configuration updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionConfiguration": { "required": [ "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "description": "Unique identifier of the configuration.", "format": "uuid", "readOnly": true }, "documentSolutionGuid": { "type": "string", "description": "Parent document solution this configuration belongs to.", "format": "uuid" }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the configuration. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode. When supplied must be one of the allowed values.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (applies when fileFormat is pdf).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (applies when fileFormat is pdf).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code applied during generation.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone used for date/time formatting.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into every generation.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionConfiguration": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "2026-01-07", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "{\"companyName\":\"Contoso Ltd\"}", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/solution/create": { "post": { "tags": [ "Document Solution" ], "summary": "Document Solution Create", "description": "Creates a new document solution.", "operationId": "documents-solution-create", "requestBody": { "description": "The DocumentSolutionModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSolutionModel" }, "example": { "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } }, "responses": { "200": { "description": "Document solution created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolution": { "required": [ "name", "dataGuid" ], "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "description": "Unique identifier of the document solution.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "dataGuid": { "type": "string", "description": "Identifier of the data source that feeds this solution. Required.", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the solution. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/solution/{documentSolutionGuid}/delete": { "delete": { "tags": [ "Document Solution" ], "summary": "Document Solution Delete", "description": "Soft-deletes a document solution by its GUID.", "operationId": "documents-document-solution-delete", "parameters": [ { "name": "documentSolutionGuid", "in": "path", "description": "GUID of the document solution to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" } } ], "responses": { "200": { "description": "Document solution deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "DocumentSolution deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "message": "DocumentSolution deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "message": "DocumentSolution deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/solution/{documentSolutionGuid}/get": { "get": { "tags": [ "Document Solution" ], "summary": "Document Solution Get", "description": "Retrieves a single document solution by its GUID.", "operationId": "documents-document-solution-get", "parameters": [ { "name": "documentSolutionGuid", "in": "path", "description": "GUID of the document solution.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" } } ], "responses": { "200": { "description": "Document solution retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolution": { "required": [ "name", "dataGuid" ], "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "description": "Unique identifier of the document solution.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "dataGuid": { "type": "string", "description": "Identifier of the data source that feeds this solution. Required.", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the solution. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/solution/list": { "get": { "tags": [ "Document Solution" ], "summary": "Document Solution List", "description": "Returns a paginated, optionally filtered and sorted list of document solutions.", "operationId": "documents-document-solution-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of document solutions retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolutions": { "type": "array", "items": { "required": [ "name", "dataGuid" ], "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "description": "Unique identifier of the document solution.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "dataGuid": { "type": "string", "description": "Identifier of the data source that feeds this solution. Required.", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the solution. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolutions": [ { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolutions": [ { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/solution/{documentSolutionGuid}/update": { "put": { "tags": [ "Document Solution" ], "summary": "Document Solution Update", "description": "Updates an existing document solution.", "operationId": "documents-document-solution-update", "parameters": [ { "name": "documentSolutionGuid", "in": "path", "description": "GUID of the document solution to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" } } ], "requestBody": { "description": "The DocumentSolutionModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSolutionModel" }, "example": { "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } }, "responses": { "200": { "description": "Document solution updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentSolution": { "required": [ "name", "dataGuid" ], "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "description": "Unique identifier of the document solution.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "dataGuid": { "type": "string", "description": "Identifier of the data source that feeds this solution. Required.", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the solution. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentSolution": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/{documentGuid}/update": { "put": { "tags": [ "Document" ], "summary": "Document Update", "description": "Updates an existing document.", "operationId": "documents-document-update", "parameters": [ { "name": "documentGuid", "in": "path", "description": "GUID of the document to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "16fd2706-8baf-433b-82eb-8c7fada847da" } } ], "requestBody": { "description": "The DocumentModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentModel" }, "example": { "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com" } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "required": [ "title", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentGuid": { "type": "string", "description": "Unique identifier of the document.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "title": { "type": "string", "description": "Document title. Required, must be non-empty.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the document file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the document file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the document file.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the document. Required.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the document is delivered. Required.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Anonymous view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Anonymous edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Authenticated-user view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Authenticated-user edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Organization view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Organization edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "succeededViewUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "succeededEditUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedViewUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedEditUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "document": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/document/upload": { "post": { "tags": [ "Document" ], "summary": "Document Upload", "description": "General-purpose document upload to Storage, form-data only. Accepted extensions: .docx, .xlsx, .doc, .xls. When several files are sent in one request, their form-data order is preserved in the response. Each document is assigned a storage id that can be referenced in later processes such as Document Merge or signing envelopes. Max size is enforced at the gateway (20MB Production, 10MB Staging).", "operationId": "documents-document-upload", "parameters": [ { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Origin", "in": "header", "description": "Free-form caller-supplied origin identifier. Not validated; echoed back verbatim into the response envelope's origin field. Optional.", "schema": { "type": "string" }, "example": "https://app.mavenmule.com" }, { "name": "X-Storage-Type", "in": "header", "description": "Selects which storage container handles the request. This operation expects the value `document-template`.", "required": true, "schema": { "type": "string" }, "example": "document-template" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "array", "description": "One or more document files to upload. Accepted extensions: .docx, .xlsx, .doc, .xls (validated by filename extension, case-sensitively — an uppercase extension like .DOCX does not match). Order is preserved in the response.", "required": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Document(s) uploaded. Returns a storage id per file, usable in downstream document/signature operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSuccessResponse" }, "example": { "result": { "data": { "files": [ { "id": "7c2f5a91-3e44-4b0d-a6f8-1b2c3d4e5f60", "fileName": "quarterly-report.docx" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "400": { "description": "A file has an extension outside .docx/.xlsx/.doc/.xls (INVALID_TEMPLATE_FORMAT), or the request was not multipart/form-data, or no file was supplied (FORM_DATA_EXPECTED — this container type has no JSON/raw-body alternative, so any non-form request lands here).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 400, "message": "The file 'notes.pdf' has an unsupported format. Allowed: .docx,.xlsx,.doc,.xls", "innerErrors": [ { "code": "INVALID_TEMPLATE_FORMAT", "message": "The file 'notes.pdf' has an unsupported format. Allowed: .docx,.xlsx,.doc,.xls", "userMessage": "This document format isn't supported. Upload a .docx, .xlsx, .doc or .xls file." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be stored due to a server/storage error (`FILE_UPLOAD_FAILED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/documents/template/create": { "post": { "tags": [ "Document Template" ], "summary": "Document Template Create", "description": "Creates a new document template.", "operationId": "documents-template-create", "requestBody": { "description": "The DocumentTemplateModel payload to create. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplateModel" }, "example": { "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx" } } } }, "responses": { "200": { "description": "Document template created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTemplate": { "required": [ "name", "fileFormat", "loadMethod" ], "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "description": "Unique identifier of the template.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the template. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional document title applied to generated output.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the template file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the template file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Read-only sharing link for anonymous viewers. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Editing link for anonymous users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Read-only sharing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Editing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Read-only sharing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Editing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the template. Required.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How the template file is loaded. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the template file.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/template/{documentTemplateGuid}/delete": { "delete": { "tags": [ "Document Template" ], "summary": "Document Template Delete", "description": "Soft-deletes a document template by its GUID.", "operationId": "documents-template-delete", "parameters": [ { "name": "documentTemplateGuid", "in": "path", "description": "GUID of the document template to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } ], "responses": { "200": { "description": "Document template deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "format": "uuid" }, "message": { "type": "string", "example": "DocumentTemplate deleted successfully." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "message": "DocumentTemplate deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "message": "DocumentTemplate deleted successfully." }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/template/{documentTemplateGuid}/get": { "get": { "tags": [ "Document Template" ], "summary": "Document Template Get", "description": "Retrieves a single document template by its GUID.", "operationId": "documents-template-get", "parameters": [ { "name": "documentTemplateGuid", "in": "path", "description": "GUID of the document template.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } ], "responses": { "200": { "description": "Document template retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTemplate": { "required": [ "name", "fileFormat", "loadMethod" ], "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "description": "Unique identifier of the template.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the template. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional document title applied to generated output.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the template file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the template file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Read-only sharing link for anonymous viewers. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Editing link for anonymous users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Read-only sharing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Editing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Read-only sharing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Editing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the template. Required.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How the template file is loaded. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the template file.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/template/list": { "get": { "tags": [ "Document Template" ], "summary": "Document Template List", "description": "Returns a paginated, optionally filtered and sorted list of document templates.", "operationId": "documents-template-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of records to return (page size).", "schema": { "type": "integer", "example": 25 } }, { "name": "skip", "in": "query", "description": "Number of records to skip (page offset).", "schema": { "type": "integer", "example": 0 } }, { "name": "orderby", "in": "query", "description": "Sort clause in the form `Column|DIRECTION`, e.g. `Name|DESC`. The column and direction are separated by a pipe (`|`).", "schema": { "type": "string", "example": "Name|DESC" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of filter clauses (see FilterDTO). Example (decoded): `[{\"key\":\"Filter1\",\"column\":\"Name\",\"type\":\"string\",\"condition\":\"CONTAINS\",\"value\":\"Invoice\"}]`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of document templates retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTemplates": { "type": "array", "items": { "required": [ "name", "fileFormat", "loadMethod" ], "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "description": "Unique identifier of the template.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the template. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional document title applied to generated output.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the template file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the template file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Read-only sharing link for anonymous viewers. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Editing link for anonymous users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Read-only sharing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Editing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Read-only sharing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Editing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the template. Required.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How the template file is loaded. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the template file.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } }, "rowCount": { "type": "integer", "description": "Total number of records matching the query.", "example": 1 } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentTemplates": [ { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentTemplates": [ { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } ], "rowCount": 1 }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/template/{documentTemplateGuid}/update": { "put": { "tags": [ "Document Template" ], "summary": "Document Template Update", "description": "Updates an existing document template.", "operationId": "documents-template-update", "parameters": [ { "name": "documentTemplateGuid", "in": "path", "description": "GUID of the document template to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } ], "requestBody": { "description": "The DocumentTemplateModel payload to update. Server-managed fields (ids, timestamps, links, isDeleted) are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplateModel" }, "example": { "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx" } } } }, "responses": { "200": { "description": "Document template updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTemplate": { "required": [ "name", "fileFormat", "loadMethod" ], "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "description": "Unique identifier of the template.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the template. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional document title applied to generated output.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the template file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the template file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Read-only sharing link for anonymous viewers. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Editing link for anonymous users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Read-only sharing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Editing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Read-only sharing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Editing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the template. Required.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How the template file is loaded. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the template file.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation.", "example": 200 }, "message": { "type": "string", "description": "Human-readable status message.", "example": "OK" } } }, "origin": { "type": "string", "description": "Echoed Origin request header.", "nullable": true, "example": "https://app.example.com" }, "dateTime": { "type": "string", "description": "UTC time the response was produced.", "format": "date-time", "example": "2026-07-14T09:30:00.0000000+00:00" }, "operationId": { "type": "string", "description": "Distributed-trace correlation id.", "nullable": true, "example": "0HN7GK9M4T2R5" } }, "description": "Standard response envelope returned by every endpoint.", "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } }, "example": { "result": { "data": { "documentTemplate": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "statusCode": 200, "message": "OK" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "Validation failed (e.g. missing required field or invalid enum value).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required." } } } }, "401": { "description": "Missing or invalid authentication token / subscription key." }, "404": { "description": "The requested resource was not found." }, "500": { "description": "Unexpected server error. `eventId` correlates to server logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "GET_DATA_SOURCE_ERROR", "message": "An unexpected error occurred.", "eventId": "a1b2c3d4" } } } } } } }, "/v1/documents/template/upload": { "post": { "tags": [ "Template" ], "summary": "Template Upload", "description": "Uploads one or more template files to Storage so they can be referenced in later requests such as document generation. Form-data only. Accepted formats: DOCX, XLSX, DOC, XLS. When several files are sent, their form-data order is preserved in the response. Each template is assigned a storage id. Uploaded templates are automatically removed from Storage after the next document-generation request that consumes them, whether it succeeds or fails — re-upload if needed. Max size is enforced at the gateway (20MB Production, 10MB Staging).", "operationId": "documents-templates-upload", "parameters": [ { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Origin", "in": "header", "description": "Free-form caller-supplied origin identifier. Not validated; echoed back verbatim into the response envelope's origin field. Optional.", "schema": { "type": "string" }, "example": "https://app.mavenmule.com" }, { "name": "X-Storage-Type", "in": "header", "description": "Selects which storage container/validation branch handles the request. This operation expects the value document-template. Not strictly enforced as a closed enum server-side.", "required": true, "schema": { "type": "string" }, "example": "document-template" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "array", "description": "One or more template files to upload. Accepted extensions: .docx, .xlsx, .doc, .xls (validated by filename extension, case-sensitively). Order is preserved in the response.", "required": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Template(s) uploaded. Returns a storage id per file, usable as a template source in subsequent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSuccessResponse" }, "example": { "result": { "data": { "files": [ { "id": "b1e6d2c9-77aa-4f3b-8c21-9d0e4a6f2b58", "fileName": "quarterly-report-template.docx" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "400": { "description": "A file has an extension outside .docx/.xlsx/.doc/.xls (INVALID_TEMPLATE_FORMAT), or the request was not multipart/form-data, or no file was supplied (FORM_DATA_EXPECTED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 400, "message": "The file 'notes.txt' has an unsupported format. Allowed: .docx,.xlsx,.doc,.xls", "innerErrors": [ { "code": "INVALID_TEMPLATE_FORMAT", "message": "The file 'notes.txt' has an unsupported format. Allowed: .docx,.xlsx,.doc,.xls", "userMessage": "This template format isn't supported. Upload a .docx, .xlsx, .doc or .xls file." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be stored due to a server/storage error (`FILE_UPLOAD_FAILED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/signatures/document/{documentId}/comment": { "post": { "tags": [ "Document", "Comment" ], "summary": "Document Comment", "description": "Adds a text comment to a document that's part of an envelope.
\n* The document must be uploaded to the Storage system before you can comment on it.\n* Use the documentId (a unique document URN) to reference the stored document.\n* The document can be identified by a unique transactionId (tid).\n* Provide the tid as a query parameter. `parentCommentId` is optional; if it doesn't reference an existing comment, the new comment is created as a top-level comment instead.", "operationId": "signatures-document-comment", "parameters": [ { "name": "documentId", "in": "path", "description": "The ID(URN) of the document from the envelope, where you’d like to place a comment.", "required": true, "schema": { "type": "string" } }, { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Origin-IpAddress", "in": "header", "description": "Caller IP address, recorded in the audit trail. Not validated.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "content": { "type": "string", "description": "Not required or length-limited by the server.", "nullable": true }, "pageNumber": { "type": "integer", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "parentCommentId": { "type": "string", "description": "Not validated to reference an existing comment - an unknown id is silently treated as a top-level comment.", "format": "uuid", "nullable": true }, "visibleTo": { "type": "array", "items": { "type": "string" }, "description": "Recipient emails allowed to see this comment. Not validated as email format at write time." } } }, "externalContext": { "nullable": true } } }, "example": { "comment": { "content": "string", "pageNumber": 0, "positionX": 0, "positionY": 0, "parentCommentId": "string", "visibleTo": [ "string" ] }, "externalContext": {} } } } }, "responses": { "201": { "description": "Comment created; returns the full visible-comment set for the envelope, not just the new comment.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "comments": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "signerId": { "type": "string", "format": "uuid", "nullable": true }, "parentCommentId": { "type": "string", "format": "uuid", "nullable": true }, "content": { "type": "string", "nullable": true }, "pageNumber": { "type": "integer", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "visibleTo": { "type": "string", "description": "JSON-encoded array AS A STRING (e.g. \"[\\\"a@b.com\\\"]\"), not a native array - a source inconsistency with the write-side shape (see document/{documentId}/comment).", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "authorName": { "type": "string", "nullable": true }, "authorEmail": { "type": "string", "nullable": true } } } }, "description": "Map keyed by document id (as a string) to an array of comments.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "externalContext": { "description": "Echoed verbatim from the request; opaque, not validated.", "nullable": true } } }, "example": { "result": { "statusCode": 201, "message": "Created", "data": { "comments": {} } }, "origin": "string", "dateTime": "string", "externalContext": {} } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/document/{documentId}/download": { "get": { "tags": [ "Document" ], "summary": "Document Download", "description": "Downloads a previously stored document by its storage id and returns the raw file as an octet-stream. The caller must own the file.", "operationId": "signatures-download", "parameters": [ { "name": "documentId", "in": "path", "description": "Storage id (GUID) of the document to download, as returned by an upload or generation response.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Storage-Type", "in": "header", "description": "Container-type key used to look up the blob. Must match whichever container the file was originally uploaded to (commonly document-input for signature-flow documents). Not strictly enforced as a closed enum; an unrecognized value surfaces as a generic FILE_DOWNLOAD_FAILED.", "required": true, "schema": { "type": "string" }, "example": "document-input" } ], "responses": { "200": { "description": "Returns the stored document as a binary stream. The Content-Disposition file name and Content-Type reflect the stored file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "403": { "description": "The file exists but belongs to a different user. Real code: FILE_ACCESS_DENIED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 403, "message": "The requested file does not belong to the authenticated user.", "innerErrors": [ { "code": "FILE_ACCESS_DENIED", "message": "The requested file does not belong to the authenticated user.", "userMessage": "You don't have access to this file." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "404": { "description": "No file exists for the supplied id. Real code: NOT_FOUND_BY_ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 404, "message": "No file was found for the supplied id.", "innerErrors": [ { "code": "NOT_FOUND_BY_ID", "message": "No file was found for the supplied id.", "userMessage": "We couldn't find that file. Check the id and try again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be retrieved due to a server/storage error. Real code: FILE_DOWNLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to read the requested file from storage.", "innerErrors": [ { "code": "FILE_DOWNLOAD_FAILED", "message": "Failed to read the requested file from storage.", "userMessage": "Something went wrong while downloading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/signatures/document/{documentId}/get": { "get": { "tags": [ "Document", "Data" ], "summary": "Document Get", "description": "Retrieves metadata for a document included in an envelope in JSON format.
\n* Use the documentId (a unique document URN) to reference the document that is included into an envelope.\n* The request returns the document data in JSON format.\n* The document can be identified by a unique transactionId (tid).\n* Provide the tid as a query parameter. Covers both regular documents and pre-conversion \"original\" documents (union query) - externalContext is always null for the latter. A caller who can't see the document gets the same DOCUMENT_ID_INVALID as a nonexistent one; there is no separate access-denied response for this operation.", "operationId": "signatures-get-getdocument", "parameters": [ { "name": "documentId", "in": "path", "description": "The ID(URN) of the document that is included into an envelope.", "required": true, "schema": { "type": "string" } }, { "name": "tid", "in": "query", "description": "This is a unique identifier associated with a specific recipient and envelope within a given transaction. It is used to securely validate that the user has the appropriate authorization to perform actions related to that transaction.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document metadata retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "readOnly": true }, "externalContext": { "nullable": true, "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "document": { "id": "string", "name": "string", "externalContext": {} } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/document/manage": { "post": { "tags": [ "Document" ], "summary": "Document Manage", "description": "Manages documents across supported platforms (Storage, Salesforce, OneDrive) without modifying their internal content.
\n* Supported operations include:\n * Copy. Duplicate a document from source to target. Requires the same fileFormat for source and target, and source.remove = \"none\".\n * Move. Transfer a document from source to target and delete it from the source. Requires the same fileFormat for source and target, and source.remove = \"delete\" or \"permanentDelete\".\n * Delete. Remove a document when only the source is provided, with source.remove = \"delete\" or \"permanentDelete\" and no target.\n * Convert. Change document format while transferring; both source and target are required and fileFormat must differ.", "operationId": "signatures-post-convertdocxtopdf", "parameters": [ { "name": "Authorization", "in": "header", "description": "JWT token to authenticate the request on behalf of a specific Microsoft user or a backend service principal.", "required": true, "schema": { "enum": [ "Bearer {{authToken}}" ], "type": "string", "default": "Bearer {{authToken}}" } }, { "name": "X-Subscription-Key", "in": "header", "description": "Unique API key used to identify and authorize access to a specific environment", "required": true, "schema": { "enum": [ "{{apiKey}}" ], "type": "string", "default": "{{apiKey}}" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side. The JWT must contain the following claims:\n\n- **_sub_**: Current user session.\n- **_Destination_**: Path to which should be used to make a callback.\n- **_full_name_**: Name of the user that made the request.\n- **_email_**: The email address of the user that made the request.\n- **_iss_**: The issuer claim identifies the principal that issued the JWT. URL of the issuer.\n- **_oid_**: Object Id claim represents a unique Id of the user that made the request, for example in Salesforce case this will be User record Id.\n- **_clientId_**: Id representing the client. Eg OrgId.\n- **_zoneInfo_**: Zone information.\n- **_locale_**: Localization information.", "schema": { "type": "string" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription. The JWT must contain the following claims:\n\n- **_amp_subscription_**: The offering subscription key which is used to validate that the client has a valid license.\n- **_full_name_**: Name of the user that made the request.\n- **_email_**: The email address of the user that made the request.\n- **_iss_**: The issuer claim identifies the principal that issued the JWT. URL of the issuer.\n- **_oid_**: Object Id claim represents a unique Id of the user that made the request, for example in Salesforce case this will be User record Id.\n- **_zoneInfo_**: Zone information.\n- **_locale_**: Localization information.", "schema": { "type": "string" } } ], "requestBody": { "description": "**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**sourceDocument**
\nIdentifies the input document and its properties, serving as the starting point for file operations like copying to a new location, moving with deletion, deleting outright, or converting to a different format.\n\n**sourceDocument.options**
\nFine-tunes the loading process for the source document to meet specific requirements, such as retaining formatting or handling special features during operations like copying or conversion.\n\n---\n\n**targetDocument**
\nDefines the properties of the output document resulting from the file operation (e.g., the destination for Copy, Move, or Convert operations). It specifies the document’s metadata, format, delivery method, storage location, and processing options, determining how the processed document is saved and managed. This node is omitted for Delete operations, as no output document is generated.\n\n**targetDocument.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**targetDocument.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "example": "{\n \"externalContext\": {\n \"id\": \"12345\"\n },\n \"sourceDocument\": {\n \"urn\": \"{{uploadedDocument}}\",\n \"fileFormat\": \"pdf\",\n \"loadMethod\": \"Storage\",\n \"remove\": \"none\",\n \"options\": {\n \"docxLoadOptions\": \"{}\"\n }\n },\n \"targetDocument\": {\n \"name\": \"CopiedTest\",\n \"fileFormat\": \"pdf\",\n \"deliveryMethod\": \"Storage\",\n \"path\": \"root\",\n \"options\": {\n \"pdfSaveOptions\": \"{ \\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750 }\",\n \"docxSaveOptions\": \"{}\",\n \"salesforce\": {\n \"networkId\": \"\",\n \"fileId\": \"\",\n \"fileType\": \"\", //Attachment, File\n \"fileParentId\": \"\",\n \"ownerId\": \"\"\n },\n \"onedrive\": {\n \"viewAnonymous\": true,\n \"editAnonymous\": true,\n \"editUsers\": [\n \"user@example.com\",\n \"user@example.com\" \n ],\n \"viewUsers\": [\n \"user@example.com\",\n \"user@example.com\" \n ]\n }\n }\n },\n \"data\": {\n \"embedded\": \"\"\n }\n}" } } }, "responses": { "201": { "description": "This response confirms that the document management operation (such as copy, move, delete, or convert) was successfully completed.
\nIt returns metadata about the resulting document, including its name, format, storage location, and URN.
\nThe response also includes consumption metrics indicating how many documents and pages were processed, which are relevant for billing or quotas.", "content": { "application/json": { "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Sales Agreement DOCX", "fileFormat": "pdf", "urn": "20b8feea-a8e6-929d-5beb67a290b8" } } }, "consumption": [ { "dimension": "pages-managed", "value": 5 }, { "dimension": "documents-managed", "value": 1 } ], "origin": "POST https://dev.headless.mavenmule.com/signatures/document/manage", "dateTime": "2025-11-05T11:02:16.0000000+00:00", "userId": "1d8b89c4-0889-0c-9af09ac3bc9b", "operationId": "a9733c420a9e6336ea36ed98f31" } } } }, "400": { "description": "This response indicates that the request was invalid or improperly formed.
\nIt provides details about the error that occurred, including specific error codes, messages, and guidance for the user on how to resolve the issue.", "content": { "application/json": { "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "{{errorCode}}", "message": "{{errorMessage}}", "userMessage": "{{message}}", "eventId": "{{eventId}}" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "{{externalContextId}}" }, "origin": "{{originEnvironment}}", "dateTime": "{{responseTimestamp}}", "userId": "{{userId}}", "operationId": "{{operationId}}" } } } } } } }, "/v1/signatures/document/upload": { "post": { "tags": [ "Document" ], "summary": "Document Upload", "description": "Uploads one or more signature-flow documents to Storage (X-Storage-Type: document-input) so they can be referenced later, e.g. in envelope creation. Two independent, real, working request shapes are accepted — and they accept DIFFERENT extension sets, which this description states explicitly rather than smoothing over: (1) multipart/form-data — multiple files per request, order preserved, each validated by filename extension against the NARROWER set .docx/.doc/.pdf (INVALID_TEMPLATE_FORMAT on mismatch — note: this reuses the template validator's error code even though it's validating signature-document types, a real backend naming quirk, not a documentation error); (2) a single-file raw binary body whose Content-Type is one of 5 recognized document mime types, accepting the WIDER set docx/xlsx/doc/xls/pdf — an .xlsx or .xls file succeeds via this raw-body path even though the identical file would be rejected via form-data for the same X-Storage-Type. The generated filename for the raw-body path is document${guid}.{extension}. Max File Size: Production 20 MB, Staging 10 MB.", "operationId": "signatures-document-upload", "parameters": [ { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` for service-principal callers.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` for client-application callers.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution when authenticating via a service or client auth token.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token.", "schema": { "type": "string" } }, { "name": "X-Origin", "in": "header", "description": "Free-form caller-supplied origin identifier. Not validated; echoed back verbatim into the response envelope's origin field. Optional.", "schema": { "type": "string" }, "example": "https://app.mavenmule.com" }, { "name": "X-Storage-Type", "in": "header", "description": "Selects which storage container/validation branch handles the request. This operation expects the value document-input. Not strictly enforced as a closed enum server-side.", "required": true, "schema": { "type": "string" }, "example": "document-input" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "array", "description": "One or more signature documents to upload. Accepted extensions (form-data path only): .docx, .doc, .pdf. Order is preserved in the response.", "required": true } }, "type": "object" } }, "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "description": "Raw single-file binary upload (.docx). Wider extension set than the form-data path — see operation description.", "format": "binary" }, "example": "string" }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "description": "Raw single-file binary upload (.xlsx). Accepted here even though rejected by the form-data path for the same X-Storage-Type.", "format": "binary" }, "example": "string" }, "application/msword": { "schema": { "type": "string", "description": "Raw single-file binary upload (.doc).", "format": "binary" }, "example": "" }, "application/vnd.ms-excel": { "schema": { "type": "string", "description": "Raw single-file binary upload (.xls). Accepted here even though rejected by the form-data path for the same X-Storage-Type.", "format": "binary" }, "example": "" }, "application/pdf": { "schema": { "type": "string", "description": "Raw single-file binary upload (.pdf).", "format": "binary" }, "example": "" } } }, "responses": { "201": { "description": "This is the response returned when a document is successfully uploaded to Storage. The uploaded document is stored and assigned a unique id, which can then be used later for signing operations (e.g., as part of an envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSuccessResponse" }, "example": { "result": { "data": { "files": [ { "id": "b6a5f346-6b60-4c1a-9d55-782651280abc", "fileName": "Sales Agreement DOCX.docx" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2025-11-05T11:02:07.0000000+00:00", "operationId": "be40dc606fbf6adc1702572ecb" } } } }, "400": { "description": "Form-data path: a file has an extension outside .docx/.doc/.pdf (INVALID_TEMPLATE_FORMAT — reuses the template error code, real backend behavior). Raw-body path: the Content-Type header isn't one of the 5 recognized document mime types, or the form was empty/absent entirely (FORM_DATA_EXPECTED, despite the name, this also covers an unrecognized raw Content-Type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 400, "message": "Request must be multipart/form-data or a recognized document Content-Type.", "innerErrors": [ { "code": "FORM_DATA_EXPECTED", "message": "Request must be multipart/form-data or a recognized document Content-Type.", "userMessage": "Request must be multipart/form-data or a recognized document Content-Type." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2025-10-31T08:19:03.0000000+00:00", "operationId": "a9733c420a9e6336ea36ed98f31" } } } }, "401": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be stored due to a server/storage error (`FILE_UPLOAD_FAILED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/signatures/envelope/accept": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Accept", "description": "Records a recipient's explicit agreement to the legal terms or conditions associated with an envelope.
\n* The envelope is identified by a unique transactionId (tid).\n* The tid is typically obtained from the email link sent to the recipient or via the GET /signatures/envelope/list endpoint.\n* Provide the tid as a query parameter.\n* This procedure occurs before the recipient views or signs any documents.", "operationId": "signatures-post-acceptlegaltermsfunction", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/attachment/{attachmentId}/download": { "get": { "tags": [ "Envelope", "Attachment" ], "summary": "Envelope Attachment Download", "description": "Downloads an attachment associated with an envelope, returned in its original format as uploaded. Genuinely supports TWO alternate, mutually exclusive auth contracts (intentional dual-mode design, not a bug): (1) anonymous mode — a Guid-parseable tid query parameter is present, and no Authorization header is required at all; the acting identity is resolved via the transaction token instead; or (2) authenticated mode — no valid tid is supplied, so a real Authorization bearer token IS required. Exactly one of {tid, Authorization} applies per call. Blob lookup uses a folder-per-envelope layout ({envelopeId}/{attachmentId}). When X-Storage-Type resolves to envelope-attachment specifically, an additional cross-type check guards against fetching an envelope-document/envelope-audit blob through this route; that extra check is skipped for the other two envelope container types.", "operationId": "signatures-envelope-attachment-download", "parameters": [ { "name": "envelopeId", "in": "path", "description": "GUID of the envelope the attachment belongs to.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "attachmentId", "in": "path", "description": "GUID of the attachment to download.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "9c858901-8a57-4791-81fe-4c455b099bc9" }, { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. When present and Guid-parseable, selects anonymous mode and no Authorization header is required. When absent or not Guid-parseable, authenticated mode applies and Authorization is required instead.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token, in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Storage-Type", "in": "header", "description": "Container-type key used to look up the blob. Expected value for this operation is `envelope-attachment`; `envelope-document`/`envelope-audit` are also recognized container types.", "required": true, "schema": { "type": "string" }, "example": "envelope-attachment" } ], "responses": { "200": { "description": "The response body contains the binary content of the attachment in its original format, as it was uploaded. Streamed directly to the client for download.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "401": { "description": "Missing or invalid authentication (does not apply when a valid `tid` is supplied).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "403": { "description": "The attachment exists but belongs to a different user (FILE_ACCESS_DENIED — this also covers the envelope-attachment cross-type check), or the anonymous-mode owner was resolved but their subscription is inactive/invalid (ENVELOPE_OWNER_INVALID_SUBSCRIPTION).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 403, "message": "The requested file does not belong to the authenticated user.", "innerErrors": [ { "code": "FILE_ACCESS_DENIED", "message": "The requested file does not belong to the authenticated user.", "userMessage": "You don't have access to this file." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "404": { "description": "No attachment exists for the supplied ids (NOT_FOUND_BY_ID); the tid didn't resolve to a valid transaction/envelope pair (ENVELOPE_NOT_FOUND_TID); the resolved envelope owner no longer exists (ENVELOPE_OWNER_NOT_FOUND); or, in authenticated mode, the caller is neither the envelope's creator nor a signer on it (ENVELOPE_NOT_FOUND_USER_AND_ENVELOPE_ID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 404, "message": "No file was found for the supplied id.", "innerErrors": [ { "code": "NOT_FOUND_BY_ID", "message": "No file was found for the supplied id.", "userMessage": "We couldn't find that file. Check the id and try again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be retrieved due to a server/storage error, or an unrecognized X-Storage-Type value. Real code: FILE_DOWNLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to read the requested file from storage.", "innerErrors": [ { "code": "FILE_DOWNLOAD_FAILED", "message": "Failed to read the requested file from storage.", "userMessage": "Something went wrong while downloading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/attachment/upload": { "post": { "tags": [ "Envelope", "Attachment" ], "summary": "Envelope Attachment Upload", "description": "Uploads one or more attachments to a specific envelope (e.g. supporting files, contracts, or other materials providing context for digital signing). Form-data only — there is no JSON/raw-body alternative for this operation. No file-extension or content-type validation of any kind is performed by the backend — this is the widest-open upload operation in the group; any file type is accepted. Genuinely supports TWO alternate, mutually exclusive auth contracts (intentional dual-mode design, not a bug), identical in structure to the sibling download operation: (1) anonymous mode — a Guid-parseable tid query parameter is present, and no Authorization header is required; or (2) authenticated mode — no valid tid is supplied, so a real Authorization bearer token IS required, and the caller must be the envelope's creator or a signer on it. After upload, each file is assigned a unique id that can be referenced in processes like envelope creation. Max File Size: Production 20 MB, Staging 10 MB.", "operationId": "signatures-upload-attachment", "parameters": [ { "name": "envelopeId", "in": "path", "description": "GUID of the envelope to attach the file(s) to.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. When present and Guid-parseable, selects anonymous mode and no Authorization header is required. When absent or not Guid-parseable, authenticated mode applies and Authorization is required instead.", "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Service-to-service auth token, used as an alternative to `Authorization` in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Client-Authorization", "in": "header", "description": "Client auth token, used as an alternative to `Authorization` in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Email", "in": "header", "description": "Caller email, used for identity resolution in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-OAuth-Flow", "in": "header", "description": "Indicates which OAuth flow variant issued the Authorization token, in authenticated mode.", "schema": { "type": "string" } }, { "name": "X-Origin", "in": "header", "description": "Free-form caller-supplied origin identifier. Not validated; echoed back verbatim into the response envelope's origin field. Optional.", "schema": { "type": "string" }, "example": "https://app.mavenmule.com" }, { "name": "X-Storage-Type", "in": "header", "description": "Container-type key for the uploaded attachment. Expected value is `envelope-attachment`.", "required": true, "schema": { "type": "string" }, "example": "envelope-attachment" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "array", "description": "One or more attachment files to upload. No extension or content-type validation is performed — any file type is accepted. Order is preserved in the response.", "required": true } }, "type": "object" } } } }, "responses": { "201": { "description": "This is the response returned when an attachment is successfully added to the envelope. The added attachment gets an id that can be referenced in other endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSuccessResponse" }, "example": { "result": { "data": { "files": [ { "id": "76bb2621-b1b1-4d47-9132-c4d1e5f60abc", "fileName": "SampleAttachment.jpg" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://dev.headless.mavenmule.com/signatures/envelope/7a5d60-a222-4c3e490ef1/attachment/upload", "dateTime": "2025-11-03T06:48:58.0000000+00:00", "operationId": "ea5716c820f26295b44c2fb2" } } } }, "400": { "description": "The request was not multipart/form-data, or no file was supplied. Real code: FORM_DATA_EXPECTED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 400, "message": "Request must be multipart/form-data.", "innerErrors": [ { "code": "FORM_DATA_EXPECTED", "message": "Request must be multipart/form-data.", "userMessage": "Request must be multipart/form-data." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "401": { "description": "Missing or invalid authentication (does not apply when a valid `tid` is supplied).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "403": { "description": "The anonymous-mode owner was resolved via tid but their subscription is inactive/invalid. Real code: ENVELOPE_OWNER_INVALID_SUBSCRIPTION.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 403, "message": "The envelope owner's subscription is not active.", "innerErrors": [ { "code": "ENVELOPE_OWNER_INVALID_SUBSCRIPTION", "message": "The envelope owner's subscription is not active.", "userMessage": "This envelope can't accept uploads right now." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "404": { "description": "The tid didn't resolve to a valid transaction/envelope pair (ENVELOPE_NOT_FOUND_TID); the resolved envelope owner no longer exists (ENVELOPE_OWNER_NOT_FOUND); or, in authenticated mode, the caller is neither the envelope's creator nor a signer on it (ENVELOPE_NOT_FOUND_USER_AND_ENVELOPE_ID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 404, "message": "Envelope not found for the supplied user and envelope id.", "innerErrors": [ { "code": "ENVELOPE_NOT_FOUND_USER_AND_ENVELOPE_ID", "message": "Envelope not found for the supplied user and envelope id.", "userMessage": "We couldn't find that envelope, or you don't have access to it." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } }, "500": { "description": "The file could not be stored due to a server/storage error, or an unrecognized X-Storage-Type value. Real code: FILE_UPLOAD_FAILED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlessErrorResponse" }, "example": { "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/audit/download": { "get": { "tags": [ "Envelope", "AuditTrail" ], "summary": "Envelope Audit Log Download", "description": "Retrieves the audit trail for a specific envelope as a downloadable file.
\n* The file provides a formal record of the envelope’s lifecycle for compliance, auditing, or record-keeping purposes.\n* The envelope is identified using the envelopeId path parameter.\n* The request returns the audit trail as a binary stream (application/octet-stream). Response is NOT wrapped in the standard result envelope - raw PDF bytes are returned directly, but with Content-Type application/octet-stream (not application/pdf) as actually set by the server.", "operationId": "signatures-download-envelope-audit", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope where the attachment will be added.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The audit trail PDF's bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/audit/get": { "get": { "tags": [ "Envelope", "AuditTrail" ], "summary": "Envelope Audit Log Get", "description": "Retrieves the audit trail for a specific envelope in JSON format.
\n* The envelope is identified using the envelopeId path parameter.\n* The JSON response contains a detailed log of all actions related to the envelope, including creation, sending, legal terms acceptance, receipt, and signing, performed by users or recipients.\n* This endpoint tracks the envelope’s lifecycle, supporting transparency, compliance, and accountability in the document signing workflow. No tid/recipient access - authenticated envelope owner/participant only.", "operationId": "signatures-get-getenvelopeaudittrail", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope where the attachment will be added.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit trail retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "auditTrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "nullable": true, "readOnly": true }, "signGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "nullable": true, "readOnly": true }, "action": { "type": "string", "readOnly": true }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "ipAddress": { "type": "string", "nullable": true, "readOnly": true }, "additionalInfo": { "type": "string", "description": "Free text or JSON depending on the action type - not a single consistent format.", "nullable": true, "readOnly": true } } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "auditTrails": [ { "id": "string", "user": { "id": "string", "name": "string", "email": "string" }, "recipient": { "id": "string", "name": "string", "email": "string" }, "signGroup": { "id": "string", "name": "string" }, "action": "string", "timestamp": "string", "ipAddress": "string", "additionalInfo": "string" } ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/cancel": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Cancel ", "description": "Terminates the signing process by canceling a sent envelope.
\n* The envelope is identified using the envelopeId path parameter.\n* Once canceled, the envelope transitions to a final state of \"Canceled\", preventing any further actions by recipients (e.g., viewing or signing documents).\n* Use this endpoint when a sender needs to stop the process, for example, due to errors in the envelope, changes in requirements, or other reasons. Note: this is a state-mutating operation exposed as GET. It also performs no status-precondition check - it can be called against an envelope in any status, including one already Completed, Deleted, or Canceled.", "operationId": "signatures-cancel-envelope", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope which Audit trail is needed.", "required": true, "schema": { "type": "string" } }, { "name": "X-Origin-IpAddress", "in": "header", "description": "Caller IP address, recorded in the audit trail. Not validated.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope canceled.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/check": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Check", "description": "Verifies whether all required actions to open an envelope have been completed.
\n* The envelope is identified using the transactionId (tid) query parameter, typically obtained from the GET /signatures/envelope/list endpoint.\n* The endpoint checks for completion of required actions, such as legal terms acceptance.", "operationId": "signatures-envelope-check", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true } }, "readOnly": true }, "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" }, "isTokenExpired": { "type": "boolean" }, "legalAccepted": { "type": "boolean" }, "isMfaEnabled": { "type": "boolean" }, "isMfaValid": { "type": "boolean" }, "hostEmail": { "type": "string", "nullable": true }, "hasUser": { "type": "boolean" } }, "readOnly": true }, "settings": { "type": "array", "items": { "type": "object" }, "description": "Filtered to settings flagged anonymous-visible; full shape defined externally.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "uploadDate": "string", "status": "string", "subject": "string", "createdBy": { "id": "string", "name": "string", "email": "string" } }, "recipient": { "id": "string", "role": "signer", "name": "string", "email": "string", "status": "string", "isTokenExpired": true, "legalAccepted": true, "isMfaEnabled": true, "isMfaValid": true, "hostEmail": "string", "hasUser": true }, "settings": [ {} ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/count": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Count", "description": "The endpoint retrieves the number of envelopes and divides them by folders. No tid/recipient access - authenticated user only.", "operationId": "signatures-envelope-count", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelopes": { "type": "object", "properties": { "inbox": { "type": "integer" }, "sent": { "type": "integer" }, "drafts": { "type": "integer" }, "trash": { "type": "integer" }, "todo": { "type": "integer" }, "expiring": { "type": "integer" }, "pending": { "type": "integer" }, "completed": { "type": "integer" } }, "description": "Fixed set of 8 counters.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "userId": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelopes": { "inbox": 0, "sent": 0, "drafts": 0, "trash": 0, "todo": 0, "expiring": 0, "pending": 0, "completed": 0 } } }, "origin": "string", "dateTime": "string", "userId": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/create": { "post": { "tags": [ "Envelope" ], "summary": "Envelope Create", "description": "Creates an envelope containing one or more documents, designated recipients, and signature fields.
\n* Documents must first be uploaded via the Storage endpoint and linked to recipients using referenceDocumentId and referenceSignerId.\n* Recipients are assigned roles (e.g., signer) and can be configured as mandatory or optional.\n* Signature fields are positioned precisely within documents and can include optional styling.\n* Envelope metadata includes:\n * Email subject.\n * Email message.\n * Sender details.\n * Signing order.\n * Expiration settings.\n * Reminders.\n * Notification triggers for signature events.", "operationId": "signatures-post-savepreparedenvelope", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeUpsertRequest" }, "example": { "documents": [ { "referenceDocumentId": 1, "name": "Test Document Name", "loadMethod": "Storage", "urn": "{{uploadedDocument}}", "externalContext": { "id": "123" } } ], "recipients": [ { "referenceSignerId": 1, "name": "Test Example", "email": "user@example.com", "role": "signer", "mandatory": true, "externalContext": { "id": "456" } } ], "fields": [ { "type": "text", "isRequired": true, "referenceSignerId": 1, "referenceDocumentId": 1, "positionX": 10, "positionY": 10, "height": 100, "width": 100, "page": 1, "name": "mds_signature1", "properties": { "fontFamily": "Arial", "fontSize": 13, "color": "red", "bold": true, "italic": true, "underline": true, "textAlign": "center" } } ], "envelope": { "subject": "Email Subject", "message": "Email Message", "senderName": "Sender Example", "senderEmail": "sender@example.com", "isSignOrder": false, "expireInDays": 5, "alertDaysBeforeExpiry": 5, "firstReminderDays": 3, "repeatingReminderDays": 2, "notifyWhenOpened": true, "notifyWhenSigned": true }, "externalContext": { "id": "789" } } } } }, "responses": { "201": { "description": "Envelope draft created.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; absent on update.", "format": "date-time" }, "status": { "type": "string", "description": "Always \"Draft\" immediately after create/update." } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "consumption": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "value": { "type": "integer" } } }, "description": "Present only on metered operations.", "readOnly": true }, "externalContext": { "description": "Echoed verbatim from the request; opaque, not validated.", "nullable": true } } }, "example": { "result": { "statusCode": 201, "message": "Created", "data": { "envelope": { "id": "string", "uploadDate": "string", "status": "string" }, "documents": [ { "id": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "externalContext": {} } ], "signGroups": [ { "id": "string" } ], "fields": [ { "id": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string" } ] } }, "origin": "string", "dateTime": "string", "consumption": [ { "dimension": "string", "value": 0 } ], "externalContext": {} } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/{templateId}/envelope/create": { "post": { "tags": [ "Envelope", "Template" ], "summary": "Envelope Create From Template", "description": "Creates an envelope based on a provided template.
\n* Use the templateId parameter to specify the template.\n* Documents must first be uploaded via the Storage endpoint and linked to recipients using referenceDocumentId and referenceSignerId.\n* Template roles are converted into envelope recipients. Recipients/signGroups provided in the request override the matching stored template recipient by templateRole; anything omitted falls back to the template's stored value.", "operationId": "signatures-envelope-create-from-template", "parameters": [ { "name": "templateId", "in": "path", "description": "The ID of the template based on which the envelope is created.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } } }, "recipients": { "type": "array", "items": { "required": [ "templateRole" ], "type": "object", "properties": { "templateRole": { "type": "string", "description": "Matched case-insensitively against the template's stored recipient templateRole values. A non-matching value is silently ignored (the template's own stored recipient is used unchanged), not an error." }, "name": { "type": "string", "description": "Overrides the template's stored value; omit to keep the template's value.", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "hostEmail": { "type": "string", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "externalContext": { "nullable": true } } } }, "signGroups": { "type": "array", "items": { "required": [ "templateRole" ], "type": "object", "properties": { "templateRole": { "type": "string" }, "name": { "type": "string", "nullable": true } } } }, "externalContext": { "nullable": true } } }, "example": { "envelope": { "subject": "TestPostman", "message": "" }, "message": { "subject": "TestPostman", "recipients": [ { "templateRole": "Role1", "name": "RomanK", "email": "roman.khryshchanovich@mavenmule.com" } ] }, "signGroups": [] } } } }, "responses": { "201": { "description": "Envelope created from template.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; omitted on update.", "format": "date-time" } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 201, "message": "Created", "data": { "template": { "id": "string", "uploadDate": "string" }, "documents": [ { "id": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "externalContext": {} } ], "signGroups": [ { "id": "string" } ], "fields": [ { "id": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string" } ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/decline": { "post": { "tags": [ "Envelope" ], "summary": "Envelope Decline", "description": "Declines a sent envelope.
\n* The envelope is identified using the transactionId (tid) query parameter, typically obtained from the GET /signatures/envelope/list endpoint.\n* This endpoint is for recipients only to refuse signing or completing the envelope, for example, due to disagreements with the document content.\n* Senders cannot decline an envelope.\n* Declining an envelope updates its status to \"Declined\". declineReason is required when the envelope's own decline-reason setting requires it.", "operationId": "signatures-declinefunction", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "declineReason": { "type": "string", "nullable": true } } }, "externalContext": { "nullable": true } } }, "example": { "envelope": { "declineReason": "test" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "externalContext": { "description": "Echoed verbatim from the request; opaque, not validated.", "nullable": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string", "externalContext": {} } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/delete": { "delete": { "tags": [ "Envelope" ], "summary": "Envelope Delete", "description": "Deletes a specific envelope from the system.
\n* The envelope is identified using the envelopeId path parameter.\n* Only envelopes in the \"Draft\" state can be deleted, allowing the sender to discard envelopes that have not yet been sent to recipients. This is a soft delete (status set to \"Deleted\") and only works on envelopes currently in Draft status.", "operationId": "signatures-delete-deleteenvelope", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope that should be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope deleted.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/document/{documentId}/download": { "get": { "tags": [ "Envelope", "Document" ], "summary": "Envelope Document Download ", "description": "Downloads a specific document within an envelope.
\n* The envelope is identified using the envelopeId path parameter.\n* The document is identified using the documentId path parameter.\n* The envelope is authenticated via the transactionId (tid) query parameter.\n* The document is returned as a binary stream (application/octet-stream), typically in its original format (e.g., PDF, DOCX) or as a processed version (e.g., signed PDF).", "operationId": "signatures-download-document", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope where the attachment is added.", "required": true, "schema": { "type": "string" } }, { "name": "documentId", "in": "path", "description": "The needed string value.\nThe ID(URN) of the document you would like to download from the defined envelope.\n\n", "required": true, "schema": { "type": "string" } }, { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The signed document's bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/edit": { "put": { "tags": [ "Envelope" ], "summary": "Envelope Edit", "description": "Edits notification-related settings for an already sent envelope.
\n* The envelope is identified using the envelopeId path parameter.\n* This endpoint allows updating:\n * Envelope expiration settings\n * Envelope notification settings, including:\n * Expiration period\n * Alerts for recipients\n* Note: Documents, recipients, or fields within the envelope are not modified — only expiration/notification settings. `expireInDays` must be at least 2 and at least `alertDaysBeforeExpiry`, and the resulting expiry date must not already be in the past.", "operationId": "signatures-changeexpirationdatefunction", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The envelopeId parameter in the URL is a unique identifier for the envelope whose notification settings are being edited. It specifies which already-sent envelope should be updated with the new expiration and alert configurations.", "required": true, "schema": { "type": "string" } }, { "name": "X-Origin-IpAddress", "in": "header", "description": "Caller IP address, recorded in the audit trail. Not validated.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "expireInDays": { "type": "integer" }, "alertDaysBeforeExpiry": { "type": "integer" } } }, "externalContext": { "nullable": true } } }, "example": { "envelope": { "expireInDays": 7, "alertDaysBeforeExpiry": 3 }, "externalContext": { "id": "12345" } } } } }, "responses": { "200": { "description": "Expiration updated.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "description": "Server-generated, DB-configurable label text.", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/get": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Get", "description": "Retrieves details of a specific envelope in JSON format.
\n* The envelope is identified using the envelopeId path parameter.\n* Secure access is ensured via the transactionId (tid) query parameter, restricting visibility to authorized recipients. The tid can be obtained from the GET /signatures/envelope/list endpoint.\n* This endpoint is available to the envelope's owner (via standard authentication) or to a recipient presenting a valid tid.", "operationId": "signatures-get-getenvelopefunction", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the needed envelope.", "required": true, "schema": { "type": "string" } }, { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Envelope retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "uploadDate": { "type": "string", "format": "date-time" }, "sendDate": { "type": "string", "format": "date-time", "nullable": true }, "status": { "enum": [ "Draft", "In Progress", "Completed", "Expired", "Failed", "Deleted", "Declined", "Canceled", "Delivery Failed", "Template" ], "type": "string" }, "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "alertDaysBeforeExpiry": { "type": "integer" }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "originalDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "referenceDocumentId": { "type": "string", "description": "Despite the name, this is the source document's id, not a client-supplied correlation id." }, "name": { "type": "string" } } }, "description": "Pre-conversion source documents.", "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signDate": { "type": "string", "description": "Always null in practice - never assigned anywhere in the codebase despite being present on the model.", "nullable": true }, "signOrder": { "type": "integer" }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "nullable": true }, "isMFAEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "nullable": true }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signOrder": { "type": "integer" }, "mandatory": { "type": "boolean" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "value": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "tooltip": { "type": "string", "nullable": true }, "isRequired": { "type": "boolean" }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." }, "signerInfo": { "description": "Computed on every call by re-parsing the live PDF's digital signature, if any - only populated for signed digitalsignature fields. Not persisted, no fixed schema.", "nullable": true } } }, "readOnly": true }, "comments": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "signerId": { "type": "string", "format": "uuid", "nullable": true }, "parentCommentId": { "type": "string", "format": "uuid", "nullable": true }, "content": { "type": "string", "nullable": true }, "pageNumber": { "type": "integer", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "visibleTo": { "type": "string", "description": "JSON-encoded array AS A STRING (e.g. \"[\\\"a@b.com\\\"]\"), not a native array - a source inconsistency with the write-side shape (see document/{documentId}/comment).", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "authorName": { "type": "string", "nullable": true }, "authorEmail": { "type": "string", "nullable": true } } } }, "description": "Map keyed by document id (as a string) to an array of comments.", "readOnly": true }, "settings": { "type": "array", "items": { "type": "object" }, "description": "Envelope settings; full shape is defined in an external package and not enumerable from this repo's source.", "readOnly": true }, "externalContext": { "nullable": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "externalContext": { "description": "Echoed verbatim from the request; opaque, not validated.", "nullable": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "createdBy": { "id": "string", "name": "string", "email": "string" }, "uploadDate": "string", "sendDate": "string", "status": "Draft", "subject": "string", "message": "string", "isSignOrder": true, "expireInDays": 0, "firstReminderDays": 0, "repeatingReminderDays": 0, "notifyWhenOpened": true, "notifyWhenSigned": true, "alertDaysBeforeExpiry": 0, "locale": "string", "timezone": "string" }, "documents": [ { "id": "string", "name": "string", "externalContext": {} } ], "originalDocuments": [ { "id": "string", "referenceDocumentId": "string", "name": "string" } ], "recipients": [ { "id": "string", "name": "string", "email": "string", "role": "signer", "status": "string", "signDate": "string", "signOrder": 0, "signGroupId": "string", "userId": "string", "mandatory": true, "hostEmail": "string", "isMFAEnabled": true, "phoneNumber": "string", "externalContext": {} } ], "signGroups": [ { "id": "string", "name": "string", "role": "signer", "status": "string", "signOrder": 0, "mandatory": true } ], "fields": [ { "id": "string", "name": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string", "type": "signature", "value": "string", "page": 0, "height": 0, "width": 0, "positionX": 0, "positionY": 0, "tooltip": "string", "isRequired": true, "properties": { "fontFamily": "string", "fontSize": 0, "color": "string", "bold": true, "italic": true, "underline": true, "textAlign": "string", "placeholder": "string", "isSignedDate": true, "selectionGroup": "string", "selectionValue": "string" }, "signerInfo": {} } ], "comments": {}, "settings": [ {} ], "externalContext": {} } }, "origin": "string", "dateTime": "string", "externalContext": {} } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/list": { "get": { "tags": [ "Envelope" ], "summary": "Envelope List", "description": "Retrieves a list of all envelopes associated with the authenticated user, including those created/sent by the user and those where the user is a recipient.
\n* Supports filtering, sorting, and pagination via query parameters to help developers query specific envelopes.\n* Query Parameters:\n * top (integer). Maximum number of envelopes to return (e.g., 25).\n * skip (integer). Number of envelopes to skip in the sorted results (e.g., 0).\n * sort (string). Column to sort by. Valid values: Subject, Recipients, Documents, Status, UploadDate, ExpireInDays.\n * order (string). Sort direction. Valid values: ASC, DESC.\n * folder (string). Folder to query. Valid values: Inbox, Sent, Drafts, Deleted, Action Required, Expiring Soon, Waiting for Others, Completed.\n * filter (JSON array). List of filter objects to refine results. Each filter includes:\n * column (string). Field to filter on (matches sort values).\n * condition (string). Filter condition:\n * For stringFilter: EMPTY, NOT_EMPTY, CONTAINS, CONTAINS_CASE_SENSITIVE, DOES_NOT_CONTAIN, DOES_NOT_CONTAIN_CASE_SENSITIVE, STARTS_WITH, STARTS_WITH_CASE_SENSITIVE, ENDS_WITH, ENDS_WITH_CASE_SENSITIVE, EQUAL, EQUAL_CASE_SENSITIVE, NULL, NOT_NULL.\n * For dateFilter: EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, NULL, NOT_NULL.\n * value (string). Filter value:\n * string for stringFilter.\n * YYYY-MM-DD for dateFilter.\n * type (string):\n * Either stringFilter.\n * dateFilter.\n * key (string). Unique 12-character alphanumeric identifier for the filter.\n\nFilter example:
\n`envelope/list?$top=25&$skip=0&$sort=Subject&$order=ASC&$filter=[{\"column\":\"status\",\"condition\":\"CONTAINS\",\"value\":\"Failed\",\"type\":\"stringFilter\",\"key\":\"6e2d9f910ad9\"},{\"column\":\"uploadDate\",\"condition\":\"EQUAL\",\"value\":\"2025-06-30\",\"type\":\"dateFilter\",\"key\":\"068d7e1baf7d\"}]&$folder=Inbox` Note: sort/order are documented here as two separate params for developer convenience, but the server actually reads a single combined orderby=\"|\" query parameter - see the orderby parameter description. The folder values below are read via a filter[] entry with key=\"folder\", there is no separate folder= query parameter.", "operationId": "signatures-get-envelope-page", "parameters": [ { "name": "sort", "in": "query", "description": "Column to sort by the results.", "schema": { "enum": [ "Subject", "Recipients", "Documents", "Status", "UploadDate", "ExpireInDays" ], "type": "string" } }, { "name": "order", "in": "query", "description": "The direction of the sort.", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "folder", "in": "query", "description": "Specifies the envelope folder to query.", "schema": { "enum": [ "Inbox", "Sent", "Drafts", "Deleted", "Action Required", "Expiring Soon", "Waiting for Others", "Completed" ], "type": "string" } }, { "name": "top", "in": "query", "description": "Max rows to return.", "schema": { "type": "integer", "default": 100 } }, { "name": "skip", "in": "query", "description": "Rows to skip. Defaults to 0 if omitted or not a valid integer.", "schema": { "type": "integer", "default": 0 } }, { "name": "orderby", "in": "query", "description": "Combined param, format \"|\" (literal pipe). Defaults to `UploadDate DESC` if omitted or not recognized.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of FilterInput objects. column/key values are interpolated into the underlying query with no allow-list. One entry with key=\"folder\" selects a view: inbox, sent, drafts, trash, todo, expiring, pending, completed, or (default) everything owned by or recipient-of the caller.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelopes retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "creatorGuid": { "type": "string", "description": "Duplicate of createdBy.id.", "format": "uuid", "readOnly": true }, "status": { "type": "string", "readOnly": true }, "uploadDate": { "type": "string", "format": "date-time", "readOnly": true }, "sendDate": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "subject": { "type": "string", "nullable": true, "readOnly": true }, "transactionTokenId": { "type": "string", "nullable": true, "readOnly": true }, "documents": { "type": "string", "description": "JSON-encoded array AS A STRING, not a native array (raw SQL FOR JSON PATH output returned unparsed).", "readOnly": true }, "recipients": { "type": "string", "description": "JSON-encoded array AS A STRING; same caveat as documents.", "readOnly": true }, "signGroups": { "type": "string", "description": "JSON-encoded array AS A STRING; same caveat as documents.", "readOnly": true }, "isSignOrder": { "type": "boolean", "readOnly": true }, "recipientStatus": { "type": "string", "description": "The current caller's own signer-status on this envelope; may be empty.", "readOnly": true }, "expireInDays": { "type": "integer", "readOnly": true }, "alertDaysBeforeExpiry": { "type": "integer", "readOnly": true } } } }, "rowCount": { "type": "integer", "description": "Total matching rows regardless of top/skip.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelopes": [ { "id": "string", "createdBy": { "id": "string", "name": "string", "email": "string" }, "creatorGuid": "string", "status": "string", "uploadDate": "string", "sendDate": "string", "subject": "string", "transactionTokenId": "string", "documents": "string", "recipients": "string", "signGroups": "string", "isSignOrder": true, "recipientStatus": "string", "expireInDays": 0, "alertDaysBeforeExpiry": 0 } ], "rowCount": 0 } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/open": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Open", "description": "Opens a sent envelope as a recipient to view or sign documents.
\n* The envelope is identified using the transactionId (tid) query parameter, which can be obtained from the GET /signatures/envelope/list endpoint. tid is effectively required even for a logged-in caller, because the server always resolves a transaction token as part of authorization on this operation.", "operationId": "signatures-get-startenveloperecipientprocess", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "nullable": true }, "status": { "type": "string" }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer" }, "uploadDate": { "type": "string", "format": "date-time" }, "sendDate": { "type": "string", "format": "date-time", "nullable": true }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signDate": { "type": "string", "nullable": true }, "signOrder": { "type": "integer" }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signOrder": { "type": "integer" }, "mandatory": { "type": "boolean" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "value": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "tooltip": { "type": "string", "nullable": true }, "isRequired": { "type": "boolean" }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." }, "signerInfo": { "description": "Certificate metadata, only for signed digitalsignature fields; computed, no fixed schema.", "nullable": true } } }, "description": "Filtered server-side to fields relevant to the caller unless the caller is done/canceled or has role viewer/cc - the set returned is viewer-dependent, not a fixed \"all fields\" list.", "readOnly": true }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "urn": { "type": "string", "description": "Opaque storage reference; format not defined by this service." }, "mimeType": { "type": "string", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "description": "Derived from attachment-type field values. Does NOT include the attachment bytes (the underlying model has a Data property but this operation never populates or returns it) and there is no attachment id - documentId here is the parent document's id.", "readOnly": true }, "signer": { "type": "string", "description": "The caller's own signer id.", "format": "uuid", "readOnly": true }, "comments": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } }, "description": "Map keyed by document id; see envelope/{envelopeId}/get for the full comment shape.", "readOnly": true }, "savedSignatures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "data": { "type": "string", "description": "No format enforced." }, "isDefault": { "type": "boolean" } } }, "readOnly": true }, "settings": { "type": "array", "items": { "type": "object" }, "description": "Filtered to anonymous-visible settings.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "createdBy": { "id": "string", "name": "string", "email": "string" }, "subject": "string", "message": "string", "senderName": "string", "senderEmail": "string", "status": "string", "notifyWhenOpened": true, "notifyWhenSigned": true, "isSignOrder": true, "expireInDays": 0, "uploadDate": "string", "sendDate": "string", "locale": "string", "timezone": "string" }, "documents": [ { "id": "string", "name": "string" } ], "recipients": [ { "id": "string", "name": "string", "email": "string", "role": "signer", "status": "string", "signDate": "string", "signOrder": 0, "signGroupId": "string", "userId": "string", "mandatory": true, "hostEmail": "string" } ], "signGroups": [ { "id": "string", "name": "string", "role": "signer", "status": "string", "signOrder": 0, "mandatory": true } ], "fields": [ { "id": "string", "name": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string", "type": "signature", "value": "string", "page": 0, "height": 0, "width": 0, "positionX": 0, "positionY": 0, "tooltip": "string", "isRequired": true, "properties": { "fontFamily": "string", "fontSize": 0, "color": "string", "bold": true, "italic": true, "underline": true, "textAlign": "string", "placeholder": "string", "isSignedDate": true, "selectionGroup": "string", "selectionValue": "string" }, "signerInfo": {} } ], "attachments": [ { "name": "string", "urn": "string", "mimeType": "string", "documentId": "string" } ], "signer": "string", "comments": {}, "savedSignatures": [ { "id": "string", "data": "string", "isDefault": true } ], "settings": [ {} ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/reassign": { "post": { "tags": [ "Envelope" ], "summary": "Envelope Reassign", "description": "Redirects a received envelope to another user.
\n* The envelope is identified using the transactionId (tid) query parameter, which can be obtained from the GET /signatures/envelope/list endpoint.\n* This endpoint allows the recipient to forward the envelope to another user instead of completing it. email is required and matched case-insensitively against existing recipients. phoneNumber is required only if the current recipient being reassigned has MFA enabled. Only allowed when the current recipient's role is signer and its status is In Progress.", "operationId": "signatures-envelope-reassign", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true } } }, "externalContext": { "nullable": true } } }, "example": { "recipient": { "name": "string", "email": "string", "reason": "string", "phoneNumber": "string" }, "externalContext": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/resend": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Resend", "description": "Resends a sent envelope to its recipients when the original email link has expired.
\n* The envelope is identified using the transactionId (tid) query parameter, which can be obtained from the GET /signatures/envelope/list endpoint.\n* This endpoint generates a new email notification containing a fresh, secure link for recipients to access the envelope. This operation only resends when the existing link has actually expired — if it hasn't, the server returns `LINK_NOT_EXPIRED` instead of resending.", "operationId": "signatures-get-resendlink", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/restore": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Restore", "description": "Restores a previously deleted draft envelope.
\n* The envelope is identified using the envelopeId path parameter.\n* This endpoint allows the sender to recover an envelope deleted while in the \"Draft\" state.\n* Upon restoration, the envelope returns to the \"Draft\" state, enabling the sender to continue editing or sending it. Note: state-mutating operation exposed as GET. Always restores to Draft status; only works on envelopes currently in Deleted status.", "operationId": "signatures-post-restoreenvelope", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The ID of the envelope that should be restored.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope restored.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/send": { "get": { "tags": [ "Envelope" ], "summary": "Envelope Send", "description": "Sends a created envelope to its designated recipients.
\n* The envelope is identified using the envelopeId path parameter.\n* Once sent, recipients receive email notifications to review and sign the documents contained within the envelope. No request body - validates and sends the already-persisted draft. Sender-only (must be the envelope's creator); no tid/recipient access. Only works on envelopes currently in Draft status.", "operationId": "signatures-post-sendpreparedenvelope", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The unique identifier of the envelope that you want to send. This ID is returned when an envelope is initially created via the /signatures/envelope/create endpoint. It is used to reference the specific envelope containing documents, recipients, and fields that are ready to be dispatched for digital signing.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope sent.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "consumption": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "value": { "type": "integer" } } }, "description": "Present only on metered operations.", "readOnly": true }, "userId": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string", "consumption": [ { "dimension": "string", "value": 0 } ], "userId": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/sign": { "post": { "tags": [ "Envelope" ], "summary": "Envelope Sign", "description": "Signs a sent and opened envelope.
\n* The envelope is identified using the transactionId (tid) query parameter, typically obtained from the email link sent to the recipient or via the GET /signatures/envelope/list endpoint.\n* Field IDs required in the request body can be retrieved from the endpoint that provides details about the open envelope.\n* This endpoint allows recipients to apply signatures and fill required fields (e.g., initials, text, checkboxes) to complete their signing obligations. For an in-person signer, the host must be a logged-in user matching the recipient's hostEmail (`HOST_USER_NOT_MATCHING` otherwise). Returns 202 instead of 200 when the digital-signature flow requires an additional client-side step to complete.", "operationId": "signatures-post-signenvelope", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Must reference one of the current signer's/sign-group's own fields.", "format": "uuid" }, "value": { "type": "string", "description": "Required only if the field was configured isRequired at envelope-creation time (resolved server-side, not expressible as a static constraint here). For attachment-type fields, expected to be a JSON string of [{name, urn, mimeType}] - this is NOT validated on input; malformed JSON is silently dropped downstream, not rejected.", "nullable": true }, "certificate": { "type": "string", "description": "Base64 certificate blob for the digital-signature partial-hash flow. Stored/consumed as-is; no format enforced by this service.", "nullable": true }, "signedData": { "type": "string", "description": "Part of the digital-signature round trip; no format enforced by this service.", "nullable": true } } } }, "externalContext": { "nullable": true } } }, "example": { "externalContext": { "id": "12345" }, "fields": [ { "id": "{{fieldId}}", "value": "{{fieldValue}}" } ] } } } }, "responses": { "200": { "description": "Envelope signed.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "202": { "description": "Digital-signature partial-hash step accepted; client must complete the signing round trip.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 202 }, "message": { "type": "string", "readOnly": true, "example": "Accepted" }, "data": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object" }, "description": "Opaque payload produced by an external PDF-processing component; shape not defined in this repo." } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 202, "message": "Accepted", "data": { "fields": [ {} ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/envelope/{envelopeId}/update": { "put": { "tags": [ "Envelope", "Content" ], "summary": "Envelope Update ", "description": "Updates an envelope that is created but not yet sent for signing.
\n* The envelope must be in the \"Draft\" status.\n* The envelope is identified using the envelopeId path parameter.\n* This endpoint allows modification of:\n * Envelope documents.\n * Recipients.\n * Fields.\n * Envelope settings.\n * Associated metadata.\n* Use this endpoint to revise envelope details before initiating the signing process. Replaces the entire draft's documents/recipients/signGroups/fields.", "operationId": "signatures-update-envelope", "parameters": [ { "name": "envelopeId", "in": "path", "description": "The unique identifier of the envelope to be updated. This ID is generated when the envelope is first created and is used to reference and modify the envelope before it is sent to recipients. It must match an existing envelope that is still in a draft (unsent) status.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeUpsertRequest" }, "example": { "documents": [ { "referenceDocumentId": 1, "name": "Test Document Name", "loadMethod": "Storage", "urn": "{{uploadedDocument}}" } ], "recipients": [ { "referenceSignerId": 1, "name": "Test Example", "email": "user@example.com", "role": "signer", "mandatory": true } ], "fields": [ { "type": "signature", "isRequired": true, "referenceSignerId": 1, "referenceDocumentId": 1, "positionX": 10, "positionY": 10, "height": 100, "width": 100, "page": 1, "name": "mds_signature1", "properties": { "fontFamily": "Arial", "fontSize": 13, "color": "red", "bold": true, "italic": true, "underline": true, "textAlign": "center" } } ], "envelope": { "subject": "Email Subject", "message": "Email Message", "senderName": "Sender", "senderEmail": "sender@example.com", "isSignOrder": false, "expireInDays": 5, "alertDaysBeforeExpiry": 5, "firstReminderDays": 3, "repeatingReminderDays": 2, "notifyWhenOpened": true, "notifyWhenSigned": true }, "externalContext": { "id": "12345" } } } } }, "responses": { "200": { "description": "Envelope draft updated.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; absent on update.", "format": "date-time" }, "status": { "type": "string", "description": "Always \"Draft\" immediately after create/update." } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "envelope": { "id": "string", "uploadDate": "string", "status": "string" }, "documents": [ { "id": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "externalContext": {} } ], "signGroups": [ { "id": "string" } ], "fields": [ { "id": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string" } ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/file/retrieve": { "get": { "tags": [ "Document" ], "summary": "File Retrieve", "description": "Downloads a document using its URL.
\n* Use the documentURL parameter to specify the document link.\n* The request returns the document as a binary stream (application/octet-stream). Response is NOT wrapped in the standard result envelope - raw binary is returned directly, always with Content-Type application/octet-stream even for PDFs.", "operationId": "signatures-post-getfilefromurl", "parameters": [ { "name": "fileUrl", "in": "query", "description": "URL of the file to retrieve and return to the caller.", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "The requested file's bytes, streamed back as-is (DOCX inputs are converted to PDF server-side first; PDFs pass through unchanged).", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "example": "" } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/folder/create": { "post": { "tags": [ "Folder" ], "summary": "Folder Create", "description": "Creates a new folder in the specified namespace to organize documents and envelopes.", "operationId": "signatures-folder-create", "requestBody": { "description": "The folder object to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUpsertRequest" }, "example": { "folder": { "name": "Q3 Financial Contracts" } } } } }, "responses": { "201": { "description": "Folder created successfully.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "description": "Server-generated, DB-configurable label text - not a fixed enum.", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "folder": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Folder saved." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/folder/{folderId}/delete": { "delete": { "tags": [ "Folder" ], "summary": "Folder Delete", "description": "Deletes a specific folder from the system.", "operationId": "signatures-folder-delete", "parameters": [ { "name": "folderId", "in": "path", "description": "The unique identifier (GUID) of the folder to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Folder deleted successfully.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "folder": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Folder deleted." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/folder/{folderId}/get": { "get": { "tags": [ "Folder" ], "summary": "Folder Get", "description": "Retrieves the details and metadata of a specific folder using its unique ID.", "operationId": "signatures-folder-get", "parameters": [ { "name": "folderId", "in": "path", "description": "The unique identifier (GUID) of the folder to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Folder details retrieved successfully.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string" } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "folder": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Q3 Financial Contracts" } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/folder/list": { "get": { "tags": [ "Folder" ], "summary": "Folder List", "description": "Retrieves a paginated list of all folders associated with the authenticated user or namespace.", "operationId": "signatures-folder-list", "parameters": [ { "name": "top", "in": "query", "description": "Maximum number of folders to return.", "schema": { "type": "integer" } }, { "name": "skip", "in": "query", "description": "Number of folders to skip in the sorted results.", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Column to sort the results by (e.g., Name).", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort direction (ASC or DESC).", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "List of folders retrieved successfully.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "folder": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string" } } }, "description": "Full, unpaginated list for the authenticated user. Key is singular despite being a list." } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "folder": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Q3 Financial Contracts" } ] } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/folder/{folderId}/update": { "put": { "tags": [ "Folder" ], "summary": "Folder Update", "description": "Updates the properties (such as the Name) of an existing folder.", "operationId": "signatures-folder-update", "parameters": [ { "name": "folderId", "in": "path", "description": "The unique identifier (GUID) of the folder to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The folder object containing updated values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUpsertRequest" }, "example": { "folder": { "name": "Q3 Financial Contracts (renamed)" } } } } }, "responses": { "200": { "description": "Folder updated successfully.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "folder": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Folder saved." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/mfa/initiate": { "post": { "tags": [ "Envelope", "MFA" ], "summary": "MFA Initiate", "description": "Initiates the multi-factor authentication (MFA) process.
\n* The request generates an authentication code and sends it to the specified phone number or email address. No request body - the server reads nothing from the body for this operation.", "operationId": "signatures-mfa-initiate", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "method": { "type": "string", "description": "Always the literal value \"email\" in the current implementation, even when the server actually delivered the code via SMS - the response field is hard-coded and does not reflect the real channel. Documented as observed, not as intended behavior.", "example": "email" }, "destination": { "type": "object", "properties": { "email": { "type": "string" } } }, "expiresAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "method": "email", "destination": { "email": "string" }, "expiresAt": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/mfa/verify": { "post": { "tags": [ "Envelope", "MFA" ], "summary": "MFA Verify", "description": "Verifies the code sent as part of the multi-factor authentication (MFA) process.
\n* Use this endpoint to confirm the authentication code received via phone or email.\n", "operationId": "signatures-mfa-verify", "parameters": [ { "name": "tid", "in": "query", "description": "Transaction token identifying a specific recipient+envelope pair. Required for anonymous/recipient access (no Authorization header, or the header doesn't resolve to the envelope owner).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "Matched by exact string equality server-side; no format/length constraint is enforced on input." } } }, "externalContext": { "nullable": true } } }, "example": { "recipient": { "code": "string" }, "externalContext": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "method": { "type": "string", "description": "Always the literal value \"email\" in the current implementation, even when the server actually delivered the code via SMS - the response field is hard-coded and does not reflect the real channel. Documented as observed, not as intended behavior.", "example": "email" }, "destination": { "type": "object", "properties": { "email": { "type": "string" } } }, "message": { "type": "string" } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "recipient": { "method": "email", "destination": { "email": "string" }, "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/signature/create": { "post": { "tags": [ "Envelope", "Signature" ], "summary": "Signature Create", "description": "Creates and stores a user’s signature in the Storage system.
\n* The signature is represented as a Base64-encoded image (e.g., PNG or JPG).\n* Each signature is assigned a unique ID, which can be used in other operations to reference the signature.\n* Users can save multiple signatures and optionally designate one as the default for the signing process.", "operationId": "signatures-post-savedefaultsignature", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSignatureUpsertRequest" }, "example": { "signature": { "value": "data:image/png;base64,iVBORw0KGgo...", "isDefault": true } } } } }, "responses": { "201": { "description": "This is the response returned when the envelope is successfully declined.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "signature": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "signature": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Signature saved." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/signature/{signatureId}/delete": { "delete": { "tags": [ "Envelope", "Signature" ], "summary": "Signature Delete", "description": "Removes a specific signature from the Storage system.
\n* The signature is identified using the signatureId path parameter.\n* This endpoint allows users to delete a previously stored signature associated with their account.", "operationId": "signatures-delete-signature", "parameters": [ { "name": "signatureId", "in": "path", "description": "The ID of the signature that should be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "This response indicates that the signature identified by the provided signatureId was successfully deleted.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "signature": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "signature": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Signature deleted." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/signature/{signatureId}/get": { "get": { "tags": [ "Envelope", "Data", "Signature" ], "summary": "Signature Get", "description": "Retrieves details about a specific signature stored in the system.
\n* The signature is identified using the signatureId path parameter.\n* The endpoint returns the signature and its associated metadata in JSON format.", "operationId": "signatures-get-signature", "parameters": [ { "name": "signatureId", "in": "path", "description": "The ID of the signature which information should be retrieved.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "This is the response returned when the signature is successfully retrieved.
\nThe response includes all the needed signature data.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "signature": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "data": { "type": "string", "description": "Raw stored signature value; no format enforced." }, "isDefault": { "type": "boolean" } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "signature": { "id": "123e4567-e89b-12d3-a456-426614174000", "data": "data:image/png;base64,iVBORw0KGgo...", "isDefault": true } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/signature/list": { "get": { "tags": [ "Envelope", "Signature" ], "summary": "Signature List", "description": "Retrieves a list of all signatures associated with the authenticated user.
\n* Each signature includes the following metadata:\n * Unique ID\n * Whether the signature is marked as default\n * Base64-encoded image data Deliberately omits the signature value/data - use signature/{signatureId}/get to retrieve it.", "operationId": "signatures-get-signatures-list", "responses": { "200": { "description": "This is the response returned when the list of available signatures is successfully retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "signature": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "isDefault": { "type": "boolean" } } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "signature": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "isDefault": true } ] } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/signature/{signatureId}/update": { "put": { "tags": [ "Envelope", "Signature" ], "summary": "Signature Update", "description": "Updates an existing saved signature for a user.
\n* The signature is identified using the signatureId path parameter.\n* This endpoint allows updating the signature's properties, including the Base64-encoded image value and optionally setting it as the default signature for preselection during document signing.", "operationId": "signatures-update-signature", "parameters": [ { "name": "signatureId", "in": "path", "description": "The ID of the signature that should be updated.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSignatureUpsertRequest" }, "example": { "signature": { "value": "data:image/png;base64,iVBORw0KGgo...", "isDefault": false } } } } }, "responses": { "200": { "description": "This is the response returned when the signature is successfully updated.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "signature": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "signature": { "id": "123e4567-e89b-12d3-a456-426614174000", "message": "Signature saved." } } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/create": { "post": { "tags": [ "Template" ], "summary": "Template Create", "description": "Creates a template containing one or more documents, template roles, and recipient roles.
\n* The created template is assigned a unique ID, stored in the templateId parameter.\n* Documents must first be uploaded via the Storage endpoint and linked to recipients using referenceDocumentId and referenceSignerId.\n* Template roles act as placeholders for actual recipients, which are defined when the template is used to create an envelope.\n* Recipient roles define the required actions for each recipient. Note: templateName is the only field the server actually requires (TEMPLATE_NAME_REQUIRED) - documents/recipients/fields may all be empty.", "operationId": "signatures-template-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeTemplateUpsertRequest" }, "example": { "documents": [ { "referenceDocumentId": 0, "name": "string", "loadMethod": "string", "urn": "string", "externalContext": {} } ], "fields": [ { "referenceSignerId": 0, "referenceSignGroupId": 0, "referenceDocumentId": 0, "name": "string", "value": "string", "type": "signature", "anchorString": "string", "page": 0, "height": 0, "width": 0, "positionX": 0, "positionY": 0, "isRequired": true, "tooltip": "string", "properties": { "fontFamily": "string", "fontSize": 0, "color": "string", "bold": true, "italic": true, "underline": true, "textAlign": "string", "placeholder": "string", "isSignedDate": true, "selectionGroup": "string", "selectionValue": "string" } } ], "recipients": [ { "referenceSignerId": 0, "referenceSignGroupId": 0, "name": "string", "email": "string", "role": "signer", "templateRole": "string", "signOrder": 0, "mandatory": true, "hostEmail": "string", "isMfaEnabled": true, "phoneNumber": "string", "externalContext": {} } ], "signGroups": [ { "referenceSignGroupId": 0, "name": "string", "role": "signer", "signOrder": 0, "mandatory": true, "templateRole": "string" } ], "template": { "subject": "string", "message": "string", "senderName": "string", "senderEmail": "string", "isSignOrder": true, "expireInDays": 0, "alertDaysBeforeExpiry": 0, "firstReminderDays": 0, "repeatingReminderDays": 0, "notifyWhenOpened": true, "notifyWhenSigned": true, "templateName": "string", "templateDescription": "string", "folderId": "string", "locale": "string", "timezone": "string" }, "externalContext": {} } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 201 }, "message": { "type": "string", "readOnly": true, "example": "Created" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; omitted on update.", "format": "date-time" } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true }, "consumption": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "value": { "type": "integer" } } }, "description": "Present only on metered operations.", "readOnly": true } } }, "example": { "result": { "statusCode": 201, "message": "Created", "data": { "template": { "id": "string", "uploadDate": "string" }, "documents": [ { "id": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "externalContext": {} } ], "signGroups": [ { "id": "string" } ], "fields": [ { "id": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string" } ] } }, "origin": "string", "dateTime": "string", "consumption": [ { "dimension": "string", "value": 0 } ] } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/{templateId}/delete": { "delete": { "tags": [ "Template" ], "summary": "Template Delete", "description": "Deletes a specific template from the system.
\n* The template is identified using the templateId path parameter.\n* Only templates accessible to the authenticated user can be deleted. Looks up the id with no IsTemplate filter, so a non-template envelope id owned by the caller will have its documents/recipients/signGroups/fields deleted, but the parent record is left in place (the final delete statement is scoped to Status='Template').", "operationId": "signatures-template-delete", "parameters": [ { "name": "templateId", "in": "path", "description": "The ID of the template that should be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template deleted.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "template": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/{templateId}/edit": { "put": { "tags": [ "Template" ], "summary": "Template Edit", "description": "Edits an existing template's properties.
\n* The template is identified using the templateId path parameter.\n* Currently, this endpoint allows moving a template to a specific folder by providing the folderId.\n* If folderId is provided as null, the template will be removed from its current folder and placed in the root directory. This operation ONLY changes the template's folder - it is not a general template edit (see template/{templateId}/update for that). No existence/ownership check runs before the update; a bad id, wrong owner, or non-existent folderId all collapse into the same TEMPLATE_EDIT_FAILED response.", "operationId": "signatures-template-edit", "parameters": [ { "name": "templateId", "in": "path", "description": "The unique identifier (GUID) of the template to be edited.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The payload containing the properties to edit on the template.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object", "properties": { "folderId": { "type": "string", "format": "uuid", "nullable": true } } }, "externalContext": { "description": "Accepted but entirely unused - not persisted, not echoed.", "nullable": true } } }, "example": { "template": { "folderId": "123e4567-e89b-12d3-a456-426614174000" }, "externalContext": { "id": "12345" } } } } }, "responses": { "200": { "description": "Template folder updated.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "message": { "type": "string", "readOnly": true } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "template": { "id": "string", "message": "string" } } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/{templateId}/get": { "get": { "tags": [ "Data", "Template" ], "summary": "Template Get", "description": "Retrieves details of a specific template.
\n* The template is identified using the templateId path parameter.\n* Only templates accessible to the authenticated user are returned.", "operationId": "signatures-template-get", "parameters": [ { "name": "templateId", "in": "path", "description": "The ID of the needed template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "uploadDate": { "type": "string", "format": "date-time" }, "sendDate": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string" }, "subject": { "type": "string" }, "message": { "type": "string" }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "alertDaysBeforeExpiry": { "type": "integer" }, "templateName": { "type": "string" }, "templateDescription": { "type": "string", "nullable": true }, "folderId": { "type": "string", "format": "uuid", "nullable": true }, "folderName": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true }, "Timezone": { "type": "string", "description": "Emitted with a capital T in the actual wire response - a source inconsistency preserved here faithfully rather than silently corrected.", "nullable": true } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "status": { "type": "string" }, "signDate": { "type": "string", "nullable": true }, "signOrder": { "type": "integer" }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "mandatory": { "type": "boolean" }, "isMFAEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "nullable": true }, "hostEmail": { "type": "string", "nullable": true }, "templateRole": { "type": "string", "nullable": true }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "role": { "type": "string" }, "status": { "type": "string" }, "signOrder": { "type": "integer" }, "mandatory": { "type": "boolean" }, "templateRole": { "type": "string" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "value": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "isRequired": { "type": "boolean" }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." } } }, "readOnly": true }, "externalContext": { "nullable": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "template": { "id": "string", "createdBy": { "id": "string", "name": "string", "email": "string" }, "uploadDate": "string", "sendDate": "string", "status": "string", "subject": "string", "message": "string", "isSignOrder": true, "expireInDays": 0, "firstReminderDays": 0, "repeatingReminderDays": 0, "notifyWhenOpened": true, "notifyWhenSigned": true, "alertDaysBeforeExpiry": 0, "templateName": "string", "templateDescription": "string", "folderId": "string", "folderName": "string", "locale": "string", "Timezone": "string" }, "documents": [ { "id": "string", "name": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "name": "string", "email": "string", "role": "string", "status": "string", "signDate": "string", "signOrder": 0, "signGroupId": "string", "userId": "string", "mandatory": true, "isMFAEnabled": true, "phoneNumber": "string", "hostEmail": "string", "templateRole": "string", "externalContext": {} } ], "signGroups": [ { "id": "string", "name": "string", "role": "string", "status": "string", "signOrder": 0, "mandatory": true, "templateRole": "string" } ], "fields": [ { "id": "string", "name": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string", "type": "signature", "value": "string", "page": 0, "height": 0, "width": 0, "positionX": 0, "positionY": 0, "isRequired": true, "properties": { "fontFamily": "string", "fontSize": 0, "color": "string", "bold": true, "italic": true, "underline": true, "textAlign": "string", "placeholder": "string", "isSignedDate": true, "selectionGroup": "string", "selectionValue": "string" } } ], "externalContext": {} } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/list": { "get": { "tags": [ "Template" ], "summary": "Template List", "description": "Retrieves a list of all templates associated with the authenticated user.
\n* Supports filtering, sorting, and pagination via query parameters.\n* Query Parameters:\n * top (integer). Maximum number of templates to return (e.g., 25).\n * skip (integer). Number of templates to skip in the sorted results (e.g., 0).\n * sort (string). Column to sort by. Valid values: Template Name, Template Roles, Documents, Creation Date.\n * order (string). Sort direction. Valid values: ASC, DESC.\n * filter (JSON array). List of filter objects to refine results. Each filter includes:\n * column (string). Field to filter on (matches sort values).\n * condition (string). Filter condition. \n * For stringFilter: EMPTY, NOT_EMPTY, CONTAINS, CONTAINS_CASE_SENSITIVE, DOES_NOT_CONTAIN, DOES_NOT_CONTAIN_CASE_SENSITIVE, STARTS_WITH, STARTS_WITH_CASE_SENSITIVE, ENDS_WITH, ENDS_WITH_CASE_SENSITIVE, EQUAL, EQUAL_CASE_SENSITIVE, NULL, NOT_NULL.\n * For dateFilter: EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, NULL, NOT_NULL.\n * value (string). Filter value.\n * string for stringFilter.\n * YYYY-MM-DD for dateFilter.\n * type (string): \n * stringFilter.\n * dateFilter.\n * key (string). Unique 12-character alphanumeric identifier for the filter.", "operationId": "signatures-template-list", "parameters": [ { "name": "sort", "in": "query", "description": "Column to sort by the results.", "schema": { "enum": [ "Template Name", "Template Roles", "Documents", "Creation Date" ], "type": "string" } }, { "name": "order", "in": "query", "description": "The direction of the sort.", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "top", "in": "query", "description": "Max rows to return.", "schema": { "type": "integer", "default": 100 } }, { "name": "skip", "in": "query", "description": "Rows to skip. Defaults to 0 if omitted or not a valid integer.", "schema": { "type": "integer", "default": 0 } }, { "name": "orderby", "in": "query", "description": "Single combined param, format \"|\" (literal pipe). Defaults to `UploadDate DESC` if omitted or not recognized.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "URL-encoded JSON array of FilterInput objects. A folder-scoping filter (key=\"folder\") can be used with the value \"templates\" to scope results to templates.", "schema": { "type": "string", "description": "URL-encoded JSON array of FilterInput objects." } } ], "responses": { "200": { "description": "Templates retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "status": { "type": "string", "readOnly": true }, "uploadDate": { "type": "string", "format": "date-time", "readOnly": true }, "sendDate": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "subject": { "type": "string", "readOnly": true }, "transactionTokenId": { "type": "string", "nullable": true, "readOnly": true }, "documents": { "type": "string", "description": "JSON-encoded array as a STRING (e.g. \"[{\\\"name\\\":...}]\"), not a native JSON array - the server produces this via SQL FOR JSON PATH and returns it unparsed.", "readOnly": true }, "recipients": { "type": "string", "description": "JSON-encoded array as a STRING; same caveat as documents.", "readOnly": true }, "signGroups": { "type": "string", "description": "JSON-encoded array as a STRING; same caveat as documents.", "readOnly": true }, "isSignOrder": { "type": "boolean", "readOnly": true }, "expireInDays": { "type": "integer", "readOnly": true }, "alertDaysBeforeExpiry": { "type": "integer", "readOnly": true }, "templateName": { "type": "string", "readOnly": true }, "templateDescription": { "type": "string", "nullable": true, "readOnly": true }, "folderId": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true }, "folderName": { "type": "string", "nullable": true, "readOnly": true } } } }, "rowCount": { "type": "integer", "description": "Total matching rows regardless of top/skip.", "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "templates": [ { "id": "string", "createdBy": { "id": "string", "name": "string", "email": "string" }, "status": "string", "uploadDate": "string", "sendDate": "string", "subject": "string", "transactionTokenId": "string", "documents": "string", "recipients": "string", "signGroups": "string", "isSignOrder": true, "expireInDays": 0, "alertDaysBeforeExpiry": 0, "templateName": "string", "templateDescription": "string", "folderId": "string", "folderName": "string" } ], "rowCount": 0 } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/template/{templateId}/update": { "put": { "tags": [ "Template" ], "summary": "Template Update", "description": "Updates an existing template that has been created but not yet used to send an envelope.
\n* The template is identified using the templateId parameter.\n* This endpoint allows modification of:\n * Template information.\n * Included documents.\n * Assigned recipients.\n * Added fields.\n * Expiration settings.\n * Reminder settings.\n * Associated metadata.", "operationId": "signatures-template-update", "parameters": [ { "name": "templateId", "in": "path", "description": "The ID of the template that should be edited.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeTemplateUpsertRequest" }, "example": { "documents": [ { "referenceDocumentId": 0, "name": "string", "loadMethod": "string", "urn": "string", "externalContext": {} } ], "fields": [ { "referenceSignerId": 0, "referenceSignGroupId": 0, "referenceDocumentId": 0, "name": "string", "value": "string", "type": "signature", "anchorString": "string", "page": 0, "height": 0, "width": 0, "positionX": 0, "positionY": 0, "isRequired": true, "tooltip": "string", "properties": { "fontFamily": "string", "fontSize": 0, "color": "string", "bold": true, "italic": true, "underline": true, "textAlign": "string", "placeholder": "string", "isSignedDate": true, "selectionGroup": "string", "selectionValue": "string" } } ], "recipients": [ { "referenceSignerId": 0, "referenceSignGroupId": 0, "name": "string", "email": "string", "role": "signer", "templateRole": "string", "signOrder": 0, "mandatory": true, "hostEmail": "string", "isMfaEnabled": true, "phoneNumber": "string", "externalContext": {} } ], "signGroups": [ { "referenceSignGroupId": 0, "name": "string", "role": "signer", "signOrder": 0, "mandatory": true, "templateRole": "string" } ], "template": { "subject": "string", "message": "string", "senderName": "string", "senderEmail": "string", "isSignOrder": true, "expireInDays": 0, "alertDaysBeforeExpiry": 0, "firstReminderDays": 0, "repeatingReminderDays": 0, "notifyWhenOpened": true, "notifyWhenSigned": true, "templateName": "string", "templateDescription": "string", "folderId": "string", "locale": "string", "timezone": "string" }, "externalContext": {} } } } }, "responses": { "200": { "description": "Template updated.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; omitted on update.", "format": "date-time" } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "template": { "id": "string", "uploadDate": "string" }, "documents": [ { "id": "string", "externalContext": {} } ], "recipients": [ { "id": "string", "externalContext": {} } ], "signGroups": [ { "id": "string" } ], "fields": [ { "id": "string", "recipientId": "string", "signGroupId": "string", "documentId": "string" } ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/signatures/user/activity/get": { "get": { "tags": [ "User", "Data" ], "summary": "User Activity Get", "description": "Retrieves a log of recent activities performed by or associated with the authenticated user.
\n* Possible actions include:\n * Create envelope.\n * Send envelope.\n * Receive envelope.\n * View envelope.\n * Cancel envelope.\n* The response provides a detailed audit trail in JSON format, including metadata such as envelope IDs, action types, timestamps, and additional information (e.g., recipient emails or token status). Both lists are capped at the 10 most recent entries.", "operationId": "signatures-get-getrecentactivity", "responses": { "200": { "description": "Recent activity retrieved.", "content": { "application/json": { "schema": { "required": [ "result", "origin", "dateTime" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "type": "integer", "readOnly": true, "example": 200 }, "message": { "type": "string", "readOnly": true, "example": "OK" }, "data": { "type": "object", "properties": { "activityItems": { "type": "array", "items": { "type": "object", "properties": { "auditTrailId": { "type": "string", "format": "uuid", "readOnly": true }, "action": { "type": "string", "readOnly": true }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "transactionTokenId": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true }, "actor": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true } }, "readOnly": true }, "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string" }, "status": { "type": "string" }, "creatorName": { "type": "string" }, "sendDate": { "type": "string", "format": "date-time", "nullable": true } }, "readOnly": true } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "documentName": { "type": "string", "readOnly": true }, "envelopeSubject": { "type": "string", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "authorName": { "type": "string", "readOnly": true }, "envelopeId": { "type": "string", "format": "uuid", "readOnly": true } } } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header.", "readOnly": true }, "dateTime": { "type": "string", "format": "date-time", "readOnly": true } } }, "example": { "result": { "statusCode": 200, "message": "OK", "data": { "activityItems": [ { "auditTrailId": "string", "action": "string", "timestamp": "string", "transactionTokenId": "string", "actor": { "name": "string", "email": "string", "role": "string" }, "envelope": { "id": "string", "subject": "string", "status": "string", "creatorName": "string", "sendDate": "string" } } ], "comments": [ { "documentName": "string", "envelopeSubject": "string", "createdAt": "string", "authorName": "string", "envelopeId": "string" } ] } }, "origin": "string", "dateTime": "string" } } } }, "400": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } }, "500": { "description": "An error occurred. See SignatureErrorResponse for the response shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureErrorResponse" }, "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } } } } } } }, "/v1/documents/document/generate/async": { "post": { "tags": [ "Document" ], "summary": "Document Generate Async", "description": "This endpoint allows you to initiate an asynchronous document generation request. Similar to the [Documents Generate](https://apim-mavenheadless-dev-westeu.developer.azure-api.net/api-details#api=documents&operation=post-documentsgenerate)\n endpoint, it enables you to generate documents (e.g. PDF, DOCX, XLSX) by specifying a template, supplying structured data, and configuring output options such as format, storage location, and delivery method. Unlike the synchronous variant, this endpoint immediately returns control to the caller and processes the document generation in the background, returning a response via a callback, promise, depending on your integration setup once the document is ready. This endpoint is useful when generating complex documents that may require longer processing times or when you prefer non-blocking operations.", "operationId": "documents-generate-async", "parameters": [ { "name": "X-Client-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to identify and authorize the calling client system responsible for requesting the document generation. This header is required when retrieving the template and/or data used to populate the template from the client’s side, and for delivering the final generated document on the client’s side.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzZXNzaW9uLTQ0NyJ9.QFq6y3f6c2b7d1a9" } }, { "name": "X-Service-Authorization", "in": "header", "description": "Encrypted (AES) JWT token to represent a user that doesn’t have a Microsoft Account and that is allowed to use the subscription.", "schema": { "type": "string", "default": "eyJhbGciOiJSUzI1NiJ9.eyJhbXBfc3Vic2NyaXB0aW9uIjoic3ViLTg4OSJ9.7f4d1a9c2b6e3f0a" } }, { "name": "X-Email", "in": "header", "description": "Email of the user who starts the process, needed for GAS script processing", "schema": { "type": "string", "default": "jane.doe@example.com" } } ], "requestBody": { "description": "\n**externalContext**
\nA contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.\n\n---\n\n**template**
\nDefines the primary document template to be used for generating the document. It includes the template’s metadata, source, file format, and any related templates used during processing.\n\n**template.options**
\nProvides additional configuration for how the template is loaded or processed (e.g., preserving unsupported features or applying file-specific handling options).\n\n**template.relatedItems**
\nAn array of additional templates associated with the primary template. These may be appended or merged during document generation.\n\n---\n\n**data**
\nDefines the source of data and variables that populate the template's placeholders or fields. It includes the method of data retrieval (e.g., from storage, Salesforce, OneDrive) and any static or dynamic content used in the final document.\n\n**data.variables**
\nList of reusable name–value pairs injected into the data. Useful for passing static values, global variables, GraphQL expressions, or field formulas. \n**Note:** This section is should be reviewed by Tomislav and Ivan A.\n\n**data.embedded**
\nAn optional string providing inline key–value metadata pairs that may be embedded in the output file (e.g., in a PDF's metadata section).\n\n---\n\n**document**
\nDefines the configuration and metadata of the final generated document, including its name, locale, format, timezone, delivery method, and storage destination.\n\n**document.options.salesforce**
\nSpecifies how the document will be stored or associated with records in Salesforce. Includes fields such as `fileId`, `fileType`, `fileParentId`, and `ownerId`.\n\n**document.options.onedrive**
\nSpecifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.\n\n**document.options.googledrive**
\nSpecifies how the document will be shared or stored via Google Drive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalContext": { "type": "object", "properties": { "id": { "type": "string", "description": "External reference ID used for contextual tracking.", "default": "12345" } } }, "template": { "required": [ "urn", "fileFormat", "loadMethod" ], "type": "object", "properties": { "name": { "type": "string", "description": "Template name (as known in Storage, Salesforce, or OneDrive).", "default": "" }, "urn": { "type": "string", "description": "Template identifier. Can be a Storage key, Salesforce ContentVersion ID, or OneDrive file ID.", "default": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5" }, "fileFormat": { "enum": [ "docx", "xlsx" ], "type": "string", "description": "Template file format without dot (e.g., docx, xlsx).", "default": "xlsx" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the template where it is stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "options": { "type": "object", "properties": { "docxLoadOptions": { "type": "string", "description": "JSON string for DOCX load options, default \"{\\\"PreserveUnsupportedFeatures\\\": true}\".", "default": "{ \"PreserveUnsupportedFeatures\": true }" } } }, "relatedItems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the related template. Must match the name used in the root template.", "default": "" }, "urn": { "type": "string", "description": "Identifier of the related template, used to locate the file.", "default": "" }, "fileFormat": { "type": "string", "description": "Format of the related template file (e.g., docx).", "default": "" }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source system from which to load the related template (e.g., Storage, Salesforce, OneDrive).", "default": "" } } } } } }, "data": { "required": [ "urn", "loadMethod" ], "type": "object", "properties": { "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Source of the data (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "urn": { "type": "string", "description": "Data identifier for the data source used to populate the template provided in the template URN (e.g., GraphQL endpoint, Storage key, OneDrive file ID).", "default": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Variable name (e.g., myExpressionField).", "default": "" }, "value": { "type": "string", "description": "Raw value or expression placeholder.", "default": "" }, "type": { "enum": [ "fieldExpression", "graphql", "global" ], "type": "string", "description": "Type of variable.", "default": "" } } } }, "query": { "type": "string", "description": "JSON-encoded GraphQL query, used if loadMethod is GraphQL.", "default": "" }, "embedded": { "type": "string", "description": "Arbitrary key-value pairs written into PDF document properties.", "default": "" } } }, "document": { "required": [ "timezone", "locale", "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "timezone": { "type": "string", "description": "Timezone used for date/time formatting.", "default": "(GMT+01:00) Central European Standard Time (Europe/Zagreb)" }, "locale": { "type": "string", "description": "Locale for language-specific formatting. Supported values follow the [Unicode CLDR Project](https://cldr.unicode.org/), such as [`en-GB`, `es-MX`, and others](https://github.com/unicode-org/cldr-json/tree/main/cldr-json/cldr-dates-full/main).", "default": "en_US_POSIX" }, "name": { "type": "string", "description": "Name of the generated document without file extension.", "default": "Document" }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "Format of the generated document (e.g., docx, xlsx, pdf).", "default": "pdf" }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive" ], "type": "string", "description": "Place where the document will be stored (e.g., Storage, Salesforce, OneDrive).", "default": "Storage" }, "path": { "type": "string", "description": "Target folder or path for delivery. Optional based on storage provider.", "default": "" }, "options": { "type": "object", "properties": { "pdfSaveOptions": { "type": "string", "description": "JSON string for PDF output settings, default \"{\\\"ConformanceLevel\\\": \\\"PdfA3a\\\", \\\"Version\\\": \\\"PDF_1_7\\\", \\\"ImageDpi\\\": 750}\".", "default": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }" }, "docxSaveOptions": { "type": "string", "description": "JSON string for DOCX output customizations.", "default": "" }, "salesforce": { "type": "object", "properties": { "fileId": { "type": "string", "description": "ID of existing file (ContentDocument) to update/replace.", "default": "" }, "fileType": { "enum": [ "File", "Attachment" ], "type": "string", "description": "File handling capabilities in Salesforce (e.g., File, Attachment).", "default": "" }, "fileParentId": { "type": "string", "description": "Salesforce record to which the file is attached.", "default": "" }, "ownerId": { "type": "string", "description": "Salesforce user or queue ID who should own the file.", "default": "" } } }, "onedrive": { "type": "object", "properties": { "viewAnonymous": { "type": "boolean", "description": "Allow public viewing via link of the generated document.", "default": false }, "editAnonymous": { "type": "boolean", "description": "Allow public editing via link of the generated document.", "default": false }, "editUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with edit access." }, "viewUsers": { "type": "array", "items": { "type": "string", "default": "user@example.com" }, "description": "List of users for the link with view access." } } } } } } } } }, "example": { "externalContext": { "id": "req-2026-0007421" }, "template": { "name": "Standard Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "fileFormat": "docx", "loadMethod": "Storage", "options": { "docxLoadOptions": "{ \"PreserveUnsupportedFeatures\": true }" }, "relatedItems": [ { "name": "Invoice Terms Addendum", "urn": "4b1e2f3a-5c6d-47e8-9a0b-1c2d3e4f5a6b", "fileFormat": "docx", "loadMethod": "Storage" } ] }, "data": { "loadMethod": "Storage", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "variables": [ { "name": "createdDate", "value": "{!$now()}", "type": "fieldExpression" }, { "name": "requestId", "value": "{!requestId}", "type": "graphql" }, { "name": "customerName", "value": "Jane Doe", "type": "global" } ], "query": "{\"query\":\"{Account {Name Description Owner.Username Id Opportunities {StageName OpportunityLineItems {Name}} Contacts {Id}}}\"}", "embedded": "key:value" }, "document": { "timezone": "(GMT+00:00) Greenwich Mean Time (Europe/Dublin)", "locale": "en_IE_EURO", "name": "Q3 Sales Report", "fileFormat": "docx", "deliveryMethod": "Storage", "path": "root", "options": { "pdfSaveOptions": "{ \"ConformanceLevel\": \"PdfA3a\", \"Version\": \"PDF_1_7\", \"ImageDpi\": 750 }", "docxSaveOptions": "{}", "salesforce": { "fileId": "069AZ0000004CvXYAW", "fileType": "File", "fileParentId": "0013P00000MvR7oQAF", "ownerId": "0053P00000MvR7oQAF" }, "onedrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] }, "googleDrive": { "viewAnonymous": true, "editAnonymous": true, "editUsers": [ "user@example.com" ], "viewUsers": [ "user@example.com" ] }, "googleGenerate": { "nativeMergeEnabled": true, "nativeImageMergeEnabled": true } } } } } } }, "responses": { "201": { "description": "This response indicates that the document was successfully generated and delivered using the specified deliveryMethod. It includes metadata about the generated document (such as name, format, and unique URN), usage metrics (e.g., pages generated), and contextual information useful for tracking and auditing the operation.", "content": { "application/json": { "schema": { "required": [ "result", "consumption", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "result": { "required": [ "statusCode", "message", "data" ], "type": "object", "properties": { "statusCode": { "enum": [ "201" ], "type": "string", "description": "Confirming the document was successfully created." }, "message": { "type": "string", "description": "A simple status message." }, "data": { "required": [ "document" ], "type": "object", "properties": { "document": { "required": [ "deliveryMethod", "name", "fileFormat", "urn" ], "type": "object", "properties": { "deliveryMethod": { "enum": [ "Salesforce", "Storage", "OneDrive" ], "type": "string", "description": "The source system where the generated document is stored." }, "name": { "type": "string", "description": "The name of the generated document (without file extension)." }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf" ], "type": "string", "description": "The format of the generated document." }, "urn": { "type": "string", "description": "A unique identifier used to retrieve or reference the generated document." } } } } } } }, "consumption": { "type": "array", "items": { "required": [ "dimension", "value" ], "type": "object", "properties": { "dimension": { "enum": [ "pages-generated", "documents-generated" ], "type": "string", "description": "The type of resource consumed (e.g., pages-generated, documents-generated)." }, "value": { "type": "number", "description": "The measured quantity for the dimension." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document generation request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the document generation was completed and the response returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this generation operation. Can be used for tracing, auditing, or support." } } }, "example": { "result": { "statusCode": "201", "message": "Created", "data": { "document": { "deliveryMethod": "Storage", "name": "Q3 Sales Report", "fileFormat": "docx", "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a:Q3 Sales Report.docx" } } }, "consumption": [ { "dimension": "pages-generated", "value": 4 }, { "dimension": "documents-generated", "value": 1 } ], "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } }, "400": { "description": "This response indicates that the request was invalid or improperly formed. It provides details about the error that occurred, including specific error codes, messages, and guidance for the user on how to resolve the issue.", "content": { "application/json": { "schema": { "required": [ "error", "externalContext", "origin", "dateTime", "userId", "operationId" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "enum": [ "400" ], "type": "string", "description": "Indicating a bad request was made." }, "message": { "type": "string", "description": "A high-level description of the error." }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage", "eventId" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code indicating the type of issue encountered." }, "message": { "type": "string", "description": "A description of the specific error encountered." }, "userMessage": { "type": "string", "description": "A message intended for the end-user, advising on how to resolve the issue." }, "eventId": { "type": "string", "description": "A unique identifier for tracing the error in logs or debugging." } } } }, "externalErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code from the external service." }, "message": { "type": "string", "description": "A description of the external error." } }, "description": "Detailed list of errors originating from external services." } } } }, "externalContext": { "required": [ "actionRequestId" ], "type": "object", "properties": { "actionRequestId": { "type": "string", "description": "External reference ID used for contextual tracking." } } }, "origin": { "type": "string", "description": "The HTTP method and endpoint URL that initiated the document generation request." }, "dateTime": { "type": "string", "description": "The exact UTC timestamp when the response was returned.", "format": "date-time" }, "userId": { "type": "string", "description": "The unique identifier of the user or system that initiated the request." }, "operationId": { "type": "string", "description": "A system-generated ID that uniquely identifies this operation. Can be used for tracing, auditing, or support." } } }, "example": { "error": { "statusCode": "400", "message": "Bad Request", "innerErrors": [ { "code": "TEMPLATE_NOT_FOUND", "message": "The specified template could not be located.", "userMessage": "We couldn't generate your document. Please check the template reference and try again.", "eventId": "a1b2c3d4" } ], "externalErrors": [] }, "externalContext": { "actionRequestId": "req-2026-0007421" }, "origin": "https://app.example.com", "dateTime": "2026-07-14T09:30:00.0000000+00:00", "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "operationId": "0HN7GK9M4T2R5" } } } } } } }, "/public/v1/auth/{provider}/authorize": { "get": { "tags": [ "Auth" ], "summary": "Authorization Proxy", "description": "Authorization Proxy", "operationId": "authorization-proxy", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": {} } ], "responses": { "200": { "description": "" } } } }, "/public/v1/auth/{provider}/token": { "post": { "tags": [ "Auth" ], "summary": "Token Proxy", "description": "Token Proxy", "operationId": "token-proxy", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": {} } ], "responses": { "200": { "description": "" } } } } }, "components": { "schemas": { "DataSourceModel": { "required": [ "name", "loadMethod" ], "type": "object", "properties": { "dataSourceGuid": { "type": "string", "description": "Unique identifier of the data source.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the data source. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the underlying source.", "format": "uuid", "nullable": true }, "query": { "type": "string", "description": "Optional free-form query used to fetch data. Stored as-is; its syntax depends on the chosen loadMethod and is interpreted downstream. This API does not validate the format beyond rejecting a blank/whitespace value when the field is supplied.", "nullable": true }, "variables": { "type": "string", "description": "Optional free-form variables associated with the query. Stored as-is and interpreted downstream. Must not be blank/whitespace when supplied.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How data is loaded. Required.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "dataSourceGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Q3 Sales Report Data", "description": "Account records used for quarterly reports.", "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c", "query": "", "variables": "", "loadMethod": "Storage", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "example": "DATA_NAME_REQUIRED" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Name is required." }, "eventId": { "type": "string", "description": "Correlation id for server-side (5xx) errors.", "nullable": true } }, "example": { "code": "DATA_NAME_REQUIRED", "message": "Name is required.", "eventId": "" } }, "DocumentModel": { "required": [ "title", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentGuid": { "type": "string", "description": "Unique identifier of the document.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "title": { "type": "string", "description": "Document title. Required, must be non-empty.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the document file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the document file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the document file.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the document. Required.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the document is delivered. Required.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Anonymous view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Anonymous edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Authenticated-user view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Authenticated-user edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Organization view link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Organization edit link. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "succeededViewUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "succeededEditUserEmailList": { "type": "string", "description": "On success: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedViewUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "failedEditUserEmailList": { "type": "string", "description": "On failure: Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentGuid": "16fd2706-8baf-433b-82eb-8c7fada847da", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "title": "Invoice INV-2026-000123", "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70", "url": "https://storage.example.com/documents/inv-2026-000123.pdf", "path": "documents/inv-2026-000123.pdf", "fileFormat": "pdf", "deliveryMethod": "Email", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "succeededViewUserEmailList": "alice@example.com", "succeededEditUserEmailList": "bob@example.com", "failedViewUserEmailList": "ops@example.com", "failedEditUserEmailList": "ops@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "DocumentRequestModel": { "required": [ "name", "status", "fileFormat", "deliveryMethod", "documentTemplateGuid", "dataGuid" ], "type": "object", "properties": { "documentRequestGuid": { "type": "string", "description": "Unique identifier of the request.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "documentTemplateGuid": { "type": "string", "description": "Template to generate from. Required (must be a non-empty GUID).", "format": "uuid" }, "dataGuid": { "type": "string", "description": "Data source to merge. Required (must be a non-empty GUID).", "format": "uuid" }, "documentGuid": { "type": "string", "description": "Resulting document, once generated.", "format": "uuid", "nullable": true, "readOnly": true }, "documentSolutionConfigurationGuid": { "type": "string", "description": "Optional configuration that governs generation & delivery.", "format": "uuid", "nullable": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "recordId": { "type": "string", "description": "Optional caller-supplied correlation/record id.", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the request. Required, must be non-empty.", "nullable": true }, "status": { "type": "string", "description": "Request status. Required, must be non-empty.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into this request.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (pdf only).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (pdf only).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "completedDate": { "type": "string", "description": "Completion timestamp (UTC), when finished. Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "nullable": true, "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentRequestGuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "documentGuid": "", "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "recordId": "INV-2026-000123", "name": "Invoice run - Contoso July", "status": "Pending", "embeddedData": "", "title": "Invoice INV-2026-000123", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "completedDate": "", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "DocumentSolutionConfigurationModel": { "required": [ "name", "fileFormat", "deliveryMethod" ], "type": "object", "properties": { "documentSolutionConfigurationGuid": { "type": "string", "description": "Unique identifier of the configuration.", "format": "uuid", "readOnly": true }, "documentSolutionGuid": { "type": "string", "description": "Parent document solution this configuration belongs to.", "format": "uuid" }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the configuration. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional output document title.", "nullable": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "Output file format. Required.", "nullable": true }, "processingType": { "enum": [ "STANDARD", "BATCH", "SYNC" ], "type": "string", "description": "Optional processing mode. When supplied must be one of the allowed values.", "nullable": true }, "deliveryMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive", "Email" ], "type": "string", "description": "How the generated document is delivered. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional destination storage path/key.", "nullable": true }, "pdfConformanceLevel": { "type": "string", "description": "Optional PDF/A conformance level (applies when fileFormat is pdf).", "nullable": true }, "pdfVersion": { "type": "string", "description": "Optional PDF version (applies when fileFormat is pdf).", "nullable": true }, "language": { "type": "string", "description": "Optional ISO language code applied during generation.", "nullable": true }, "locale": { "type": "string", "description": "Optional locale used for formatting.", "nullable": true }, "timeZone": { "type": "string", "description": "Optional IANA time zone used for date/time formatting.", "nullable": true }, "embeddedData": { "type": "string", "description": "Optional JSON string of static data merged into every generation.", "nullable": true }, "viewAnonymous": { "type": "boolean", "description": "Allow anonymous view access to the output." }, "editAnonymous": { "type": "boolean", "description": "Allow anonymous edit access to the output." }, "viewOrganization": { "type": "boolean", "description": "Allow organization-wide view access." }, "editOrganization": { "type": "boolean", "description": "Allow organization-wide edit access." }, "viewUser": { "type": "boolean", "description": "Allow named-user view access (see viewUserEmailList)." }, "editUser": { "type": "boolean", "description": "Allow named-user edit access (see editUserEmailList)." }, "viewUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "editUserEmailList": { "type": "string", "description": "Comma-separated list of e-mail addresses. Each address is validated individually; an invalid address rejects the whole request.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionConfigurationGuid": "a3bb189e-8bf9-3888-9912-ace4e6543002", "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Invoice - PDF via Email", "description": "Renders invoices as PDF and e-mails them to the customer.", "title": "Invoice", "fileFormat": "pdf", "processingType": "STANDARD", "deliveryMethod": "Email", "path": "output/invoices/", "pdfConformanceLevel": "PdfA2B", "pdfVersion": "1.7", "language": "en", "locale": "en-US", "timeZone": "America/New_York", "embeddedData": "", "viewAnonymous": false, "editAnonymous": false, "viewOrganization": true, "editOrganization": false, "viewUser": true, "editUser": false, "viewUserEmailList": "alice@example.com,bob@example.com", "editUserEmailList": "carol@example.com", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "DocumentSolutionModel": { "required": [ "name", "dataGuid" ], "type": "object", "properties": { "documentSolutionGuid": { "type": "string", "description": "Unique identifier of the document solution.", "format": "uuid", "nullable": true, "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "nullable": true, "readOnly": true }, "dataGuid": { "type": "string", "description": "Identifier of the data source that feeds this solution. Required.", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Human-readable name of the solution. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentSolutionGuid": "d290f1ee-6c54-4b01-90e6-d701748f0851", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "dataGuid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "name": "Quarterly Invoice Package", "description": "Bundles the invoice template with Q3 account data.", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "DocumentTemplateModel": { "required": [ "name", "fileFormat", "loadMethod" ], "type": "object", "properties": { "documentTemplateGuid": { "type": "string", "description": "Unique identifier of the template.", "format": "uuid", "readOnly": true }, "subscriptionGuid": { "type": "string", "description": "Owning subscription. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "ownerGuid": { "type": "string", "description": "Creating user. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "lastModifiedUserGuid": { "type": "string", "description": "Last user to modify the record. Server-managed; ignored on write and populated on read.", "format": "uuid", "readOnly": true }, "name": { "type": "string", "description": "Human-readable name of the template. Required, must be non-empty.", "nullable": true }, "description": { "type": "string", "description": "Optional description.", "nullable": true }, "title": { "type": "string", "description": "Optional document title applied to generated output.", "nullable": true }, "urn": { "type": "string", "description": "Optional GUID resource identifier of the template file.", "format": "uuid", "nullable": true }, "url": { "type": "string", "description": "Optional absolute URL to the template file. When supplied it must be a well-formed absolute URI.", "nullable": true }, "viewAnonymousLink": { "type": "string", "description": "Read-only sharing link for anonymous viewers. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editAnonymousLink": { "type": "string", "description": "Editing link for anonymous users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewUserLink": { "type": "string", "description": "Read-only sharing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editUserLink": { "type": "string", "description": "Editing link for authenticated users. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "viewOrganizationLink": { "type": "string", "description": "Read-only sharing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "editOrganizationLink": { "type": "string", "description": "Editing link scoped to the organization. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "fileFormat": { "enum": [ "docx", "xlsx", "pdf", "gdoc", "gsheet" ], "type": "string", "description": "File format of the template. Required.", "nullable": true }, "loadMethod": { "enum": [ "Storage", "Salesforce", "OneDrive", "GoogleDrive" ], "type": "string", "description": "How the template file is loaded. Required.", "nullable": true }, "path": { "type": "string", "description": "Optional storage path/key of the template file.", "nullable": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "isDeleted": { "type": "boolean", "description": "Soft-delete flag. Server-managed; ignored on write and populated on read.", "readOnly": true } }, "example": { "documentTemplateGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "subscriptionGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "ownerGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "lastModifiedUserGuid": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Standard Invoice", "description": "Company standard invoice layout.", "title": "Invoice", "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5", "url": "https://storage.example.com/templates/invoice-standard.docx", "viewAnonymousLink": "", "editAnonymousLink": "", "viewUserLink": "", "editUserLink": "", "viewOrganizationLink": "", "editOrganizationLink": "", "fileFormat": "docx", "loadMethod": "Storage", "path": "templates/invoice-standard.docx", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00", "isDeleted": false } }, "OptionValueModel": { "type": "object", "properties": { "optionValueGuid": { "type": "string", "description": "Unique identifier of the option value.", "format": "uuid", "readOnly": true }, "entityType": { "type": "string", "description": "Type of entity the option is attached to (taken from the URL path on write). Free-form string, e.g. DocumentSolutionConfiguration or DocumentTemplate.", "nullable": true }, "entityId": { "type": "string", "description": "Identifier of the entity the option is attached to (taken from the URL path on write).", "format": "uuid" }, "optionDefinitionId": { "type": "integer", "description": "System option definition id. Provide a positive value for a system option; mutually exclusive with customKey.", "nullable": true }, "customKey": { "maxLength": 255, "type": "string", "description": "Custom option key. Provide for a free-form option; mutually exclusive with optionDefinitionId. Max length 255.", "nullable": true }, "customGroup": { "maxLength": 128, "type": "string", "description": "Optional grouping for a custom option. Only allowed together with customKey. Max length 128.", "nullable": true }, "value": { "type": "string", "description": "The option value.", "nullable": true }, "effectiveKey": { "type": "string", "description": "Resolved key (system key or custom key). Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "effectiveGroup": { "type": "string", "description": "Resolved group. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "systemType": { "type": "string", "description": "Data type of the underlying system option definition. Server-managed; ignored on write and populated on read.", "nullable": true, "readOnly": true }, "createdDate": { "type": "string", "description": "Creation timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true }, "lastModifiedDate": { "type": "string", "description": "Last modification timestamp (UTC). Server-managed; ignored on write and populated on read.", "format": "date-time", "readOnly": true } }, "example": { "optionValueGuid": "c9bf9e57-1685-4c89-bafb-ff5af830be8a", "entityType": "DocumentSolutionConfiguration", "entityId": "a3bb189e-8bf9-3888-9912-ace4e6543002", "optionDefinitionId": "", "customKey": "watermark.text", "customGroup": "rendering", "value": "CONFIDENTIAL", "effectiveKey": "watermark.text", "effectiveGroup": "rendering", "systemType": "string", "createdDate": "2026-07-14T09:30:00.0000000+00:00", "lastModifiedDate": "2026-07-14T09:30:00.0000000+00:00" } }, "StorageErrorResponse": { "required": [ "error", "dateTime" ], "type": "object", "properties": { "error": { "required": [ "statusCode", "message", "innerErrors" ], "type": "object", "properties": { "statusCode": { "type": "integer", "description": "HTTP status code of the error.", "readOnly": true }, "message": { "type": "string", "description": "High-level description of the error.", "readOnly": true }, "innerErrors": { "type": "array", "items": { "required": [ "code", "message", "userMessage" ], "type": "object", "properties": { "code": { "type": "string", "description": "Application error code identifying the issue (e.g. FORM_DATA_EXPECTED, VALIDATION_ERROR, INVALID_DATA_FORMAT, INVALID_TEMPLATE_FORMAT, NOT_FOUND_BY_ID, FILE_ACCESS_DENIED, FILE_UPLOAD_FAILED, FILE_DOWNLOAD_FAILED)." }, "message": { "type": "string", "description": "Developer-facing description of the specific error." }, "userMessage": { "type": "string", "description": "End-user-facing message advising how to resolve the issue." } } } } } }, "origin": { "type": "string", "description": "Value of the X-Origin request header, echoed back.", "readOnly": true }, "dateTime": { "type": "string", "description": "UTC timestamp when the error response was generated.", "format": "date-time", "readOnly": true }, "operationId": { "type": "string", "description": "Trace identifier for correlating logs and support requests.", "readOnly": true } }, "example": { "error": { "statusCode": 400, "message": "Bad Request", "innerErrors": [ { "code": "FORM_DATA_EXPECTED", "message": "Expected multipart/form-data with at least one file.", "userMessage": "Please attach a file and resend the request." } ] }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } }, "SignatureInnerError": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code, e.g. ENVELOPE_ID_INVALID.", "example": "ENVELOPE_ID_INVALID" }, "message": { "type": "string", "description": "Internal error message." }, "userMessage": { "type": "string", "description": "User-facing error message." } } }, "SignatureErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" }, "innerErrors": { "type": "array", "items": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code, e.g. ENVELOPE_ID_INVALID.", "example": "ENVELOPE_ID_INVALID" }, "message": { "type": "string", "description": "Internal error message." }, "userMessage": { "type": "string", "description": "User-facing error message." } } } } } }, "origin": { "type": "string", "description": "Echoed from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "nullable": true } }, "description": "Error envelope returned by the Signatures service. See the operation-specific `error.innerErrors[].code` values documented per endpoint.", "example": { "error": { "message": "Envelope not found.", "statusCode": 400, "innerErrors": [ { "code": "ENVELOPE_ID_INVALID", "message": "Envelope not found.", "userMessage": "Envelope not found." } ] }, "origin": "POST https://apim-mavenheadless-dev-westeu-1.azure-api.net/v1/signatures/envelope/create", "dateTime": "2026-07-20T12:00:00.0000000+00:00" } }, "RecipientRole": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "FieldType": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "UserRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "FieldPropertiesInput": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." }, "FolderUpsertRequest": { "type": "object", "properties": { "folder": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } }, "description": "Folder name." }, "externalContext": { "description": "Accepted but NOT persisted by this operation (no ExternalContext column on folders) - it is only echoed back in the response envelope, never stored or returned by folder/get or folder/list.", "nullable": true } } }, "FolderRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string" } } }, "SavedSignatureUpsertRequest": { "type": "object", "properties": { "signature": { "type": "object", "properties": { "value": { "type": "string", "description": "Stored and returned as-is; no format (e.g. base64/data-URI) is validated or enforced by the server.", "nullable": true }, "isDefault": { "type": "boolean", "description": "If true, the server demotes the caller's other saved signatures' isDefault flag in the same request." } } }, "externalContext": { "description": "Accepted but NOT persisted - echoed only, never stored or returned by other signature operations.", "nullable": true } } }, "FilterInput": { "type": "object", "properties": { "column": { "type": "string" }, "condition": { "type": "string", "description": "e.g. CONTAINS, EQUAL, NULL, STARTS_WITH, GREATER_THAN (date)." }, "value": { "type": "string" }, "type": { "enum": [ "string", "date" ], "type": "string", "description": "One of `string` or `date`." }, "key": { "type": "string" } }, "description": "column/key are interpolated into the query with no server-side allow-list - any string is accepted, not just real columns." }, "DocumentTemplateInput": { "required": [ "referenceDocumentId", "name" ], "type": "object", "properties": { "referenceDocumentId": { "type": "integer", "description": "Client-assigned correlation id used to link fields to this document within the same request; not a server document id." }, "name": { "type": "string" }, "loadMethod": { "type": "string", "description": "How to source the document's content. Currently only `storage` is supported, which fetches bytes from the location named by `urn`. There is no field on this object to send document bytes inline." }, "urn": { "type": "string", "description": "Storage location, only consulted when loadMethod is \"storage\". No format is enforced by this service - obtained from a separate upload step.", "nullable": true }, "externalContext": { "description": "Opaque; persisted verbatim and returned by template/{id}/get.", "nullable": true } } }, "FieldTemplateInput": { "required": [ "referenceDocumentId", "name", "type" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "referenceDocumentId": { "type": "integer" }, "name": { "type": "string", "description": "PDF field name." }, "value": { "type": "string", "description": "Required (non-empty) only for type=note; format otherwise depends entirely on type and is not validated by the server.", "nullable": true }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "anchorString": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "isRequired": { "type": "boolean" }, "tooltip": { "type": "string", "nullable": true }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." } }, "description": "Exactly one of referenceSignerId/referenceSignGroupId must be set. Exactly one positioning strategy must be set: anchorString, OR all four of page+height+width+positionX+positionY." }, "RecipientTemplateInput": { "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "templateRole": { "type": "string", "description": "Must be unique within the request across recipients and signGroups." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when template.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "description": "Format validated only; NOT required even when role=inpersonsigner (unlike the regular envelope recipient DTO).", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "description": "No format validated. Required only if isMfaEnabled is true and the account's MFA channel is not email.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned by template/{id}/get.", "nullable": true } }, "description": "name/email/hostEmail are NOT required here (contrast with the regular envelope recipient DTO, where they are). role is only validated (closed set, case-sensitive) when referenceSignGroupId is not set. templateRole is required (when not sign-group-based) and must be unique across all recipients+signGroups in the request." }, "SignGroupTemplateInput": { "required": [ "referenceSignGroupId", "role", "templateRole" ], "type": "object", "properties": { "referenceSignGroupId": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when template.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "templateRole": { "type": "string", "description": "Must be unique within the request across recipients and signGroups." } } }, "EnvelopeTemplateInfoInput": { "required": [ "templateName" ], "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "format": "email", "nullable": true }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer", "description": "0 means no expiry. Any value other than 0 must be >= 2 (1 is rejected)." }, "alertDaysBeforeExpiry": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "templateName": { "type": "string" }, "templateDescription": { "type": "string", "nullable": true }, "folderId": { "type": "string", "description": "Not validated to exist/belong to the caller at request-validation time - a non-matching id is silently resolved to no folder.", "format": "uuid", "nullable": true }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "EnvelopeTemplateUpsertRequest": { "type": "object", "properties": { "documents": { "type": "array", "items": { "required": [ "referenceDocumentId", "name" ], "type": "object", "properties": { "referenceDocumentId": { "type": "integer", "description": "Client-assigned correlation id used to link fields to this document within the same request; not a server document id." }, "name": { "type": "string" }, "loadMethod": { "type": "string", "description": "How to source the document's content. Currently only `storage` is supported, which fetches bytes from the location named by `urn`. There is no field on this object to send document bytes inline." }, "urn": { "type": "string", "description": "Storage location, only consulted when loadMethod is \"storage\". No format is enforced by this service - obtained from a separate upload step.", "nullable": true }, "externalContext": { "description": "Opaque; persisted verbatim and returned by template/{id}/get.", "nullable": true } } } }, "fields": { "type": "array", "items": { "required": [ "referenceDocumentId", "name", "type" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "referenceDocumentId": { "type": "integer" }, "name": { "type": "string", "description": "PDF field name." }, "value": { "type": "string", "description": "Required (non-empty) only for type=note; format otherwise depends entirely on type and is not validated by the server.", "nullable": true }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "anchorString": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "isRequired": { "type": "boolean" }, "tooltip": { "type": "string", "nullable": true }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." } }, "description": "Exactly one of referenceSignerId/referenceSignGroupId must be set. Exactly one positioning strategy must be set: anchorString, OR all four of page+height+width+positionX+positionY." } }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "templateRole": { "type": "string", "description": "Must be unique within the request across recipients and signGroups." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when template.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "description": "Format validated only; NOT required even when role=inpersonsigner (unlike the regular envelope recipient DTO).", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "description": "No format validated. Required only if isMfaEnabled is true and the account's MFA channel is not email.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned by template/{id}/get.", "nullable": true } }, "description": "name/email/hostEmail are NOT required here (contrast with the regular envelope recipient DTO, where they are). role is only validated (closed set, case-sensitive) when referenceSignGroupId is not set. templateRole is required (when not sign-group-based) and must be unique across all recipients+signGroups in the request." } }, "signGroups": { "type": "array", "items": { "required": [ "referenceSignGroupId", "role", "templateRole" ], "type": "object", "properties": { "referenceSignGroupId": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when template.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "templateRole": { "type": "string", "description": "Must be unique within the request across recipients and signGroups." } } } }, "template": { "required": [ "templateName" ], "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "format": "email", "nullable": true }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer", "description": "0 means no expiry. Any value other than 0 must be >= 2 (1 is rejected)." }, "alertDaysBeforeExpiry": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "templateName": { "type": "string" }, "templateDescription": { "type": "string", "nullable": true }, "folderId": { "type": "string", "description": "Not validated to exist/belong to the caller at request-validation time - a non-matching id is silently resolved to no folder.", "format": "uuid", "nullable": true }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "externalContext": { "nullable": true } }, "description": "Unlike the regular envelope create/update request, documents/fields/recipients are NOT required to be non-empty here - a template can be saved with none of them." }, "EnvelopeTemplateUpsertResponseData": { "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; omitted on update.", "format": "date-time" } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } }, "RecipientTemplatePrepareInput": { "required": [ "templateRole" ], "type": "object", "properties": { "templateRole": { "type": "string", "description": "Matched case-insensitively against the template's stored recipient templateRole values. A non-matching value is silently ignored (the template's own stored recipient is used unchanged), not an error." }, "name": { "type": "string", "description": "Overrides the template's stored value; omit to keep the template's value.", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "hostEmail": { "type": "string", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "externalContext": { "nullable": true } } }, "SignGroupTemplatePrepareInput": { "required": [ "templateRole" ], "type": "object", "properties": { "templateRole": { "type": "string" }, "name": { "type": "string", "nullable": true } } }, "DocumentInput": { "required": [ "referenceDocumentId", "name" ], "type": "object", "properties": { "referenceDocumentId": { "type": "integer", "description": "Client-assigned correlation id linking fields to this document within the same request." }, "name": { "type": "string" }, "loadMethod": { "type": "string", "description": "How to source the document's content. Currently only `storage` is supported, which fetches bytes from the location named by `urn`. There is no inline/base64 bytes field." }, "urn": { "type": "string", "description": "Storage location, only consulted when loadMethod is \"storage\". Obtained from a separate upload step; format not enforced by this service.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned by document/{documentId}/get.", "nullable": true } } }, "RecipientInput": { "required": [ "name", "email" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when envelope.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "description": "Required only when role=inpersonsigner; must additionally resolve to an existing, valid subscription user.", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "description": "No format validated. Required only if isMfaEnabled is true and the account's MFA channel is not email.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned.", "nullable": true } }, "description": "At least one of referenceSignerId/referenceSignGroupId is required (both may be set)." }, "SignGroupInput": { "required": [ "referenceSignGroupId", "name", "role" ], "type": "object", "properties": { "referenceSignGroupId": { "type": "integer" }, "name": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when envelope.isSignOrder is true." }, "mandatory": { "type": "boolean" } } }, "FieldInput": { "required": [ "referenceDocumentId", "name", "type" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "referenceDocumentId": { "type": "integer" }, "name": { "type": "string", "description": "PDF field name." }, "value": { "type": "string", "description": "Required (non-empty) only for type=note. Format otherwise depends entirely on type and is not validated by the server (e.g. attachment-type fields expect a JSON string, unvalidated on write).", "nullable": true }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "anchorString": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "isRequired": { "type": "boolean" }, "tooltip": { "type": "string", "nullable": true }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." } }, "description": "Exactly one of referenceSignerId/referenceSignGroupId must be set (strict XOR - unlike RecipientInput, having both set here is rejected). Exactly one positioning strategy must be set: anchorString, OR all four of page+height+width+positionX+positionY." }, "EnvelopeInfoInput": { "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "format": "email", "nullable": true }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer", "description": "0 means no expiry. Any non-zero value must be >= 2 (1 is rejected)." }, "alertDaysBeforeExpiry": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "EnvelopeUpsertRequest": { "required": [ "documents", "recipients" ], "type": "object", "properties": { "documents": { "minItems": 1, "type": "array", "items": { "required": [ "referenceDocumentId", "name" ], "type": "object", "properties": { "referenceDocumentId": { "type": "integer", "description": "Client-assigned correlation id linking fields to this document within the same request." }, "name": { "type": "string" }, "loadMethod": { "type": "string", "description": "How to source the document's content. Currently only `storage` is supported, which fetches bytes from the location named by `urn`. There is no inline/base64 bytes field." }, "urn": { "type": "string", "description": "Storage location, only consulted when loadMethod is \"storage\". Obtained from a separate upload step; format not enforced by this service.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned by document/{documentId}/get.", "nullable": true } } } }, "fields": { "type": "array", "items": { "required": [ "referenceDocumentId", "name", "type" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "referenceDocumentId": { "type": "integer" }, "name": { "type": "string", "description": "PDF field name." }, "value": { "type": "string", "description": "Required (non-empty) only for type=note. Format otherwise depends entirely on type and is not validated by the server (e.g. attachment-type fields expect a JSON string, unvalidated on write).", "nullable": true }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "anchorString": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "isRequired": { "type": "boolean" }, "tooltip": { "type": "string", "nullable": true }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." } }, "description": "Exactly one of referenceSignerId/referenceSignGroupId must be set (strict XOR - unlike RecipientInput, having both set here is rejected). Exactly one positioning strategy must be set: anchorString, OR all four of page+height+width+positionX+positionY." } }, "recipients": { "minItems": 1, "type": "array", "items": { "required": [ "name", "email" ], "type": "object", "properties": { "referenceSignerId": { "type": "integer", "nullable": true }, "referenceSignGroupId": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when envelope.isSignOrder is true." }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "description": "Required only when role=inpersonsigner; must additionally resolve to an existing, valid subscription user.", "format": "email", "nullable": true }, "isMfaEnabled": { "type": "boolean" }, "phoneNumber": { "type": "string", "description": "No format validated. Required only if isMfaEnabled is true and the account's MFA channel is not email.", "nullable": true }, "externalContext": { "description": "Opaque; persisted and returned.", "nullable": true } }, "description": "At least one of referenceSignerId/referenceSignGroupId is required (both may be set)." } }, "signGroups": { "type": "array", "items": { "required": [ "referenceSignGroupId", "name", "role" ], "type": "object", "properties": { "referenceSignGroupId": { "type": "integer" }, "name": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "signOrder": { "type": "integer", "description": "Required to be non-zero only when envelope.isSignOrder is true." }, "mandatory": { "type": "boolean" } } } }, "envelope": { "type": "object", "properties": { "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "format": "email", "nullable": true }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer", "description": "0 means no expiry. Any non-zero value must be >= 2 (1 is rejected)." }, "alertDaysBeforeExpiry": { "type": "integer" }, "firstReminderDays": { "type": "integer", "nullable": true }, "repeatingReminderDays": { "type": "integer", "nullable": true }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "externalContext": { "description": "Opaque; persisted and echoed back in the response envelope.", "nullable": true } }, "description": "Unlike the regular envelope create/update request, documents/fields/recipients are not required to be non-empty here — a template can be saved with none of them." }, "EnvelopeUpsertResponseData": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "uploadDate": { "type": "string", "description": "Present on create; absent on update.", "format": "date-time" }, "status": { "type": "string", "description": "Always \"Draft\" immediately after create/update." } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "externalContext": { "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "readOnly": true } } }, "EnvelopeOpenResponseData": { "type": "object", "properties": { "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "readOnly": true }, "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "senderName": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "nullable": true }, "status": { "type": "string" }, "notifyWhenOpened": { "type": "boolean" }, "notifyWhenSigned": { "type": "boolean" }, "isSignOrder": { "type": "boolean" }, "expireInDays": { "type": "integer" }, "uploadDate": { "type": "string", "format": "date-time" }, "sendDate": { "type": "string", "format": "date-time", "nullable": true }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } }, "readOnly": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "readOnly": true }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signDate": { "type": "string", "nullable": true }, "signOrder": { "type": "integer" }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "mandatory": { "type": "boolean" }, "hostEmail": { "type": "string", "nullable": true } } }, "readOnly": true }, "signGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "enum": [ "signer", "inpersonsigner", "cc", "viewer" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "status": { "type": "string" }, "signOrder": { "type": "integer" }, "mandatory": { "type": "boolean" } } }, "readOnly": true }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "recipientId": { "type": "string", "format": "uuid", "nullable": true }, "signGroupId": { "type": "string", "format": "uuid", "nullable": true }, "documentId": { "type": "string", "format": "uuid" }, "type": { "enum": [ "signature", "digitalsignature", "text", "initial", "company", "title", "number", "note", "name", "email", "date", "checkbox", "radio", "stamp", "attachment", "drawing" ], "type": "string", "description": "Closed set enforced case-sensitively by the server." }, "value": { "type": "string", "nullable": true }, "page": { "type": "integer", "nullable": true }, "height": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "positionX": { "type": "number", "nullable": true }, "positionY": { "type": "number", "nullable": true }, "tooltip": { "type": "string", "nullable": true }, "isRequired": { "type": "boolean" }, "properties": { "type": "object", "properties": { "fontFamily": { "type": "string", "nullable": true }, "fontSize": { "type": "number", "nullable": true }, "color": { "type": "string", "nullable": true }, "bold": { "type": "boolean", "nullable": true }, "italic": { "type": "boolean", "nullable": true }, "underline": { "type": "boolean", "nullable": true }, "textAlign": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "isSignedDate": { "type": "boolean", "nullable": true }, "selectionGroup": { "type": "string", "nullable": true }, "selectionValue": { "type": "string", "nullable": true } }, "description": "Free-form field styling/behavior bag. No sub-field is validated by the server — values are stored and returned as-is." }, "signerInfo": { "description": "Certificate metadata, only for signed digitalsignature fields; computed, no fixed schema.", "nullable": true } } }, "description": "Filtered server-side to fields relevant to the caller unless the caller is done/canceled or has role viewer/cc - the set returned is viewer-dependent, not a fixed \"all fields\" list.", "readOnly": true }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "urn": { "type": "string", "description": "Opaque storage reference; format not defined by this service." }, "mimeType": { "type": "string", "nullable": true }, "documentId": { "type": "string", "format": "uuid" } } }, "description": "Derived from attachment-type field values. Does NOT include the attachment bytes (the underlying model has a Data property but this operation never populates or returns it) and there is no attachment id - documentId here is the parent document's id.", "readOnly": true }, "signer": { "type": "string", "description": "The caller's own signer id.", "format": "uuid", "readOnly": true }, "comments": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } }, "description": "Map keyed by document id; see envelope/{envelopeId}/get for the full comment shape.", "readOnly": true }, "savedSignatures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "data": { "type": "string", "description": "No format enforced." }, "isDefault": { "type": "boolean" } } }, "readOnly": true }, "settings": { "type": "array", "items": { "type": "object" }, "description": "Filtered to anonymous-visible settings.", "readOnly": true } } }, "SignFieldInput": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Must reference one of the current signer's/sign-group's own fields.", "format": "uuid" }, "value": { "type": "string", "description": "Required only if the field was configured isRequired at envelope-creation time (resolved server-side, not expressible as a static constraint here). For attachment-type fields, expected to be a JSON string of [{name, urn, mimeType}] - this is NOT validated on input; malformed JSON is silently dropped downstream, not rejected.", "nullable": true }, "certificate": { "type": "string", "description": "Base64 certificate blob for the digital-signature partial-hash flow. Stored/consumed as-is; no format enforced by this service.", "nullable": true }, "signedData": { "type": "string", "description": "Part of the digital-signature round trip; no format enforced by this service.", "nullable": true } } }, "HeadlessErrorResponse": { "required": [ "error", "dateTime" ], "type": "object", "properties": { "error": { "required": [ "innerErrors", "message", "statusCode" ], "type": "object", "properties": { "innerErrors": { "type": "array", "items": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "userMessage": { "type": "string" } } } }, "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true } }, "description": "The error envelope used by this service for exceptions not covered by the standard `ErrorResponse` schema used elsewhere in this document: a nested `error` object with an `innerErrors` array, rather than a flat `{code, message, eventId}` object.", "example": { "error": { "innerErrors": [ { "code": "VALIDATION_ERROR", "message": "Name is required.", "userMessage": "Name is required." } ], "message": "One or more validation errors occurred.", "statusCode": 400 }, "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123-00", "origin": "self-service-portal" } }, "RoleLevel": { "enum": [ 1, 2, 3 ], "type": "integer", "description": "Owner=1, Admin=2, Member=3. Serialized as a plain integer, not a string name.", "example": 2 }, "RoleScope": { "enum": [ 1, 2, 3, 4 ], "type": "integer", "description": "Application=1, Account=2, Subscription=3, Users=4. Serialized as a plain integer. `Application` scope cannot be granted through the self-service user-create/assign/update operations in this group.", "example": 3 }, "AccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "AccountGuid.", "format": "uuid", "readOnly": true }, "name": { "type": "string" }, "status": { "type": "string" }, "website": { "type": "string" }, "taxNumber": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid", "readOnly": true }, "domain": { "type": "string" } }, "description": "Account resource read straight from `dbo.Accounts`. No property carries a `[Required]`/validation attribute in source. Because the service applies `JsonIgnoreCondition.WhenWritingDefault` globally, any property holding its default value (a null string, `Guid.Empty`) is **omitted from the JSON entirely** rather than emitted as `null` -- none of these fields should be treated as guaranteed-present.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme Corp", "status": "Active", "website": "https://acme.example.com", "taxNumber": "US-123456789", "tenantId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "domain": "acme.example.com" } }, "AccountUpdateResultDto": { "type": "object", "properties": { "accountGuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "website": { "type": "string" }, "taxNumber": { "type": "string" } }, "description": "The shape actually returned by `PUT /platform/account/{accountId}/update`: an echo of the request DTO, **not** a fresh read of the persisted row and **not** `AccountResponseDto`. Confirmed structural mismatch with the GET response: identifier property is `accountGuid` (not `id`), and `status`/`tenantId`/`domain` are absent entirely. Treat as a distinct resource shape, do not unify with `AccountResponseDto`.", "example": { "accountGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme Corp", "website": "https://acme.example.com", "taxNumber": "US-123456789" } }, "UpdateAccountRequest": { "type": "object", "properties": { "name": { "type": "string" }, "website": { "type": "string" }, "taxNumber": { "type": "string" } }, "description": "`accountGuid` is intentionally not part of this schema — the `{accountId}` path parameter is used instead; any `accountGuid` supplied in the body is ignored. `name`/`website`/`taxNumber` have no format validation.", "example": { "name": "Acme Corp", "website": "https://acme.example.com", "taxNumber": "US-123456789" } }, "SimpleUserDto": { "type": "object", "properties": { "id": { "type": "string", "description": "= SubscriptionUserGUID.", "format": "uuid", "readOnly": true }, "fullName": { "type": "string" }, "userEmail": { "type": "string" } }, "description": "Minimal user projection returned only by `GET /platform/account/users/list`. No role, active-status, or date fields -- contrast with `SubscriptionUserDto` returned by the subscription-scoped user endpoints.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "userEmail": "jane.doe@example.com" } }, "SubscriptionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "= AMPSubscriptionId.", "format": "uuid", "readOnly": true }, "name": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "autoUserProvisioning": { "type": "boolean" }, "accountId": { "type": "string", "format": "uuid" }, "planName": { "type": "string" } }, "description": "Returned by `GET /platform/subscription/list` (as `subscriptions[]`) and `POST /platform/subscription/trial/start` (as `trialSubscription`, the one place a 'create' response shares a shape with a sibling read endpoint). `status` is an open string mixing genuine Microsoft `SubscriptionStatusEnum` values (e.g. `Subscribed`, `PendingFulfillmentStart`) with Maven-invented intermediate literals (`PendingActivation`, `UnsubscribeFailed`) -- do not model as a closed enum. `isActive`/`autoUserProvisioning` are non-nullable booleans in source: a real `false` value is omitted from the JSON entirely (global `WhenWritingDefault`), so a client must treat 'field absent' as `false`, not 'unknown'.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme - Enterprise Plan", "status": "Subscribed", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "autoUserProvisioning": true, "accountId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "planName": "Enterprise" } }, "SubscriptionInfoResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string" }, "status": { "type": "string", "description": "Open string, same Microsoft-enum-plus-Maven-literals superset as `SubscriptionResponseDto.status`. Not a closed enum." }, "platform": { "type": "string", "description": "NOT a stored value -- heuristically derived by substring-matching the plan's display name (`contains(\"microsoft\")`/`contains(\"enterprise\")` -> `Microsoft`; `contains(\"google\")`/`contains(\"pro\")` -> `Google`; else `Unknown`). Treat as non-authoritative, not a genuine stored attribute." }, "plan": { "type": "string", "description": "= Plans.DisplayName." }, "isActive": { "type": "boolean" }, "term": { "type": "string", "description": "Human-friendly text for 4 known Microsoft `TermUnitEnum` codes (`P1M`->'Per 1 Month', `P1Y`->'Per 1 Year', `P2Y`->'Per 2 Years', `P3Y`->'Per 3 Years'); any other raw code passes through unchanged. Not a closed enum in practice." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "accountId": { "type": "string", "format": "uuid" }, "autoUserProvisioning": { "type": "boolean" }, "purchaserEmail": { "type": "string" }, "isTransactable": { "type": "boolean", "description": "Derived from the subscription's plan type." }, "isPrivatePlan": { "type": "boolean", "description": "= Plans.IsPrivate." }, "availableOperations": { "type": "array", "items": { "type": "string" }, "description": "Metered-dimension display names for the subscription's plan." } }, "description": "Returned only by `GET /platform/subscription/{subscriptionId}/get`. `isActive`/`autoUserProvisioning`/`isTransactable`/`isPrivatePlan` are nullable booleans here; absence in the JSON means the value is unknown, not necessarily false.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme - Enterprise Plan", "status": "Subscribed", "platform": "Microsoft", "plan": "Enterprise", "isActive": true, "term": "Per 1 Year", "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "accountId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "autoUserProvisioning": true, "purchaserEmail": "jane.doe@example.com", "isTransactable": true, "isPrivatePlan": false, "availableOperations": [ "API Calls", "Storage GB" ] } }, "SubscriptionAuditDto": { "type": "object", "properties": { "attribute": { "type": "string" }, "oldValue": { "type": "string" }, "newValue": { "type": "string" }, "createDate": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "= SubscriptionUsers.FullName, or the literal `\"System\"` if CreatedBy is null/unmatched." } }, "description": "`attribute`/`oldValue`/`newValue` are free-text strings written by whatever service code called `SubscriptionAuditService.LogActionAsync` -- observed values include `attribute=\"Status\"` with status-string old/new values, but the column has no closed set enforced anywhere; treat as opaque text, not an enum.", "example": { "attribute": "Status", "oldValue": "PendingFulfillmentStart", "newValue": "PendingActivation", "createDate": "2026-01-01T12:00:00.0000000+00:00", "createdBy": "jane.doe@example.com" } }, "BillingSummaryDto": { "type": "object", "properties": { "dimension": { "type": "string" }, "totalQuantity": { "type": "number", "format": "double" }, "includedQuantity": { "type": "number", "format": "double" }, "billedQuantity": { "type": "number", "format": "double" }, "lastEntryDateTime": { "type": "string", "format": "date-time" }, "subscriptionStartDate": { "type": "string", "format": "date-time" }, "subscriptionEndDate": { "type": "string", "format": "date-time" } }, "description": "Read-only mirror of `dbo.BillingSummary`, populated by a separate timer-triggered process (`BillingService.ExecuteAsync`) that calls Microsoft's Metered Billing API -- this list endpoint itself has no direct external dependency, but the data is fundamentally Microsoft-driven and only as fresh as the last successful timer run. `totalQuantity`/`includedQuantity`/`billedQuantity` are non-nullable doubles: a genuine `0.0` (e.g. before any billing cycle has run) is omitted from the JSON per the global `WhenWritingDefault` option.", "example": { "dimension": "API Calls", "totalQuantity": 15000, "includedQuantity": 10000, "billedQuantity": 5000, "lastEntryDateTime": "2026-07-01T12:00:00.0000000+00:00", "subscriptionStartDate": "2026-01-01T12:00:00.0000000+00:00", "subscriptionEndDate": "2027-01-01T12:00:00.0000000+00:00" } }, "MeteringLogDto": { "type": "object", "properties": { "quantity": { "type": "number", "format": "double" }, "dimension": { "type": "string" }, "userEmail": { "type": "string" }, "startDateTime": { "type": "string", "format": "date-time" }, "endDateTime": { "type": "string", "format": "date-time" }, "details": { "type": "string" }, "groups": { "type": "string" }, "allocatedResources": { "type": "string", "description": "Numeric quantity echo despite the string type and resource-sounding name -- see schema-level note." }, "fullName": { "type": "string" }, "pricePerUnit": { "type": "number", "format": "float" }, "displayName": { "type": "string", "description": "= MeteredDimensions.Description." } }, "description": "`dimension`/`userEmail` fall back to `'Unknown'` rather than being absent. `groups` is a comma-joined list of group names, and is an empty string when there are none. `allocatedResources` reflects the plan's included quantity for the dimension, as a string.", "example": { "quantity": 120, "dimension": "api-calls", "userEmail": "jane.doe@example.com", "startDateTime": "2026-07-01T12:00:00.0000000+00:00", "endDateTime": "2026-07-01T01:00:00.0000000+00:00", "details": "Batch ingest job", "groups": "Finance,Engineering", "allocatedResources": "10000", "fullName": "Jane Doe", "pricePerUnit": 0.05, "displayName": "API Calls" } }, "SubscriptionUserDto": { "type": "object", "properties": { "id": { "type": "string", "description": "= SubscriptionUserGUID.", "format": "uuid", "readOnly": true }, "fullName": { "type": "string" }, "userEmail": { "type": "string" }, "isActive": { "type": "boolean" }, "roleId": { "type": "string", "description": "Not populated by either endpoint that returns this DTO today.", "format": "uuid", "readOnly": true }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "userDetails": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/RoleScope" }, "level": { "$ref": "#/components/schemas/RoleLevel" } }, "description": "Only populated by `GET .../user/list`; always absent on `POST .../user/create`." }, "settings": { "type": "array", "items": { "type": "object" }, "description": "Not populated by either endpoint that returns this DTO today." } }, "description": "Shared response DTO returned by both `POST /platform/subscription/{subscriptionId}/user/create` (array, under the JSON key `\"user\"`) and `GET /platform/subscription/{subscriptionId}/user/list` (array, under the key `\"users\"`). Field population differs by endpoint: on `user/create`, `roleId`/`userDetails`/`settings` are not populated; on `user/list`, `userDetails.scope`/`userDetails.level` are populated while `roleId`/`settings` remain unpopulated there too.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "userEmail": "jane.doe@example.com", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "userDetails": { "scope": 3, "level": 2 } } }, "SubscriptionMemberUpdatedDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "endDate": { "type": "string", "format": "date-time" } }, "description": "Returned by both `POST /platform/subscription/{subscriptionId}/user/{userId}/assign` and `PUT /platform/subscription/{subscriptionId}/user/{userId}/update` under the same `\"user\"` key. Never echoes the `roleLevel`/`roleScope` that was applied by the request -- a caller cannot verify the resulting role purely from this response.", "example": { "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": true, "isDefault": true, "endDate": "2027-01-01T12:00:00.0000000+00:00" } }, "MarketplaceTokenRequest": { "required": [ "token" ], "type": "object", "properties": { "token": { "type": "string" } }, "description": "`token` is the raw Azure Marketplace resolve token forwarded by Microsoft's AMP redirect. Must be non-blank. Callers should URL-encode the token even though it sits inside a JSON body.", "example": { "token": "eyJhbGciOiJIUzI1NiJ9.example-marketplace-resolve-token" } }, "FreeTrialRequest": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "jobTitle": { "type": "string" }, "companyName": { "type": "string", "description": "Should be non-blank in practice — see schema-level note." }, "companySize": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "emailAddress": { "type": "string" }, "phoneNumber": { "type": "string" }, "subscribeToUpdates": { "type": "boolean" }, "platform": { "type": "string", "description": "Case-insensitive; only \"google\" is treated as Google, everything else (including omission) is treated as Microsoft." }, "externalId": { "type": "string" } }, "description": "`companyName` should be non-blank in practice. `platform` is matched case-insensitively; only `\"google\"` selects the Google validation path — everything else (including omission) is treated as Microsoft.", "example": { "firstName": "Jane", "lastName": "Doe", "jobTitle": "IT Manager", "companyName": "Acme Corp", "companySize": "51-200", "country": "United States", "city": "Austin", "street": "123 Main St", "emailAddress": "jane.doe@example.com", "phoneNumber": "+1-512-555-0100", "subscribeToUpdates": true, "platform": "microsoft", "externalId": "ext-12345" } }, "SubscriptionUserCreateRequest": { "required": [ "userEmail", "roleLevel", "roleScope" ], "type": "object", "properties": { "userEmail": { "type": "string" }, "fullName": { "type": "string" }, "roleLevel": { "$ref": "#/components/schemas/RoleLevel" }, "roleScope": { "$ref": "#/components/schemas/RoleScope" }, "startDate": { "type": "string", "format": "date-time", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "default": true, "nullable": true } }, "description": "Request body for `POST /platform/subscription/{subscriptionId}/user/create` is a bare JSON array of this type, not an object wrapper. Blank/whitespace `userEmail` returns a non-standard 400 (see the operation's own 400 response). `roleLevel`/`roleScope` are effectively required — treat them as required even though omitting them surfaces as a generic 500 rather than a clean 400. `roleScope=Application(1)` is rejected at runtime (`PERMISSION_DENIED`). `endDate`, if present, must be `>= (startDate ?? now)` or `VALIDATION_ERROR` is thrown. `isActive` defaults to `true` if omitted. An array item whose `(subscriptionId, userEmail)` membership already exists is skipped without error; the response array can be shorter than the request array.", "example": { "userEmail": "jane.doe@example.com", "fullName": "Jane Doe", "roleLevel": 2, "roleScope": 3, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "", "isActive": true } }, "CreateSubscriptionMemberRequest": { "required": [ "roleLevel", "roleScope" ], "type": "object", "properties": { "isActive": { "type": "boolean", "default": true, "nullable": true }, "roleLevel": { "$ref": "#/components/schemas/RoleLevel" }, "roleScope": { "$ref": "#/components/schemas/RoleScope" }, "isDefault": { "type": "boolean", "nullable": true }, "startDate": { "type": "string", "format": "date-time", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true } }, "description": "Request body for `POST /platform/subscription/{subscriptionId}/user/{userId}/assign`. The user identified by `{userId}` must already exist — this endpoint never creates a new user record (contrast with `user/create`). `roleLevel`/`roleScope` are effectively required — omitting either results in a 500 (`ASSIGN_USER_ERROR`) rather than a clean 400. Unlike `user/create`, there is no `endDate >= startDate` check on this endpoint. `isActive` defaults to `true` if omitted.", "example": { "isActive": true, "roleLevel": 3, "roleScope": 3, "isDefault": false, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "" } }, "SubscriptionMemberUpdateRequest": { "type": "object", "properties": { "isActive": { "type": "boolean", "nullable": true }, "isDefault": { "type": "boolean", "nullable": true }, "roleScope": { "$ref": "#/components/schemas/RoleScope" }, "roleLevel": { "$ref": "#/components/schemas/RoleLevel" }, "endDate": { "type": "string", "format": "date-time", "nullable": true } }, "description": "Request body for `PUT /platform/subscription/{subscriptionId}/user/{userId}/update`. Deliberately has no `startDate` field (present on both `user/create` and `user/assign`) — start date cannot be modified once a membership exists. `roleLevel`/`roleScope` are optional here, unlike `user/create`/`user/assign` — do not mark them required. `isActive` omission means 'leave unchanged', not 'set true' (unlike create's implicit `true`). If a role change is requested but the resulting `(scope, level)` combination doesn't correspond to a real role, `NOT_FOUND_BY_ID` is thrown. `endDate` accepts any date including one in the past. A null/absent request body returns a non-standard 400 (see the operation's own 400 response).", "example": { "isActive": true, "isDefault": false, "roleScope": 3, "roleLevel": 2, "endDate": "2027-06-01T12:00:00.0000000+00:00" } }, "SubscriptionValidationBadRequestResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "description": "Always null for this response.", "nullable": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string" }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string" } }, "description": "Non-standard 400 shape used by a small number of validation checks in this group — an empty/null request array or blank `userEmail` on `POST .../user/create`, and a null/absent request body on `PUT .../user/{userId}/update`. This uses the success-shaped `GenericResponse` envelope (`result.data/statusCode/message`) with `statusCode: 400` embedded and `data` always null — not the standard `ErrorResponse`/`error.innerErrors[]` shape used elsewhere in this group. A client that assumes all 4xx/5xx responses use the standard error envelope will be wrong for these specific cases.", "example": { "result": { "data": "", "statusCode": 400, "message": "Request body cannot be empty." }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "AccountGetResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountResponseDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/account/get.", "example": { "result": { "data": { "account": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme Corp", "status": "Active", "website": "https://acme.example.com", "taxNumber": "US-123456789", "tenantId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "domain": "acme.example.com" } }, "statusCode": 200, "message": "Account retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "AccountUpdateResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountUpdateResultDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for PUT /platform/account/{accountId}/update. `data.account` is an echo of the request DTO, not a fresh read of the persisted row -- see AccountUpdateResultDto.", "example": { "result": { "data": { "account": { "accountGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme Corp", "website": "https://acme.example.com", "taxNumber": "US-123456789" } }, "statusCode": 200, "message": "Account updated successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "AccountUsersListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/SimpleUserDto" } } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/account/users/list. Has no `rowCount` field — the entire matching result set is always returned, with no pagination.", "example": { "result": { "data": { "users": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "userEmail": "jane.doe@example.com" } ] }, "statusCode": 200, "message": "Users for account retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionResponseDto" } }, "rowCount": { "type": "integer", "description": "Reflects the count of items on this page, not the total across all pages. Do not use this to build pagination-total UI." } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/list.", "example": { "result": { "data": { "subscriptions": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme - Enterprise Plan", "status": "Subscribed", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "autoUserProvisioning": true, "accountId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "planName": "Enterprise" } ], "rowCount": 25 }, "statusCode": 200, "message": "Customer subscriptions retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionGetResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/SubscriptionInfoResponseDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/{subscriptionId}/get. **This operation has no auth check at all in the running service** -- see the operation description and security note.", "example": { "result": { "data": { "subscription": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme - Enterprise Plan", "status": "Subscribed", "platform": "Microsoft", "plan": "Enterprise", "isActive": true, "term": "Per 1 Year", "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "accountId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "autoUserProvisioning": true, "purchaserEmail": "jane.doe@example.com", "isTransactable": true, "isPrivatePlan": false, "availableOperations": [ "API Calls", "Storage GB" ] } }, "statusCode": 200, "message": "Subscription retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionAuditListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "audits": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAuditDto" } }, "rowCount": { "type": "integer", "description": "A true total across all matching rows, independent of the current page." } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/{subscriptionId}/audit/list.", "example": { "result": { "data": { "audits": [ { "attribute": "Status", "oldValue": "PendingFulfillmentStart", "newValue": "PendingActivation", "createDate": "2026-01-01T12:00:00.0000000+00:00", "createdBy": "jane.doe@example.com" } ], "rowCount": 1 }, "statusCode": 200, "message": "Subscription logs retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionBillingListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "billing": { "type": "array", "items": { "$ref": "#/components/schemas/BillingSummaryDto" } }, "rowCount": { "type": "integer", "description": "A true total across all matching rows, independent of the current page." } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/{subscriptionId}/billing/list.", "example": { "result": { "data": { "billing": [ { "dimension": "API Calls", "totalQuantity": 15000, "includedQuantity": 10000, "billedQuantity": 5000, "lastEntryDateTime": "2026-07-01T12:00:00.0000000+00:00", "subscriptionStartDate": "2026-01-01T12:00:00.0000000+00:00", "subscriptionEndDate": "2027-01-01T12:00:00.0000000+00:00" } ], "rowCount": 1 }, "statusCode": 200, "message": "Billing summary retrieved" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionMeteringListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "meteringLogs": { "type": "array", "items": { "$ref": "#/components/schemas/MeteringLogDto" } }, "rowCount": { "type": "integer", "description": "Reflects only the current page's count, not the total across all matching rows. Do not use this to build pagination-total UI." } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/{subscriptionId}/metering/list.", "example": { "result": { "data": { "meteringLogs": [ { "quantity": 120, "dimension": "api-calls", "userEmail": "jane.doe@example.com", "startDateTime": "2026-07-01T12:00:00.0000000+00:00", "endDateTime": "2026-07-01T01:00:00.0000000+00:00", "details": "Batch ingest job", "groups": "Finance,Engineering", "allocatedResources": "10000", "fullName": "Jane Doe", "pricePerUnit": 0.05, "displayName": "API Calls" } ], "rowCount": 10 }, "statusCode": 200, "message": "Metering logs retrieved successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionTrialStartResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trialSubscription": { "$ref": "#/components/schemas/SubscriptionResponseDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for POST /platform/subscription/trial/start. Real HTTP status is 201, not 200. Uses the same `SubscriptionResponseDto` shape as GET /platform/subscription/list.", "example": { "result": { "data": { "trialSubscription": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme - Enterprise Plan", "status": "Subscribed", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "autoUserProvisioning": true, "accountId": "8f14e45f-ceea-467e-adde-3fb5ba62c9d2", "planName": "Enterprise" } }, "statusCode": 201, "message": "Created" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionUserCreateResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionUserDto" } } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for POST /platform/subscription/{subscriptionId}/user/create. Real HTTP status is 201, not 200. The JSON key is the singular `\"user\"` even though the value is an array. The array can be shorter than the request array: items whose `(subscriptionId, userEmail)` membership already exists are skipped without error.", "example": { "result": { "data": { "user": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "userEmail": "jane.doe@example.com", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "userDetails": { "scope": 3, "level": 2 } } ] }, "statusCode": 201, "message": "Subscription user created successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionUserAssignResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/SubscriptionMemberUpdatedDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for POST /platform/subscription/{subscriptionId}/user/{userId}/assign. Real HTTP status is 201, not 200. `data.user` here is a singular object under the `\"user\"` key (contrast with `user/create`, where the same key holds an array).", "example": { "result": { "data": { "user": { "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": true, "isDefault": true, "endDate": "2027-01-01T12:00:00.0000000+00:00" } }, "statusCode": 201, "message": "Subscription member assigned successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionUserListResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionUserDto" } }, "rowCount": { "type": "integer", "description": "Reflects only the current page's count, not the total across all matching rows. Do not use this to build pagination-total UI." } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for GET /platform/subscription/{subscriptionId}/user/list. Note the JSON key here is **plural** `\"users\"`, contrasted with `user/create`'s singular `\"user\"` key for a conceptually similar array -- confirmed naming inconsistency between the two, both preserved as-is.", "example": { "result": { "data": { "users": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "userEmail": "jane.doe@example.com", "isActive": true, "startDate": "2026-01-01T12:00:00.0000000+00:00", "endDate": "2027-01-01T12:00:00.0000000+00:00", "userDetails": { "scope": 3, "level": 2 } } ], "rowCount": 10 }, "statusCode": 200, "message": "Subscription users retrieved" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionUserUnassignResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "description": "Always absent from the response.", "nullable": true }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for DELETE /platform/subscription/{subscriptionId}/user/{userId}/unassign. Returns HTTP 200 with no meaningful response data.", "example": { "result": { "statusCode": 200, "message": "User unassigned from subscription successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SubscriptionUserUpdateResponse": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/SubscriptionMemberUpdatedDto" } } }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } }, "origin": { "type": "string", "description": "Echoed verbatim from the request's X-Origin header." }, "dateTime": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "description": "From Activity.Current?.RootId." } }, "description": "Success envelope for PUT /platform/subscription/{subscriptionId}/user/{userId}/update. Same response shape/key as `user/{userId}/assign` -- also never echoes the resulting `roleLevel`/`roleScope`.", "example": { "result": { "data": { "user": { "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isActive": true, "isDefault": true, "endDate": "2027-01-01T12:00:00.0000000+00:00" } }, "statusCode": 200, "message": "User updated successfully" }, "origin": "platform-api", "dateTime": "2026-01-01T12:00:00.0000000+00:00", "operationId": "00-abc123def456-00" } }, "SettingScopeMetaDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "SettingCategoryMetaDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "SettingGroupMetaDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." }, "SettingMetaDto": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } }, "SettingDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "LimitGroupDto": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_MONTH/*_USER_MONTH setting exists." }, "yearly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_YEAR/*_USER_YEAR setting exists." } } }, "LimitSettingDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Raw dimension name from the database." }, "allocatedResources": { "type": "string", "description": "Human-readable display string, not a machine-parseable number — e.g. \"1000 per month\", \"500 per year\", \"250 per 2 years\", or \"Unlimited\". Clients needing the numeric limit should read subscriptionLimits/userLimits instead." }, "displayName": { "type": "string" }, "groups": { "type": "string", "description": "Comma-joined string of group names (e.g. \"Group A,Group B\") — NOT a JSON array, despite representing a list conceptually." }, "pricePerUnit": { "type": "number", "description": "Omitted from the response when null.", "format": "float", "nullable": true }, "subscriptionLimits": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_MONTH/*_USER_MONTH setting exists." }, "yearly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_YEAR/*_USER_YEAR setting exists." } } }, "userLimits": { "type": "object", "properties": { "monthly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_MONTH/*_USER_MONTH setting exists." }, "yearly": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "value": { "type": "string", "description": "Current effective value. Always a string on the wire even though limit values are semantically integers." }, "defaultValue": { "type": "string" }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single effective setting value, as embedded in GET /common/limits/get's subscriptionLimits/userLimits." }, "description": "Empty array (never null/omitted) when no matching *_SUBSCRIPTION_YEAR/*_USER_YEAR setting exists." } } } }, "description": "One metered dimension's limit configuration, as returned inside the `settings` array of GET /common/limits/get.", "example": { "name": "ENVELOPES", "allocatedResources": "1000 per month", "displayName": "Envelopes Sent", "groups": "Signature,Core", "pricePerUnit": 0.05, "subscriptionLimits": { "monthly": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ENVELOPES_LIMIT_SUBSCRIPTION_MONTH", "value": "1000", "defaultValue": "500", "meta": { "application": "MH", "scope": { "name": "Subscription" }, "category": { "name": "Limits" }, "subCategory": { "name": "Envelopes" }, "group": { "key": "limits", "name": "Limits" } } } ], "yearly": [] }, "userLimits": { "monthly": [], "yearly": [] } } }, "SettingAllowedValueDto": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } } }, "SettingDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "value": { "type": "string" }, "defaultValue": { "type": "string" }, "type": { "type": "string", "description": "Free-form string describing the setting's value type." }, "icon": { "type": "string" }, "allowedValues": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } } }, "description": "Null (not an empty array) when the setting has no enumerated allowed values configured.", "nullable": true }, "meta": { "type": "object", "properties": { "application": { "type": "string" }, "scope": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted from the response when Guid.Empty (global WhenWritingDefault default-omission policy), not emitted as an explicit empty GUID.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "priority": { "type": "integer", "description": "Omitted from the response when 0, not emitted as an explicit 0.", "nullable": true } }, "description": "Scope metadata for a setting definition (Meta.Scope)." }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "subCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Category (or sub-category) metadata for a setting definition. Same shape is reused for both Meta.category and Meta.subCategory." }, "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Omitted when Guid.Empty.", "format": "uuid", "nullable": true }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "sortOrder": { "type": "integer", "description": "Omitted when 0.", "nullable": true } }, "description": "Group metadata for a setting definition (Meta.group)." } } } }, "description": "A single setting definition with its current effective value, as returned by GET /common/settings/get.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "ALLOWED_SIGNATURE_INPUT_METHOD", "label": "Allowed Signature Input Method", "description": "Controls which signature input methods are permitted.", "value": "Draw,Type", "defaultValue": "Draw,Type,Upload", "type": "string", "icon": "signature", "allowedValues": "", "meta": { "application": "MH", "scope": { "name": "Account" }, "category": { "name": "Signing" }, "subCategory": { "name": "Input" }, "group": { "key": "signing", "name": "Signing" } } } }, "UpdateSettingItemDto": { "type": "object", "properties": { "settingDefinitionId": { "type": "string", "description": "If unknown (no matching setting definition), the item is skipped without error.", "format": "uuid" }, "settingScopeId": { "type": "string", "description": "GUID of the scope entity (user/account/subscription) this setting override applies to.", "format": "uuid" }, "scope": { "type": "string", "description": "One of \"user\", \"account\", \"subscription\" (case-insensitive)." }, "value": { "type": "string", "description": "Interpretation depends on which setting `key` this item's `settingDefinitionId` resolves to — see the operation description for the small set of keys with real, enforced validation. Blank/whitespace resets the setting to its default value on next read." }, "entityId": { "type": "string", "description": "Target user/account/subscription for the write. For scope \"user\" any client-supplied value here is ignored and always overwritten with the caller's own id.", "format": "uuid", "nullable": true } }, "description": "One setting write in a PUT /common/settings/update batch." }, "UpdateSettingsRequestDto": { "required": [ "settings" ], "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "settingDefinitionId": { "type": "string", "description": "If unknown (no matching setting definition), the item is skipped without error.", "format": "uuid" }, "settingScopeId": { "type": "string", "description": "GUID of the scope entity (user/account/subscription) this setting override applies to.", "format": "uuid" }, "scope": { "type": "string", "description": "One of \"user\", \"account\", \"subscription\" (case-insensitive)." }, "value": { "type": "string", "description": "Interpretation depends on which setting `key` this item's `settingDefinitionId` resolves to — see the operation description for the small set of keys with real, enforced validation. Blank/whitespace resets the setting to its default value on next read." }, "entityId": { "type": "string", "description": "Target user/account/subscription for the write. For scope \"user\" any client-supplied value here is ignored and always overwritten with the caller's own id.", "format": "uuid", "nullable": true } }, "description": "One setting write in a PUT /common/settings/update batch." }, "description": "Required. An empty array is a safe no-op." } }, "example": { "settings": [ { "settingDefinitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "settingScopeId": "5a2e7b10-8c3e-4a1a-9e3a-1f2b3c4d5e6f", "scope": "account", "value": "5", "entityId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ] } }, "DashboardRecentEnvelopeSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" } }, "description": "One row of the dashboard summary's recentEnvelopes list." }, "DashboardOldestTodoEnvelopeSummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sendDate": { "type": "string", "format": "date-time" }, "userName": { "type": "string", "description": "Submitter's full name." }, "tid": { "type": "string", "description": "Transaction token GUID; may be absent/null if none exists for this envelope.", "format": "uuid", "nullable": true } }, "description": "One row of the dashboard summary's oldestTodoEnvelopes list." }, "DashboardLatestPendingActivityDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "action": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "person": { "type": "string", "description": "Coalesced: submitter full name, else signer name, else literal \"N/A\"." } }, "description": "One row of the dashboard summary's latestPendingEnvelopes list (the latest audit event per pending envelope)." }, "DashboardSummaryDto": { "type": "object", "properties": { "todo": { "type": "integer", "description": "Count of \"In Progress\" envelopes where the caller is the current/next signer.", "nullable": true }, "pending": { "type": "integer", "description": "\"In Progress\" envelopes waiting on someone else, or already completed by this signer.", "nullable": true }, "inbox": { "type": "integer", "description": "Envelopes not Draft/Deleted where the caller is next signer in order.", "nullable": true }, "expiring": { "type": "integer", "description": "\"In Progress\" envelopes expiring within [0, AlertDaysBeforeExpiry] days.", "nullable": true }, "completed": { "type": "integer", "description": "Envelopes with Status = 'Completed'.", "nullable": true }, "recentEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" } }, "description": "One row of the dashboard summary's recentEnvelopes list." }, "description": "Top 3, terminal-status envelopes owned by the caller, ordered by send date descending." }, "oldestTodoEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sendDate": { "type": "string", "format": "date-time" }, "userName": { "type": "string", "description": "Submitter's full name." }, "tid": { "type": "string", "description": "Transaction token GUID; may be absent/null if none exists for this envelope.", "format": "uuid", "nullable": true } }, "description": "One row of the dashboard summary's oldestTodoEnvelopes list." }, "description": "Top 5 oldest \"todo\" envelopes, ordered by send date ascending." }, "latestPendingEnvelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "action": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "person": { "type": "string", "description": "Coalesced: submitter full name, else signer name, else literal \"N/A\"." } }, "description": "One row of the dashboard summary's latestPendingEnvelopes list (the latest audit event per pending envelope)." }, "description": "Top 5, latest audit event per pending envelope." } }, "description": "Response data for GET /common/summary?type=dashboard.", "example": { "todo": 3, "pending": 1, "inbox": 5, "expiring": 0, "completed": 42, "recentEnvelopes": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "NDA - Acme Corp", "status": "Completed" } ], "oldestTodoEnvelopes": [ { "id": "5a2e7b10-8c3e-4a1a-9e3a-1f2b3c4d5e6f", "name": "Vendor Agreement", "sendDate": "2026-06-01T12:00:00.0000000+00:00", "userName": "Jane Submitter", "tid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "latestPendingEnvelopes": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Offer Letter", "action": "Viewed", "timestamp": "2026-07-01T12:00:00.0000000+00:00", "person": "John Signer" } ] } }, "SelfServiceSubscriptionSummaryItemDto": { "type": "object", "properties": { "count": { "type": "integer" }, "status": { "type": "string" } } }, "SelfServiceSubscriptionsSummaryDto": { "type": "object", "properties": { "total": { "type": "integer", "description": "Sum of the counts in `details`." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/SelfServiceSubscriptionSummaryItemDto" } } } }, "SelfServiceUserStatusSummaryItemDto": { "type": "object", "properties": { "status": { "type": "string", "description": "Literal \"Active\" or \"Inactive\"." }, "count": { "type": "integer" } } }, "SelfServiceUsersSummaryDto": { "type": "object", "properties": { "total": { "type": "integer", "description": "ActiveCount + NotActiveCount." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/SelfServiceUserStatusSummaryItemDto" } } } }, "SelfServiceSummaryDto": { "type": "object", "properties": { "subscriptions": { "$ref": "#/components/schemas/SelfServiceSubscriptionsSummaryDto" }, "users": { "$ref": "#/components/schemas/SelfServiceUsersSummaryDto" }, "limits": { "type": "integer", "description": "Count of limit breaches across the caller's visible subscriptions.", "nullable": true } }, "description": "Response data for GET /common/summary?type=self-service. `subscriptions`/`users`/`limits` are scoped to subscriptions the caller can administer (directly, or via an Account-level Admin/Owner role).", "example": { "subscriptions": { "total": 2, "details": [ { "count": 2, "status": "Active" } ] }, "users": { "total": 5, "details": [ { "status": "Active", "count": 4 }, { "status": "Inactive", "count": 1 } ] }, "limits": 0 } }, "UserContactDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Absent from the response when false, rather than serialized as an explicit false (global WhenWritingDefault default-omission policy) — a missing key means false/not-shared, not \"unspecified\"." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; identifies the contact's owning user. Omitted when Guid.Empty.", "format": "uuid", "nullable": true } }, "description": "Response representation of a user contact.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": true, "subscriptionUserGuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "UserContactCreateRequestDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Any client-supplied value here is ignored on Create — the persisted contact's id is server-generated.", "format": "uuid" }, "name": { "type": "string", "description": "Contact name. No length limit is enforced." }, "email": { "type": "string", "description": "Contact email. No format validation is enforced." }, "sharedWithAccount": { "type": "boolean", "description": "Ignored on Create — always derived from the caller's own account settings. Included here only to document the wire shape. Contrast with Update, where this field is a normal writable field.", "readOnly": true }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; not used on input.", "format": "uuid", "nullable": true, "readOnly": true } }, "description": "Request body for POST /common/user/contact/create.", "example": { "name": "Jane Doe", "email": "jane.doe@example.com" } }, "UserContactUpdateRequestDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Any client-supplied value here is ignored — the contact's id is always taken from the {userContactId} path segment instead.", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "sharedWithAccount": { "type": "boolean", "description": "Ordinary writable field on Update, trusted as-is from the client (unlike Create, where this field is server-derived and any client value is discarded)." }, "subscriptionUserGuid": { "type": "string", "description": "Display-only; not used on input.", "format": "uuid", "nullable": true, "readOnly": true } }, "description": "Request body for PUT /common/user/contact/{userContactId}/update.", "example": { "name": "Jane Doe", "email": "jane.doe@example.com", "sharedWithAccount": false } }, "UserContactDeleteResultDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "description": "Returned with HTTP 200 regardless of whether a matching contact existed and was deleted.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "message": "User contact successfully deleted." } }, "CurrentUserSettingDto": { "type": "object", "properties": { "settingKey": { "type": "string" }, "value": { "type": "string" } }, "description": "Partial, best-effort shape of the caller's settings." }, "CurrentUserRoleDetailsDto": { "type": "object", "properties": { "scope": { "type": "integer" }, "level": { "type": "integer" } }, "description": "Raw role scope/level ordinals. Do not assume a specific integer-to-label mapping when consuming this." }, "CurrentUserDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "description": "Absent from the response when false (global default-omission policy)." }, "roleId": { "type": "string", "format": "uuid" }, "userEmail": { "type": "string" }, "settings": { "type": "array", "items": { "type": "object", "properties": { "settingKey": { "type": "string" }, "value": { "type": "string" } }, "description": "Partial, best-effort shape of the caller's settings." }, "description": "Best-effort partial shape — only `settingKey`/`value` are confirmed populated." }, "userDetails": { "type": "object", "properties": { "scope": { "type": "integer" }, "level": { "type": "integer" } }, "description": "Raw role scope/level ordinals. Do not assume a specific integer-to-label mapping when consuming this." } }, "description": "Response data for GET /common/user/get. Note: startDate/endDate/isActive are read directly off the membership record (SubscriptionMembers), while fullName/userEmail/id/settings are read off its nested SubscriptionUser sub-object — two distinct nested objects on an external type, flattened here with no naming cue as to which sub-object each field originated from.", "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "startDate": "2025-01-01T12:00:00.0000000+00:00", "isActive": true, "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "userEmail": "jane.doe@example.com", "settings": [ { "settingKey": "ALLOW_CONTACT_SHARE", "value": "true" } ], "userDetails": { "scope": 1, "level": 1 } } }, "UploadResponseFile": { "required": [ "id", "fileName" ], "type": "object", "properties": { "id": { "type": "string", "description": "Server-generated storage identifier (GUID) for the uploaded file. Reference this in downstream requests.", "format": "uuid", "readOnly": true }, "fileName": { "type": "string", "description": "Stored file name. For form-data uploads this is the original client-supplied filename; for raw-body/JSON uploads it is a server-generated name (e.g. document${guid}.{extension} or data${guid}.json).", "readOnly": true } } }, "UploadSuccessResponse": { "required": [ "result", "origin", "dateTime", "operationId" ], "type": "object", "properties": { "result": { "required": [ "data", "statusCode", "message" ], "type": "object", "properties": { "data": { "required": [ "files" ], "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "required": [ "id", "fileName" ], "type": "object", "properties": { "id": { "type": "string", "description": "Server-generated storage identifier (GUID) for the uploaded file. Reference this in downstream requests.", "format": "uuid", "readOnly": true }, "fileName": { "type": "string", "description": "Stored file name. For form-data uploads this is the original client-supplied filename; for raw-body/JSON uploads it is a server-generated name (e.g. document${guid}.{extension} or data${guid}.json).", "readOnly": true } } }, "description": "One entry per uploaded file. Form-data uploads return one entry per file in the same order they were sent; raw-body/JSON uploads always return exactly one entry." } } }, "statusCode": { "type": "integer", "description": "HTTP status code of the operation. Always 201 for a successful upload.", "readOnly": true }, "message": { "type": "string", "description": "Outcome message. Always \"Created\" for a successful upload.", "readOnly": true } } }, "origin": { "type": "string", "description": "Value of the X-Origin request header, echoed back verbatim. Empty if the header was not supplied.", "readOnly": true }, "dateTime": { "type": "string", "description": "UTC timestamp when the response was generated.", "format": "date-time", "readOnly": true }, "operationId": { "type": "string", "description": "Server-side trace identifier for correlating logs and support requests. May be null.", "nullable": true, "readOnly": true } }, "example": { "result": { "data": { "files": [ { "id": "3a4b5c6d-7e8f-4011-8223-3445566778899", "fileName": "example.docx" } ] }, "statusCode": 201, "message": "Created" }, "origin": "https://app.mavenmule.com", "dateTime": "2026-07-14T09:32:15.0000000+00:00", "operationId": "3a4b5c6d7e8f90112233445566778899" } }, "DriveActionRequest": { "required": [ "httpAction", "targetUrl" ], "type": "object", "properties": { "httpAction": { "type": "string", "description": "The HTTP method to use for the outbound request (e.g. GET, POST, PUT, DELETE)." }, "targetUrl": { "type": "string", "description": "The full destination URL the request is proxied to.", "format": "uri" }, "body": { "description": "Optional request body, forwarded to the target as raw JSON text (Content-Type: application/json; charset=utf-8) regardless of the value's actual shape." }, "headers": { "type": "string", "description": "Optional extra headers to attach to the outbound request, as a JSON-ENCODED STRING containing a flat object of header-name/header-value pairs — this is a string field, not a nested JSON object, in the outer request body. Any caller-supplied 'Authorization' entry inside this dictionary is ignored: the server always overwrites the outbound Authorization header with its own resolved credential (see operation description)." } }, "example": { "httpAction": "GET", "targetUrl": "https://graph.microsoft.com/v1.0/me/drive/root/children?$select=id,name", "body": "", "headers": "{\"Accept\":\"application/json\"}" } }, "ConsentModel": { "required": [ "ipAddress", "termDefinitionId", "sessionId", "sessionStartDatetime", "sessionExpirationDatetime", "accepted", "acceptedDatetime" ], "type": "object", "properties": { "ipAddress": { "type": "string", "description": "Captured from the request's X-Origin-IpAddress header at consent-creation time. If that header wasn't sent, this is the literal string \"Header Empty\", not blank/null.", "readOnly": true }, "termDefinitionId": { "type": "string", "description": "The term definition this consent was created against.", "readOnly": true }, "sessionId": { "type": "string", "readOnly": true }, "sessionStartDatetime": { "type": "string", "format": "date-time", "readOnly": true }, "sessionExpirationDatetime": { "type": "string", "format": "date-time", "readOnly": true }, "environmentData": { "type": "string", "description": "Set via PUT edit. Stored as-is; the service doesn't define or validate its format.", "nullable": true, "readOnly": true }, "additionalData": { "type": "string", "description": "Set via PUT edit. Stored as-is; the service doesn't define or validate its format.", "nullable": true, "readOnly": true }, "externalUserId": { "type": "string", "description": "Caller-supplied identifier, stored as-is. May be set on create or edit.", "nullable": true, "readOnly": true }, "accepted": { "type": "boolean", "description": "False until the consent is edited. Editing can also result in false even when the caller most recently sent true, e.g. if the resent term text doesn't match what was originally shown for this session.", "readOnly": true }, "acceptedDatetime": { "type": "string", "description": "0001-01-01T00:00:00 before the consent has been accepted.", "format": "date-time", "readOnly": true } } }, "TermDefinitionModel": { "required": [ "termDefinitionId" ], "type": "object", "properties": { "termDefinitionId": { "type": "string", "readOnly": true }, "termDefinitionRelatedId": { "type": "string", "description": "Not populated by this API's create endpoint; passed through as-is from storage if present.", "nullable": true, "readOnly": true }, "name": { "type": "string", "nullable": true, "readOnly": true }, "code": { "type": "string", "nullable": true, "readOnly": true }, "text": { "type": "string", "description": "The text/HTML shown to end-users during consent. Can be empty if the term definition was created without one — see the change-summary for the downstream effect this has on consent creation.", "nullable": true, "readOnly": true }, "isActive": { "type": "string", "description": "Passed through as-is from storage. No allowed-value set is enforced or defined by this service.", "nullable": true, "readOnly": true } } }, "ClickwrapPaginationInfo": { "required": [ "currentPage", "count", "pageSize", "hasNext", "hasPrevious" ], "type": "object", "properties": { "currentPage": { "type": "integer", "readOnly": true }, "count": { "type": "integer", "description": "Number of items on this page, not a grand total across all pages.", "readOnly": true }, "pageSize": { "type": "integer", "readOnly": true }, "hasNext": { "type": "boolean", "readOnly": true }, "hasPrevious": { "type": "boolean", "readOnly": true } } }, "ConsentCreateRequest": { "required": [ "consent" ], "type": "object", "properties": { "externalContext": { "description": "Echoed back verbatim in the response; opaque, not validated. Accepts any JSON value (object, string, number, etc.)." }, "consent": { "required": [ "termDefinitionId" ], "type": "object", "properties": { "termDefinitionId": { "type": "string", "description": "The term definition the user is being asked to consent to." }, "externalUserId": { "type": "string", "description": "Optional caller-supplied identifier, stored as-is.", "nullable": true } } } } }, "ConsentEditRequest": { "required": [ "consent", "termDefinition" ], "type": "object", "properties": { "externalContext": { "description": "Echoed back verbatim in the response; opaque, not validated. Accepts any JSON value (object, string, number, etc.)." }, "consent": { "type": "object", "properties": { "environmentData": { "type": "string", "description": "Stored as-is; the service doesn't define or validate its format.", "nullable": true }, "additionalData": { "type": "string", "description": "Stored as-is; the service doesn't define or validate its format.", "nullable": true }, "externalUserId": { "type": "string", "description": "Optional caller-supplied identifier, stored as-is.", "nullable": true }, "accepted": { "type": "boolean", "description": "Whether the user accepted the terms. The server can store this as false regardless of the value sent, if the resent termDefinition.text doesn't match what was originally shown for this session." } } }, "termDefinition": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": "string", "description": "The exact term definition text that was originally shown to the end-user for this session. Required and must be non-empty." } } } } }, "TermDefinitionCreateRequest": { "required": [ "termDefinition" ], "type": "object", "properties": { "externalContext": { "description": "Echoed back verbatim in the response; opaque, not validated. Accepts any JSON value (object, string, number, etc.)." }, "termDefinition": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "text": { "type": "string", "description": "The text/HTML to show end-users during consent. Not enforced as required by this service today, though omitting it will cause consent-creation against this term definition to fail — see the change-summary.", "nullable": true } } } } }, "ConsentCreateResponseData": { "type": "object", "properties": { "consent": { "required": [ "sessionId", "sessionStartDatetime", "sessionExpirationDatetime" ], "type": "object", "properties": { "sessionId": { "type": "string", "readOnly": true }, "sessionStartDatetime": { "type": "string", "format": "date-time", "readOnly": true }, "sessionExpirationDatetime": { "type": "string", "format": "date-time", "readOnly": true } } }, "termDefinition": { "type": "object", "properties": { "text": { "type": "string", "description": "The term text the caller must resend, verbatim, on PUT edit.", "readOnly": true } } } } }, "TermDefinitionCreateResponseData": { "type": "object", "properties": { "termDefinition": { "required": [ "termDefinitionId" ], "type": "object", "properties": { "termDefinitionId": { "type": "string", "readOnly": true } } } } } }, "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "name": "X-Api-Key", "in": "header", "description": "API key, sent as a request header." }, "apiKeyQuery": { "type": "apiKey", "name": "x-api-key", "in": "query", "description": "API key, sent as a query string parameter." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token to authenticate the request." } } } }