{ "openapi": "3.0.3", "info": { "title": "ePost Public API", "description": "REST API for integrating with the ePost communication platform. See developer.epost.ch for guides, authentication and getting started. **Important note:** Effective November 15th, 2024, HTTP/1.0 is no longer supported. Use HTTP/1.1 or HTTP/2.", "version": "0.0.1" }, "servers": [ { "url": "https://api-test.klara-epost.tech", "description": "Test. Self-service onboarding, no charges, nothing is physically posted" }, { "url": "https://api.epost.ch", "description": "Production. Deliveries are chargeable" } ], "tags": [ { "name": "Authentication", "description": "KLARA Authentication flow" }, { "name": "ePost Communication Platform Delivery", "description": "Including identity matching on delivery" }, { "name": "ePost Communication Platform Preview Services", "description": "Offers preview of the delivery channels and prices without sending any document." }, { "name": "ePost Communication Platform Monitoring", "description": "Monitoring data for deliveries done by oneAPI, independent of the delivery channel." }, { "name": "Standard ePost Digital Letterbox Identity Matching", "description": "Including identity matching with simple responses" }, { "name": "ePost Digital Letterbox Onboarding and Profile Management", "description": "ePost onboarding and profile management" }, { "name": "ePost Digital LetterBox Identity Matching with detailed recipient feedback", "description": "Identity matching with detailed response" }, { "name": "ePost Sign", "description": "Submit documents for electronic signing (SwissSign SES / AES / QES) and track the signing process. Access requires the ePost Sign widget subscription." }, { "name": "ePost Digital Letterbox", "description": "Access and manage your digital letter box via public API" }, { "name": "ePost eArchive", "description": "Operations related to directories of eArchive" } ], "paths": { "/core/latest/tenants": { "post": { "tags": [ "Authentication" ], "summary": "Returns all tenants of a user", "description": "A KLARA user might have multiple tenants. Use this endpoint to get the list of tenants containing tenant id, company id.
The tenant and company id returned by this endpoint can be used to generate tokens to access other endpoints. Use your KLARA username and password OR access-token to get the list of tenants.
", "operationId": "listTenants", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" }, "access_token": { "type": "string" } } }, "encoding": { "access_token": { "style": "form" }, "password": { "style": "form" }, "username": { "style": "form" } } } } }, "responses": { "200": { "description": "Found tenants", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } } } } }, "400": { "description": "Missing parameters

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The user has been disabled

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong when getting list of tenants

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/core/latest/token": { "post": { "tags": [ "Authentication" ], "summary": "Generate tokens to access other KLARA core endpoints", "description": "After obtaining tenant id and company id for the desired tenant, use this endpoint to get the access token for a specific tenant, and refresh token.
A grant_type of password is used for a Password grant, which requires username, password, tenant and company id to produce access token, refresh token from scratch.
A grant_type of refresh_token is used for a Refresh token grant, which is used for acquiring the access token using refresh token.
A grant_type of token_exchange performs an OAuth 2.0 Token Exchange (RFC 8693). Provide subject_token (the raw upstream Bearer token, without the 'Bearer ' prefix) and audience to identify the target token type.
Supported audience values:Note: subject_token must be the raw token value without the 'Bearer ' prefix.", "operationId": "createPublicApiToken", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "default": "", "type": "string" }, "password": { "default": "", "type": "string" }, "grant_type": { "default": "", "type": "string" }, "tenant_id": { "default": "", "type": "string" }, "company_id": { "default": "", "type": "string" }, "refresh_token": { "default": "", "type": "string" }, "subject_token": { "default": "", "type": "string" }, "audience": { "default": "", "type": "string" } } } } } }, "responses": { "200": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAPIToken" } } } }, "400": { "description": "Could not get token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } }, "/core/latest/token/by-microsoft": { "post": { "tags": [ "Authentication" ], "summary": "Exchange Microsoft access token for system token", "description": "Provide a Microsoft access token and tenant id to exchange for a system token.", "operationId": "createPublicApiTokenByMicrosoft", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "microsoft_access_token": { "type": "string" }, "tenant_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessTokenResponse" } } } }, "400": { "description": "Could not get token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Invalid credentials

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Internal server error

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } }, "/epost/deliveries/monitoring": { "get": { "tags": [ "ePost Communication Platform Monitoring" ], "summary": "Get monitoring data for the deliveries.", "operationId": "listDeliveryMonitoringData", "parameters": [ { "name": "delivery-id", "in": "query", "description": "Filter recipient tracking base on the delivery id.
If this parameter is empty, the API will return the records for all deliveries.", "schema": { "format": "int64", "type": "integer" } }, { "name": "limit", "in": "query", "description": "Define the limit of the recipient tracking list that this API returns.
For example, if a sender have 10 recipient tracking in the database, and this limit parameter is 5, and the offset parameter is 0,
then this API will return the list containing the first 5 records
If not set, then default value of 48 is used", "schema": { "format": "int32", "default": 48, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Define which position to start getting recipient tracking list.
For example, if a user have 10 recipient tracking in the database, and this offset parameter is 5,
then this API will return recipient tracking list from the 5th record.
If not set, then default value of 0 is used", "schema": { "format": "int32", "default": 0, "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sorting the list for getting newest (DESC) or oldest (ASC) results.", "schema": { "allOf": [ { "$ref": "#/components/schemas/SortStrategy" }, { "default": "DESCENDING" } ] } } ], "responses": { "200": { "description": "List of recipient tracking was returned", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientTrackingDataResponse" } } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/onboarding": { "post": { "tags": [ "ePost Digital Letterbox Onboarding and Profile Management" ], "summary": "Improves users's onboarding experience and add credentials", "description": "Generate a link or QR code on which interacted/scanned, the actions defined in the request body will be executed.
The response output is decided by the Accept header of the request
If a value of \"text/html\" is entered in the Accept header, a response with \"text/html\" media type is returned containing the URL.
If a value of \"image/png\" is entered in the Accept header, a response with \"image/png\" media type is returned containing the QR code.
Verification score of the credentials Accept value 0 or 50.
Only one credential has verification score in the request body.", "operationId": "createOnboardingQrCode", "parameters": [ { "name": "encrypt-token", "in": "query", "description": "Indicate that if the encryption is required for the token part of the response URL.
Should be true when the token payload contains recipient's credentials.", "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Onboarding" } } }, "required": true }, "responses": { "201": { "description": "QR code or Link generated successfully.", "content": { "image/png, application/json": {}, "text/html;charset=UTF-8, application/json": { "example": "https://api.klara.tech/eletter-qr?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhZGQtY3JlZGVudGlhbHMiOnsiMmZjYjRmNmEtZjI4ZC00ZTlmLTk2MGQtYTZlNGM3NWViYmFmLm15LXByb3BlcnR5I\njoiMzcuMTI4NDM0NS0xMjIyMjEifSwibWF0Y2gtY3JlZGVudGlhbHMiOnsiZW1haWwiOiJqb2huLmRvZUBrbGFyYS50ZWNoIiwiZmlyc3ROYW1lIjoiSm9obiIsImxhc3ROYW1lIjoiRG9lIiwic3RyZWV0IjoiTWFpbiBTdHJlZXQiLC\nJob3VzZU51bWJlciI6IjciLCJ6aXAiOiI4MDAwIiwiY2l0eSI6Ilp1cmljaCJ9LCJpc3MiOiJodHRwczovL2tsYXJhLmNoIiwiZXhwIjo0MTAyMzU4NDAwLCJpYXQiOjE2MzcxMjM5NDksImp0aSI6ImJhOTc0N2Q0LWIwZGUtNGRjZC0\n4N2E4LTRlZjIyNDJiOGMxNCJ9.Cpx4uWWj9GDd0ZjKcqpJuMVRDaLP8vHdNigRQXFZPdH68RnX9WNCedTcPTK0kU6MAKTutLFhWk-TSxKrJlVe7oRk4jnlzXgy-05UNKMYAeNPHzDakAS305SsIlatcSeT1nRtUECoZWQ5BIiYEAA6qdQ\n392bSRlbnsgXxDMvTfzI1toYymfS12T3YjoZgfAr4TZM6bYNn8WCgBeL0TQW_olaedo2qoYwzhuv1Q6Qm3U7Cq-hO5hZFtHHU1LXTLOVauU9OMAcPwb7nMoqYI3djLp9YVMIVQvbz2Zu5Ct0_DW-ve4RrgpjWjqwbi6XWr3eKz-cTS29r\nQ2Kvocdde93DVQ" } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/preview/delivery-channels": { "post": { "tags": [ "ePost Communication Platform Preview Services" ], "summary": "Creates a preview of all the available delivery channels without delivering any document.", "description": "

Delivery size limit: 2GB

Each document size (binary + metadata) limit: 200MB

", "operationId": "createDeliveryChannelPreview", "parameters": [ { "name": "preview-option", "in": "query", "description": "Specify should include 1st or all channels in the result.
Acceptable values:
ALL_AVAILABLE_CHANNELS include all channels in result
FIRST_AVAILABLE_CHANNEL include only first channel in result


ALL_AVAILABLE_CHANNELS is chosen by default", "schema": { "allOf": [ { "$ref": "#/components/schemas/PreviewOption" }, { "default": "ALL_AVAILABLE_CHANNELS" } ] } } ], "requestBody": { "description": "Preview delivery's metadata", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OneApiPreviewRequest" }, "encoding": { "files": { "contentType": "application/octet-stream" } } } }, "required": true }, "responses": { "201": { "description": "Delivery preview created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponseV2" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "415": { "description": "Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/preview/delivery-channels/{preview-id}/status": { "get": { "tags": [ "ePost Communication Platform Preview Services" ], "summary": "Get delivery channel preview status.", "operationId": "getDeliveryChannelPreviewStatus", "parameters": [ { "name": "preview-id", "in": "path", "description": "The id of the preview", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDeliveryChannelResponse" } } } }, "400": { "description": "Preview id is invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/preview/delivery-prices": { "post": { "tags": [ "ePost Communication Platform Preview Services" ], "summary": "Creates a preview of all the available delivery channels without delivering any document.", "description": "

Delivery size limit: 2GB

Each document size (binary + metadata) limit: 200MB

", "operationId": "createDeliveryPricePreview", "parameters": [ { "name": "preview-option", "in": "query", "description": "Specify should include 1st or all channels in the result.
Acceptable values:
ALL_AVAILABLE_CHANNELS include all channels in result
FIRST_AVAILABLE_CHANNEL include only first channel in result


ALL_AVAILABLE_CHANNELS is chosen by default", "schema": { "allOf": [ { "$ref": "#/components/schemas/PreviewOption" }, { "default": "ALL_AVAILABLE_CHANNELS" } ] } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PreviewDeliveryRequestV2" }, "encoding": { "files": { "contentType": "application/octet-stream" } } } } }, "responses": { "201": { "description": "Delivery pricing preview created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponseV2" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "415": { "description": "Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/preview/delivery-prices/{preview-id}/status": { "get": { "tags": [ "ePost Communication Platform Preview Services" ], "summary": "Get delivery pricing preview status.", "operationId": "getDeliveryPricePreviewStatus", "parameters": [ { "name": "preview-id", "in": "path", "description": "The id of the preview", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDeliveryPricingResponse" } } } }, "400": { "description": "Preview id is invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Preview id is not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/billing-allowlist": { "get": { "tags": [ "ePost Sign" ], "summary": "List the calling company's billing allowlist.", "description": "Returns the individual ePost users the calling company has authorised to charge a signing request to it. Only reachable for a COMPANY tenant managing its own allowlist; an entry existing here IS the authorization — there is no separate company role to hold.", "operationId": "listBillingAllowlist", "responses": { "200": { "description": "The company's current allowlist entries (possibly empty).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAllowlistEntry" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or the calling tenant is not a COMPANY tenant.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] }, "post": { "tags": [ "ePost Sign" ], "summary": "Authorise an individual ePost user to bill signing requests to the calling company.", "description": "Adds email to the calling company's billing allowlist. The email must resolve to exactly one existing ePost user holding an INDIVIDUAL account. Idempotent: re-adding an email already on the allowlist is a no-op and returns the existing entry. Only reachable for a COMPANY tenant managing its own allowlist.", "operationId": "addBillingAllowlistEntry", "requestBody": { "description": "The individual ePost user's email to authorise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAllowlistAddRequest" } } }, "required": true }, "responses": { "201": { "description": "Entry authorised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAllowlistEntry" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or the calling tenant is not a COMPANY tenant.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No ePost user exists with the given email.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "The email matches more than one ePost account (ambiguous), or the request body failed validation.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/billing-allowlist/{entry-id}": { "delete": { "tags": [ "ePost Sign" ], "summary": "Remove an entry from the calling company's billing allowlist.", "description": "Revokes the authorization: the referenced individual ePost user may no longer charge a signing request to the calling company. Does not affect already-submitted signing processes — billToCompanyTenantId is fixed on the process at creation and never re-checked. Only reachable for a COMPANY tenant managing its own allowlist.", "operationId": "removeBillingAllowlistEntry", "parameters": [ { "name": "entry-id", "in": "path", "description": "Server-assigned unique identifier of the allowlist entry to remove, as returned by GET /signing/billing-allowlist or POST /signing/billing-allowlist.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" } } ], "responses": { "204": { "description": "Entry removed." }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or the calling tenant is not a COMPANY tenant.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "No such entry exists for the calling company.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/billing-companies": { "get": { "tags": [ "ePost Sign" ], "summary": "List companies the authenticated user may bill a signing to.", "description": "Returns the companies the authenticated user is allowed to charge a signing request to — i.e. where the user holds the DOCUMENT_SIGN_BILLING company role in the KLARA web client role system. Used by the UI to render the selection. A user can hold the role in several companies. The returned companyTenantId values are valid inputs for billToCompanyTenantId on POST /signing/processes. luz-documentSign only checks the role and holds no own mapping; revoking the role later does not affect already-submitted processes.", "operationId": "listSigningBillingCompanies", "responses": { "200": { "description": "Companies the user may bill to.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCompany" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/processes": { "get": { "tags": [ "ePost Sign" ], "summary": "List signing processes of the calling tenant.", "description": "Returns a lightweight page of signing processes belonging to the calling tenant: creator, title, optional description, status, deadline and creation timestamp. Use GET /signing/processes/{processId} for the full view. Access requires the ePost Sign widget subscription.", "operationId": "listSigningProcesses", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items per page. Defaults to 25, capped at 200.", "schema": { "default": "25", "maximum": 200, "type": "integer", "example": 25 } }, { "name": "offset", "in": "query", "description": "Number of items to skip from the start of the result set. Defaults to 0. Page (zero-based) n is offset = n * limit; the total item count is returned as total in the response.", "schema": { "default": "0", "minimum": 0, "type": "integer", "example": 0 } }, { "name": "status", "in": "query", "description": "Optional filter on lifecycle status. Allowed values: CREATED, IN_PROGRESS, COMPLETED, EXPIRED, CANCELLED. If omitted, all processes are returned.", "schema": { "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "EXPIRED", "CANCELLED" ], "type": "string", "example": "IN_PROGRESS" } } ], "responses": { "200": { "description": "A page of signing processes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningProcessListResponse" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] }, "post": { "tags": [ "ePost Sign" ], "summary": "Submit a document for signing and create a signing process.", "description": "Submits exactly ONE document to be signed and creates a signing process. Uses multipart/form-data analogous to POST /epost/v2/deliveries: a file part (the PDF) and a metadata JSON part (SigningProcessCreateRequest). The document is stored, a slot per participant is created, and the signature document is made available to each participant in the signing room. Participants without an ePost account receive a forced-onboarding email when forceOnboarding = true AND the credential is an email address (onboarded users can complete only SES). Returns the created process id and its initial status; full details via GET /signing/processes/{processId}. Access requires the ePost Sign widget subscription. Billing a signing to a company requires the DOCUMENT_SIGN_BILLING company role in the KLARA web client role system on the paying company.", "operationId": "createSigningProcess", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Client-generated key that prevents duplicate process creation on retries. Optional: if omitted, retries may create a duplicate process. Same key + same payload returns the original result; same key + different payload → HTTP 409.", "schema": { "type": "string", "example": "d3f4c2b1-9a8b-4c8b-8a5f-7c8b9a1e2d34" } } ], "requestBody": { "description": "Multipart body with exactly two parts:

How to fill metadata:
", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SigningProcessMultipartForm" }, "encoding": { "file": { "contentType": "application/octet-stream" }, "metadata": { "contentType": "application/json" } } } }, "required": true }, "responses": { "202": { "description": "Signing process accepted and created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningProcessCreated" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or caller lacks the DOCUMENT_SIGN_BILLING role on the requested billing company.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "411": { "description": "Content-Length header missing, blank, malformed or negative (chunked transfer encoding is not supported on this endpoint).

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "413": { "description": "Request body exceeds the 200 MB upload ceiling.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Validation failed on the metadata part.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/processes/{processId}": { "get": { "tags": [ "ePost Sign" ], "summary": "Get a signing process — submitted data plus current signing status.", "description": "Returns the data submitted on POST plus the signing status: who has already signed and who has not. The name shown is the one used within the signing process / signature itself — per CISO, no additional profile data is resolved from ePost. Deliberately NOT returned: the full unhashedCredentials (personal-data protection) and the document payload (use GET /signing/processes/{processId}/document).", "operationId": "getSigningProcess", "parameters": [ { "name": "processId", "in": "path", "description": "Server-assigned unique identifier of the signing process.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" } } ], "responses": { "200": { "description": "Current state of the signing process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningProcess" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] }, "patch": { "tags": [ "ePost Sign" ], "summary": "Update a running signing process (ADMIN-only).", "description": "ADMIN-only update of a running signing process. Callable by the process creator or by any active participant that holds the ADMIN role. All fields on the body are optional; only the fields the caller wishes to change need to be sent. Fields set to null are treated as "no change".

Editable fields: title, description, deadline (must be strictly in the future), documentHandling.allowPrint / documentHandling.allowSave. Field-level diffing is applied and an audit trail entry (PROCESS_UPDATED) is written only when at least one value actually changed.

Locked at creation (never patchable through this endpoint): signatureType, mode, participants (participants have their own PATCH endpoint), forceOnboarding, billToCompanyTenantId.

Lifecycle: only status = CANCELLED is accepted — deactivates the process (SwissSign signaturesCancelProcessing), records a PROCESS_CANCELLED audit trail entry, schedules the process for deletion, delivers the partially-signed document to RECEIVER participants and notifies SIGNER / ADMIN participants. Any other status value is rejected with HTTP 400. Updates against a process in COMPLETED, CANCELLED or EXPIRED are rejected with HTTP 409. Callers that are not an ADMIN participant of this process receive HTTP 404 (the existence of the process is not disclosed). Access requires the ePost Sign widget subscription.", "operationId": "updateSigningProcess", "parameters": [ { "name": "processId", "in": "path", "description": "Server-assigned unique identifier of the signing process.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" } } ], "requestBody": { "description": "Partial update. Send only the fields to change. Field-level diffing is applied downstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningProcessUpdate" } } }, "required": true }, "responses": { "200": { "description": "Updated signing process.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningProcess" } } } }, "400": { "description": "Body invalid, or status supplied but not equal to CANCELLED.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or caller is not an ADMIN of this process.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Process is in a terminal status (COMPLETED, CANCELLED or EXPIRED) and cannot be updated.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Validation failed on the request body (e.g. deadline not strictly in the future).

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/processes/{processId}/document": { "get": { "tags": [ "ePost Sign" ], "summary": "Download the final signed document.", "description": "Returns the FINAL signed PDF once the process is COMPLETED. While signing is ongoing the document is only viewable within the signing room and is NOT exposed here. Access is controlled per tenant.", "operationId": "getSignedDocument", "parameters": [ { "name": "processId", "in": "path", "description": "Server-assigned unique identifier of the signing process.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" } } ], "responses": { "200": { "description": "The final signed PDF document.", "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Process not yet COMPLETED — the signed document is not available.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/signing/processes/{processId}/participants/{participantId}": { "patch": { "tags": [ "ePost Sign" ], "summary": "Update a participant of a running signing process (ADMIN-only).", "description": "ADMIN-only update of a single participant. Callable by the process creator or by any active participant that holds the ADMIN role. Only reachable while the participant is PENDING or FORCED_ONBOARDING — once the participant has SIGNED, REJECTED, EXPIRED or has already been REMOVED, the request is rejected with HTTP 409. All fields on the body are optional; field-level diffing is applied and an audit trail entry (PARTICIPANT_UPDATED) is written only when at least one value actually changed.

Removal: send status = REMOVED to remove the participant from the process. Records a PARTICIPANT_REMOVED audit trail entry. Any other status value is rejected with HTTP 400.

Credential-change re-matching: changing any credential field — hashedPrimaryCredential, hashedPrimaryValue, derivedHashedCredentials, derivedHashedValue, unhashedCredentials, or allCredentialShouldMatch — re-runs tenant-directory matching for this participant slot. If the resolved recipient changes, the previously-resolved tenant is remembered (so their subsequent sign attempts are rejected with REMOVED_BY_SENDER) and the initial signing notification is re-delivered to the newly resolved recipient. The previous recipient's letterbox entry is intentionally NOT withdrawn. If the new credential matches multiple accounts the request is rejected with HTTP 422.

Last-ADMIN protection: removing the last ADMIN — or stripping the ADMIN role from the last ADMIN by supplying a roles list that does not contain ADMIN — is rejected with HTTP 409; the participant is left unchanged. Callers that are not an ADMIN participant of this process receive HTTP 404 (the existence of the process is not disclosed). Access requires the ePost Sign widget subscription.", "operationId": "updateSigningParticipant", "parameters": [ { "name": "participantId", "in": "path", "description": "Process-local participant id (stable, also while the participant is unresolved). Matches ParticipantStatus.internalTrackingId from the GET view.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "b4a9b3f1-c8d0-4e2a-b5f6-b7c8d9e0a1b2" } }, { "name": "processId", "in": "path", "description": "Server-assigned unique identifier of the signing process.", "required": true, "schema": { "format": "uuid", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" } } ], "requestBody": { "description": "Partial update. Send only the fields to change. Field-level diffing is applied downstream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantUpdate" } } }, "required": true }, "responses": { "200": { "description": "Updated participant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantStatus" } } } }, "400": { "description": "Body invalid, or status supplied but not equal to REMOVED.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "ePost Sign widget not subscribed, or caller is not an ADMIN of this process.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Participant is no longer in an editable state (not PENDING / FORCED_ONBOARDING), or the change would leave the process without any ADMIN.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Validation failed on the request body, or a credential change re-matches to multiple accounts.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/archives/directories": { "get": { "tags": [ "ePost eArchive" ], "summary": "Get all folders (branded folders, unbranded folders and subfolders) in the Storage", "operationId": "listArchiveFolders", "responses": { "200": { "description": "Retrieve folders successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Directory" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/archives/letters": { "get": { "tags": [ "ePost eArchive" ], "summary": "Get letters in root storage or in a specific folder.", "operationId": "listArchiveLetters", "parameters": [ { "name": "directory-id", "in": "query", "description": "The ID of the folder to get for letters. If empty, it will get letters in the root storage.", "required": false, "schema": { "type": "string" }, "example": "637b04533b81694d793c2159" }, { "name": "limit", "in": "query", "description": "Define the limit of the letter list that this API returns.
For example, if a user have 20 letters in their inbox, and this limit parameter is 5, and the offset parameter is 0,
then this API will return letter list containing the first 5 letters
If not set, then default value of 48 is used", "schema": { "format": "int32", "default": "48", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Define which position to start getting letter list.
For example, if a user have 20 letters in their inbox, and this offset parameter is 5,
then this API will return letter list from the 5th letter.
If not set, then default value of 0 is used", "schema": { "format": "int32", "default": "0", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "Retrieve letters successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Letter" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/archives/upload": { "post": { "tags": [ "ePost eArchive" ], "summary": "Uploads a document to the ePost archive of the authenticated tenant together with its metadata.", "description": "

Uploads a document to the ePost archive of the authenticated tenant together with its metadata.

The request contains the binary file and document metadata. After a successful upload, the document is stored in the tenant's ePost archive and can be accessed through the archive.

", "operationId": "uploadArchiveDocument", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ArchiveUploadRequest" }, "encoding": { "file": { "contentType": "application/octet-stream" }, "directoryIds": { "contentType": "text/plain", "style": "form", "explode": true } } } }, "required": true }, "responses": { "201": { "description": "Document uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveUploadResponse" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "411": { "description": "Length required — the request did not advertise a numeric, non-negative Content-Length. Chunked transfer encoding is not supported on this endpoint.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "413": { "description": "Request entity too large — payload exceeds the 1GB ceiling.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "415": { "description": "Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/deliveries": { "post": { "tags": [ "ePost Communication Platform Delivery" ], "summary": "Creates a delivery and send documents for a sender.", "description": "

Delivery size limit: 2GB

Each document size (binary + metadata) limit: 200MB

Total number of documents per delivery limit: 2,000

Total number of recipients per delivery limit: 2,000

", "operationId": "createDelivery", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DeliveryRequestV2" }, "encoding": { "files": { "contentType": "application/octet-stream" } } } } }, "responses": { "201": { "description": "Delivery created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponseV2" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "415": { "description": "Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/deliveries/{delivery-id}/status": { "get": { "tags": [ "ePost Communication Platform Delivery" ], "summary": "Get Delivery status.", "operationId": "getDeliveryStatus", "parameters": [ { "name": "delivery-id", "in": "path", "description": "The id of the delivery", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryStatusResponseV2" } } } }, "400": { "description": "Delivery id is invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/iletters/{iletter-id}/response-files/{response-file-id}/content": { "get": { "tags": [ "ePost Communication Platform Delivery" ], "summary": "Download a file a recipient uploaded as an answer to an iLetter.", "description": "Only the sender tenant of the iLetter can read its response files. The content is available for 90 days after the answer was submitted; after that the call returns 410 with the file metadata.", "operationId": "getILetterResponseFileContent", "parameters": [ { "name": "iletter-id", "in": "path", "description": "Id of the iLetter, as sent in the letterId field of the answer webhook.", "required": true, "schema": { "type": "string", "example": "65e7e536aae6544ca8dce48f" } }, { "name": "response-file-id", "in": "path", "description": "Id of the response file, as sent in the files field of the answer webhook.", "required": true, "schema": { "type": "string", "example": "66f1a2b3c4d5e6f708192a3b" } } ], "responses": { "200": { "description": "The file content. Content-Type and Content-Disposition carry the original type and file name.", "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "object" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "410": { "description": "The file content was removed: its 90-day retention ended, or the answer was replaced or deleted.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseFileGoneResponse" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get letters of current user.", "operationId": "listLetters", "parameters": [ { "name": "from-date", "in": "query", "description": "Filter letters with the send date (yyyy-MM-dd). Letters were sent since 'from-date' value will be return.
Both from-date and to-date need to be specified to filter letters within a time period.
Example: 2021-10-01", "schema": { "type": "string" } }, { "name": "is-business-tenant", "in": "query", "schema": { "type": "boolean" } }, { "name": "letter-folder", "in": "query", "description": "Filter letters in specific folder
Acceptable values:
INBOX_FOLDER for inbox letters
SENT_FOLDER for outbox letters


INBOX_FOLDER is chosen by default", "schema": { "allOf": [ { "$ref": "#/components/schemas/LetterFolder" }, { "default": "INBOX_FOLDER" } ] } }, { "name": "letter-types", "in": "query", "description": "Filter letters with this media type
Acceptable values:
CLASSIC_LETTER for classic letters
SMART_LETTER for smart letters
SMART_LETTER_ANSWER for smart letter answers
SIMPLE_SHORT_MESSAGE for simple short message
INCAMAIL for IncaMail
SECURESEND for SecureSend

CLASSIC_LETTER is chosen by default", "required": true, "schema": { "default": "CLASSIC_LETTER", "type": "array", "items": { "$ref": "#/components/schemas/LetterType" } } }, { "name": "limit", "in": "query", "description": "Define the limit of the letter list that this API returns.
For example, if a user have 20 letters in their inbox, and this limit parameter is 5, and the offset parameter is 0,
then this API will return letter list containing the first 5 letters
If not set, then default value of 48 is used", "schema": { "format": "int32", "default": "48", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Define which position to start getting letter list.
For example, if a user have 20 letters in their inbox, and this offset parameter is 5,
then this API will return letter list from the 5th letter.
If not set, then default value of 0 is used", "schema": { "format": "int32", "default": "0", "minimum": 0, "type": "integer" } }, { "name": "read-status", "in": "query", "description": "Filter letters with read status
Acceptable values:
READ for read letters
UNREAD for unread letters
ALL for all letters
ALL is chosen by default", "schema": { "allOf": [ { "$ref": "#/components/schemas/LetterReadStatusFilterParam" }, { "default": "ALL" } ] } }, { "name": "senderCaseId", "in": "query", "description": "Filter letters with sender case id", "schema": { "type": "string" } }, { "name": "senderEndToEndId", "in": "query", "description": "Filter letters with sender end to end id", "schema": { "type": "string" } }, { "name": "senderParticipantId", "in": "query", "description": "Filter letters with sender participant id", "schema": { "type": "string" } }, { "name": "senderUserId", "in": "query", "description": "Filter letters with sender user id", "schema": { "type": "string" } }, { "name": "to-date", "in": "query", "description": "Filter letters with the send date (yyyy-MM-dd). Letters were sent before 'to-date' value will be return
Both from-date and to-date need to be specified to filter letters within a time period.
Example: 2021-10-01", "schema": { "type": "string" } }, { "name": "with-reminder", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieve letters successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Letter" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get a letter of current user with given id.", "operationId": "getLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "The id of the letter", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "Retrieve letter successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Letter" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] }, "delete": { "tags": [ "ePost Digital Letterbox" ], "summary": "Delete letter", "description": "Delete letter by letter id", "operationId": "deleteLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "Id of the letter needed to be deleted", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "204": { "description": "Successful operation" }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/accept": { "post": { "tags": [ "ePost Digital Letterbox" ], "summary": "Accept a letter by id.", "operationId": "acceptLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "Id of the letter to accept", "required": true, "schema": { "type": "string", "example": "656d961f852ea03ec718ab5d" } } ], "responses": { "204": { "description": "Successful operation" }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/archive": { "patch": { "tags": [ "ePost Digital Letterbox" ], "summary": "Archive a letter from Letterbox to the root or to a specific folder in Storage.", "description": "If the letter is already archived and in the Storage, the exception will be thrown.", "operationId": "archiveLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "The ID of the letter to archive", "required": true, "schema": { "type": "string" }, "example": "6461ba8d85f2cb38c91b82d4" }, { "name": "destination-directory-id", "in": "query", "description": "Destination folder id. If empty, the letter will be stored in the root storage.", "required": false, "schema": { "type": "string" }, "example": "637b04533b81694d793c2159" } ], "responses": { "204": { "description": "Store letter successfully." }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/content": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get the content of a letter with given id.", "operationId": "getLetterContent", "parameters": [ { "name": "letter-id", "in": "path", "description": "The id of the letter", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream, application/json": { "schema": { "format": "byte", "type": "object" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/reject": { "post": { "tags": [ "ePost Digital Letterbox" ], "summary": "Reject a letter by id.", "operationId": "rejectLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "Id of the letter to reject", "required": true, "schema": { "type": "string", "example": "656d961f852ea03ec718ab5d" } } ], "responses": { "204": { "description": "Successful operation" }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/restore": { "post": { "tags": [ "ePost Digital Letterbox" ], "summary": "Restore a letter being deleted from inbox by letter id.", "description": "Recover letter by letter id", "operationId": "restoreLetter", "parameters": [ { "name": "letter-id", "in": "path", "description": "Id of the letter needed to be restored", "required": true, "schema": { "type": "string", "example": "656d961f852ea03ec718ab5d" } } ], "responses": { "204": { "description": "Successful operation" }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/{letter-id}/thumbnail": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get thumbnail of a letter with given id.", "description": "Thumbnail is returned as an stream of bytes with JPEG image format. Default image size is 90x128 pixels.", "operationId": "getLetterThumbnail", "parameters": [ { "name": "letter-id", "in": "path", "description": "Id of the letter to get the thumbnail for.", "required": true, "schema": { "type": "string", "example": "65e7e536aae6544ca8dce48f" } } ], "responses": { "200": { "description": "Retrieve the letter thumbnail successfully.", "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "object" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/deleted": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get deleted letters and its remaining days to be permanently deleted.", "operationId": "listDeletedLetters", "parameters": [ { "name": "limit", "in": "query", "description": "Define the limit of the letter list that this API returns.
For example, if a user have 20 letters in their inbox, and this limit parameter is 5, and the offset parameter is 0,
then this API will return letter list containing the first 5 letters
If not set, then default value of 48 is used", "schema": { "format": "int32", "default": "48", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Define which position to start getting letter list.
For example, if a user have 20 letters in their inbox, and this offset parameter is 5,
then this API will return letter list from the 5th letter.
If not set, then default value of 0 is used", "schema": { "format": "int32", "default": "0", "minimum": 0, "type": "integer" } }, { "name": "sender-participant-id", "in": "query", "description": "Filter count letters from a specific sender by their participant id. Example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve deleted letters successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Letter" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/inbox/count": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Get the inbox unread letters count of the current user.", "operationId": "getInboxUnreadCount", "parameters": [ { "name": "sender-participant-id", "in": "query", "description": "Filter count letters from a specific sender by their participant id. Example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve letters count successfully.", "content": { "application/json": { "schema": { "format": "int32", "type": "integer" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/read": { "post": { "tags": [ "ePost Digital Letterbox" ], "summary": "Update the READ/UNREAD status for selected letters. The default status is READ.", "operationId": "updateLettersReadStatus", "requestBody": { "description": "Letters marked as READ/UNREAD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadLetters" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "processed_count": { "format": "int32", "type": "integer" }, "skipped_count": { "format": "int32", "type": "integer" }, "failed_count": { "format": "int32", "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LetterReadUnreadResult" } } } } } } }, "207": { "description": "Partial success", "content": { "application/json": { "schema": { "type": "object", "properties": { "processed_count": { "format": "int32", "type": "integer" }, "skipped_count": { "format": "int32", "type": "integer" }, "failed_count": { "format": "int32", "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LetterReadUnreadResult" } } } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/letters/search": { "get": { "tags": [ "ePost Digital Letterbox" ], "summary": "Search for letters using keywords that can be found in the letter's title, sender's name, or content.", "operationId": "searchLetters", "parameters": [ { "name": "limit", "in": "query", "description": "Define the limit of the letter list that this API returns.
For example, if a user have 20 letters in their inbox, and this limit parameter is 5, and the offset parameter is 0,
then this API will return letter list containing the first 5 letters
If not set, then default value of 48 is used", "schema": { "format": "int32", "default": "48", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "name": "offset", "in": "query", "description": "Define which position to start getting letter list.
For example, if a user have 20 letters in their inbox, and this offset parameter is 5,
then this API will return letter list from the 5th letter.
If not set, then default value of 0 is used", "schema": { "format": "int32", "default": "0", "minimum": 0, "type": "integer" } }, { "name": "search-location", "in": "query", "description": "Search letters with location
Acceptable values:
ALL for all location, is chosen by default
INBOX for inbox folder
STORAGE for letters in storage
TRASH for deleted letters in trash folder", "required": false, "schema": { "default": "ALL", "type": "string", "example": "ALL" } }, { "name": "sender-participant-id", "in": "query", "description": "Sender participant id of letters (Optional), This unique ID can be used to reference the sender", "required": false, "schema": { "type": "string" } }, { "name": "value", "in": "query", "description": "Key words to search letters, it can be sender name, letter title, text content, etc.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve letters successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Letter" } } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "500": { "description": "Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/matching-runs": { "post": { "tags": [ "ePost Digital LetterBox Identity Matching with detailed recipient feedback" ], "summary": "Identity matching process.", "description": "Send metadata of your customers for matching them with ePost users. There is the possibility to hash the metadata before sending it. It isn't mandatory to send all data for identity matching, but the sent data has to be unique in it's combination.

The access to this API request is restricted, because it returns detailed information about whether a credential has been matched or not. Against a fee you are able to use this detailed identity matching API. Please get in touch with an administrator to get more information.", "operationId": "createMatchingRun", "requestBody": { "description": "recipient's info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInfo" } } }, "required": true }, "responses": { "202": { "description": "Request accepted", "headers": { "Location": { "description": "Location to the endpoint of getting status for this request.", "style": "simple", "schema": { "type": "string", "example": "https://api.klara.ch/epost/v2/matching-runs/processing/1" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchingRunResultLocation" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/matching-runs/{matching-run-id}": { "get": { "tags": [ "ePost Digital LetterBox Identity Matching with detailed recipient feedback" ], "summary": "Get all of matching results from matching run id.", "operationId": "getMatchingRunResult", "parameters": [ { "name": "matching-run-id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve successfully. The matching status could be processing or finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchingRunProcessResponse" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/matching-runs/processing/{matching-run-id}": { "get": { "tags": [ "ePost Digital LetterBox Identity Matching with detailed recipient feedback" ], "summary": "Checking matching process.", "operationId": "getMatchingRunProgress", "parameters": [ { "name": "matching-run-id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching process is processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchingRunProcessResponse" } } } }, "303": { "description": "Finished matching process. Then auto redirect to get matching result api /matching-runs/{matching-run-id} and return matching result." }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/matchings": { "post": { "tags": [ "ePost Digital LetterBox Identity Matching with detailed recipient feedback" ], "summary": "Identity matching process.", "description": "Send metadata of your customers for matching them with ePost users. The limit size of the metadata is 5 There is the possibility to hash the metadata before sending it. It isn't mandatory to send all data for identity matching, but the sent data has to be unique in it's combination.

The access to this API request is restricted, because it returns detailed information about whether a credential has been matched or not. Against a fee you are able to use this detailed identity matching API. Please get in touch with an administrator to get more information.", "operationId": "matchRecipients", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInfo" } } } }, "responses": { "200": { "description": "Get matched users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MatchingResponse" } } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/recipients": { "get": { "tags": [ "ePost Digital LetterBox Identity Matching with detailed recipient feedback" ], "summary": "Get hashed metadata from ePost users for matching lookup.", "operationId": "listMatchingLookupRecipients", "parameters": [ { "name": "limit", "in": "query", "schema": { "format": "int32", "default": 100, "maximum": 1000, "type": "integer" } }, { "name": "min-timestamp", "in": "query", "description": "The minimum timestamp that sender want to filter the result. Ex: 2021-04-14T01:27:05.382Z", "schema": { "default": "2021-04-14T01:27:05.382Z", "type": "string" } }, { "name": "minimum-level-of-trust", "in": "query", "description": "The minimum LOT that sender want to filter the result. Ex: SILVER", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/LevelOfTrust" }, { "default": "BRONZE", "nullable": false } ] } }, { "name": "offset", "in": "query", "schema": { "format": "int32", "default": 0, "type": "integer" } }, { "name": "primary-credential", "in": "query", "description": "The primary value that sender want to get a hashed value. Possible values: email|mobilenumber|postaladdress", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/HashedPrimaryCredentialType" }, { "default": "email", "nullable": false } ] } } ], "responses": { "200": { "description": "Retrieve successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchingLookup" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/standard-matching-runs": { "post": { "tags": [ "Standard ePost Digital Letterbox Identity Matching" ], "summary": "Standard identity matching process.", "description": "Send metadata of your customers for matching them with ePost users. There is the possibility to hash the metadata before sending it. It isn't mandatory to send all data for identity matching, but the sent data has to be unique in it's combination.", "operationId": "createStandardMatchingRun", "requestBody": { "description": "recipient's info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInfo" } } }, "required": true }, "responses": { "202": { "description": "Request accepted", "headers": { "location": { "description": "Location to the endpoint of getting status for this request.", "style": "simple", "schema": { "type": "string", "example": "https://api.klara.ch/epost/v2/standard-matching-runs/processing/1" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/standard-matching-runs/{matching-run-id}": { "get": { "tags": [ "Standard ePost Digital Letterbox Identity Matching" ], "summary": "Get all of matching results from matching run id.", "operationId": "getStandardMatchingRunResult", "parameters": [ { "name": "matching-run-id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve successfully. The matching status could be processing or finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMatchingRunProcessResponse" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/standard-matching-runs/processing/{matching-run-id}": { "get": { "tags": [ "Standard ePost Digital Letterbox Identity Matching" ], "summary": "Checking matching process.", "operationId": "getStandardMatchingRunProgress", "parameters": [ { "name": "matching-run-id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching process is processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMatchingRunProcessResponse" } } } }, "303": { "description": "Finished matching process. Then auto redirect to get matching result api /matching-runs/{matching-run-id} and return matching result." }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Resource not found

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/standard-matchings": { "post": { "tags": [ "Standard ePost Digital Letterbox Identity Matching" ], "summary": "Identity matching process. Standard version just return the user's basic information.", "description": "Send metadata of your customers for matching them with ePost users. The limit size of the metadata is 5 There is the possibility to hash the metadata before sending it. It isn't mandatory to send all data for identity matching, but the sent data has to be unique in it's combination.", "operationId": "matchStandardRecipients", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientInfo" } } } }, "responses": { "200": { "description": "Get matched users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StandardMatchingResponse" } } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/epost/v2/synchronous-deliveries": { "post": { "tags": [ "ePost Communication Platform Delivery" ], "summary": "Creates a synchronous delivery to send documents for a sender and receive status immediately.", "description": "

Delivery size limit: 2GB

Each document size (binary + metadata) limit: 200MB

Total number of documents per delivery limit: 1500

Total number of recipients per delivery limit: 1500

", "operationId": "createSynchronousDelivery", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DeliveryRequestV21" }, "encoding": { "files": { "contentType": "application/octet-stream" } } } } }, "responses": { "200": { "description": "Status of the delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryStatusResponseV2" } } } }, "400": { "description": "Data invalid

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "415": { "description": "Unsupported Media Type

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "429": { "description": "API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ] } } }, "components": { "schemas": { "AccessTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "format": "int64", "type": "integer" }, "refresh_expires_in": { "format": "int64", "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" }, "id_token": { "type": "string" }, "not-before-policy": { "format": "int32", "type": "integer" }, "session_state": { "type": "string" }, "otherClaims": { "type": "object", "additionalProperties": { "type": "object" } } } }, "ActorRef": { "type": "object", "properties": { "pid": { "description": "Internal ePost id of the resolved tenant. null while the tenant cannot yet be resolved (e.g. forced onboarding pending).", "type": "string", "example": "c60d31fa-f335-4957-872a-90b035632081", "nullable": true }, "name": { "description": "Name as used within the signing process / signature itself (verified name applied at signing). null while unresolved.", "type": "string", "example": "Anna Muster", "nullable": true } } }, "AdditionalEmailInfo": { "description": "Contain email and its name", "type": "object", "properties": { "email": { "description": "Email address", "type": "string", "example": "abc@klara.ch", "writeOnly": true }, "name": { "description": "Name of email", "type": "string", "example": "ABC", "writeOnly": true } } }, "ArchiveUploadRequest": { "description": "Single file to archive together with its metadata. Standard / large-file routing is decided automatically by the adapter from the request Content-Length; callers do not need to flag large uploads explicitly.", "type": "object", "properties": { "file": { "allOf": [ { "$ref": "#/components/schemas/BinaryFileV2" }, { "description": "The binary file to upload to the ePost archive.
\nThe file must be provided as part of a multipart/form-data request and must not exceed ≤ 200MB.
\nSupported file types are [ .pdf, .jpg, .png, .gif, .xlsx, .docx, .txt, .rtf]." } ] }, "metadata": { "description": "metadata", "required": [ "fileName", "documentTitle", "documentReferenceDate" ], "type": "object", "properties": { "fileName": { "description": "Original file name (with extension).", "pattern": "\\S", "type": "string", "example": "sample.xlsx", "nullable": false }, "documentTitle": { "description": "Display title shown in eArchive.", "pattern": "\\S", "type": "string", "example": "sample", "nullable": false }, "documentReferenceDate": { "description": "Reference date of the document in ISO local-date format (yyyy-MM-dd).", "pattern": "\\S", "type": "string", "example": "2026-05-06", "nullable": false }, "documentTypes": { "description": "Document types (free-form tags such as invoice, receipt, contract, HR). Defaults to an empty list when omitted.", "type": "array", "items": { "type": "string" }, "example": [] }, "senderName": { "description": "Display name of the sender.", "type": "string", "example": "ABC AG" }, "description": { "description": "Display description shown in eArchive.", "type": "string", "example": "Invoice file" } } }, "directoryIds": { "description": "The IDs of the archive directories in which the uploaded document should be stored.\nAll provided directory IDs must belong to the authenticated tenant. If no directory ID is provided, the document is stored without a directory assignment.", "type": "array", "items": { "type": "string" } } } }, "ArchiveUploadResponse": { "description": "Response returned after a document is successfully archived.", "type": "object", "properties": { "documentId": { "description": "Identifier of the newly archived document.", "type": "string", "example": "6a028c8e3a805659063bde2f" }, "fileName": { "description": "File name of the stored document (post sanitization).", "type": "string", "example": "Invoice_2026_05_08.pdf" }, "documentTitle": { "description": "Display title of the archived document.", "type": "string", "example": "Invoice 2026-05-08" }, "documentReferenceDate": { "description": "Reference date of the document (yyyy-MM-dd).", "type": "string", "example": "2026-05-08" }, "description": { "description": "Display description of the archived document.
\nSourced from the BFF response field documentDescription and renamed here to description so the public API uses one consistent term across request and response.", "type": "string", "example": "Monthly partner export for invoicing reconciliation" }, "directoryIds": { "description": "Directory ids the document is stored in, as resolved by the eArchive backend (after permission checks and root-directory normalization). Omitted when the document is stored at the root.
\nSourced from the BFF response field folderIds and renamed here to directoryIds so the public API uses one consistent term across request and response.", "type": "array", "items": { "type": "string" }, "example": [ "637b04533b81694d793c2159" ] }, "createdBy": { "description": "User identifier (typically email) that created the document.", "type": "string", "example": "kiendong2411@axongroupio.ch" }, "createdDate": { "description": "Creation timestamp in ISO-8601 format (UTC).", "type": "string", "example": "2026-05-12T02:12:30.691Z" }, "updatedBy": { "description": "User identifier (typically email) of the last update. Equal to createdBy on initial upload.", "type": "string", "example": "kiendong2411@axongroupio.ch" }, "updatedDate": { "description": "Last update timestamp in ISO-8601 format (UTC). Equal to createdDate on initial upload.", "type": "string", "example": "2026-05-12T02:12:30.691Z" }, "link": { "allOf": [ { "$ref": "#/components/schemas/ArchiveUploadResponseLink" }, { "description": "Resource link references for the archived document." } ] }, "versionNumber": { "format": "int32", "description": "Monotonically increasing version number of the document. Starts at 1 on initial upload.", "type": "integer", "example": 1 } } }, "ArchiveUploadResponseLink": { "description": "Resource link references for the archived document.", "type": "object", "properties": { "self": { "description": "Self link to the archived document, relative to the eArchive backend ({tenantId}/documents/{documentId}).", "type": "string", "example": "064f1c76-ed3e-4d3d-800b-9195e13edcbe/documents/6a028c8e3a805659063bde2f" } } }, "BaseDeliveryMetadataV2": { "description": "Metadata of one delivery v2 contain list metadata of files.", "type": "object", "properties": { "costCenter": { "description": "In each delivery, you can input the specific department name sending the delivery. In order to see the cost generated by each business unit/department in the invoice. This is an optional field and maximum of 1 value per each delivery is accepted.", "type": "string" }, "fileMetadata": { "description": "List of file's metadata", "type": "array", "items": { "$ref": "#/components/schemas/DocumentMetadataV2" } } } }, "BillingAllowlistAddRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "description": "Email of the individual ePost user to authorise. Must resolve to exactly one existing ePost user holding an INDIVIDUAL account.", "pattern": "\\S", "type": "string", "example": "jane.doe@example.com", "nullable": false } } }, "BillingAllowlistEntry": { "type": "object", "properties": { "id": { "format": "uuid", "description": "Server-assigned unique identifier of this allowlist entry. Pass this value as entry-id on DELETE /signing/billing-allowlist/{entry-id} to remove it.", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" }, "userEmail": { "description": "Email of the individual ePost user authorised to bill signing requests to this company.", "type": "string", "example": "jane.doe@example.com" }, "userParticipantId": { "description": "ePost participantId resolved for userEmail at the time this entry was added.", "type": "string", "example": "c56a24e3-55af-4d96-8cf3-8c127116efc5", "nullable": true }, "createdAt": { "format": "date-time", "description": "Creation timestamp (ISO 8601).", "type": "string", "example": "2026-10-01T10:03:34Z" } } }, "BillingCompany": { "type": "object", "properties": { "companyTenantId": { "description": "Tenant id of the company. Pass this value as billToCompanyTenantId on submission.", "type": "string", "example": "c60d31fa-f335-4957-872a-90b035632081" }, "name": { "description": "Company name — display value only.", "type": "string", "example": "Muster AG" } } }, "BinaryFileV2": { "format": "binary", "description": "A binary file, users can push the binary via API document for testing.
PDF binaries have to be delivered in the format PDF/A.", "type": "string" }, "BusinessStatus": { "enum": [ "RECEIVED", "WAIT_FOR_GROUP", "WAIT_FOR_CONFIRMATION", "CANCELLED_BY_SENDER", "ACCEPTED", "FAILURE", "DELIVERED", "REJECTED_BY_RECIPIENT", "ACCEPTED_BY_RECIPIENT", "CALLED_BY_RECIPIENT", "NOT_CALLED_BY_RECIPIENT", "UNDELIVERABLE" ], "type": "string" }, "BusinessStatusHistory": { "description": "A historical record of a business status change for a delivery.", "type": "object", "properties": { "businessStatus": { "allOf": [ { "$ref": "#/components/schemas/BusinessStatus" }, { "description": "The business status of the delivery at this point in history.", "example": "DELIVERED" } ] }, "changedAt": { "format": "date-time", "description": "The UTC timestamp when the business status changed.", "type": "string", "example": "2023-11-14T22:13:20Z" }, "triggeredByUserFirstName": { "description": "The first name of the user who triggered the status change.", "type": "string", "example": "John" }, "triggeredByUserLastName": { "description": "The last name of the user who triggered the status change.", "type": "string", "example": "Doe" } } }, "DeliveryChannelPreference": { "enum": [ "DIGITAL", "PHYSICAL", "SMS", "AUTO", "EBILL", "EMAIL" ], "type": "string" }, "DeliveryChannelPreview": { "enum": [ "DIGITAL", "PHYSICAL", "SMS", "EBILL", "EMAIL" ], "type": "string" }, "DeliveryMetadataV2": { "description": "Metadata of one delivery v2 contain list metadata of files.", "type": "object", "properties": { "costCenter": { "description": "In each delivery, you can input the specific department name sending the delivery. In order to see the cost generated by each business unit/department in the invoice. This is an optional field and maximum of 1 value per each delivery is accepted.", "type": "string" }, "fileMetadata": { "description": "List of file's metadata", "type": "array", "items": { "$ref": "#/components/schemas/DocumentMetadataV2" } }, "featurePricePlan": { "description": "This value is optional and is used for special pricing agreement between KLARA and the sender customer. For more information, please contact KLARA admin.
\nIf you don't have a value given by KLARA admin team, you can set it to null which will result in standard pricing.", "type": "string" } } }, "DeliveryPreviewStatus": { "enum": [ "PROCESSING", "FINISHED", "ERROR", "EXPIRED" ], "type": "string" }, "DeliveryRequestV2": { "description": "A list of binary file and document metadata.", "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/BinaryFileV2" } }, "largeFile": { "allOf": [ { "$ref": "#/components/schemas/BinaryFileV2" }, { "description": "Only usable for specially activated senders!
\nOnly DIGITAL channel is supported.
\nDelivery (binary + metadata) size limit: 1GB" } ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/DeliveryMetadataV2" }, { "description": "metadata" } ] } } }, "DeliveryRequestV21": { "description": "A list of binary file and document metadata.", "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/BinaryFileV2" } }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/DeliveryMetadataV2" }, { "description": "metadata" } ] } } }, "DeliveryResponseV2": { "description": "A response when do a delivery.", "type": "object", "properties": { "id": { "description": "The id of this delivery after created", "type": "string" } } }, "DeliveryStatus": { "description": "All statuses which a delivery could have", "enum": [ "CREATED", "PROCESSING", "DELIVERED", "DELIVERED_WITH_ERROR", "ERROR" ], "type": "string" }, "DeliveryStatusResponseV2": { "description": "Response of status v2 endpoint", "type": "object", "properties": { "deliveryId": { "description": "Delivery's id", "type": "string" }, "status": { "allOf": [ { "$ref": "#/components/schemas/DeliveryStatus" }, { "description": "Status of the delivery: " } ] }, "document": { "allOf": [ { "$ref": "#/components/schemas/DeliveryStatusResponseV2.Document" }, { "description": "Document information" } ] } } }, "DeliveryStatusResponseV2.DeliveredDetail": { "description": "Delivered delivery information for a single document of recipient", "type": "object", "properties": { "deliveryChannel": { "allOf": [ { "$ref": "#/components/schemas/DeliveryChannelPreference" }, { "description": "Delivery channel" } ] }, "participantId": { "description": "The participant id of the user that was delivered", "type": "string" }, "senderUserId": { "description": "User id was defined by sender for each recipient", "type": "string" }, "trackingNumber": { "description": "Tracking number of the document that was delivered. It's only relevant for the postage REGISTERED and APLUS.", "type": "string" } } }, "DeliveryStatusResponseV2.DeliveredDocument": { "description": "Documents that succeeded to be delivered", "type": "object", "properties": { "senderEndToEndId": { "description": "End to end id defined by sender for each document", "type": "string" }, "documentTitle": { "description": "Document title", "type": "string" }, "detail": { "description": "List of recipient successfully received the document. This list is only returned when displayDeliveredDocuments is set to true when sending the delivery.", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryStatusResponseV2.DeliveredDetail" } } } }, "DeliveryStatusResponseV2.DeliveredRecipientStatistic": { "description": "The number of recipients have been already delivered to", "type": "object", "properties": { "recipientsDeliveredDigitally": { "format": "int32", "description": "Number of recipients that have been delivered digitally to", "type": "integer" }, "recipientsDeliveredPhysically": { "format": "int32", "description": "Number of recipients that have been delivered physically to", "type": "integer" }, "recipientsWithSmsDelivered": { "format": "int32", "description": "Number of recipients that received SMS", "type": "integer" }, "recipientsDeliveredEbill": { "format": "int32", "description": "Number of recipients that have been delivered via eBill", "type": "integer" }, "recipientsDeliveredEmail": { "format": "int32", "description": "Number of recipients that have been delivered via email", "type": "integer" } } }, "DeliveryStatusResponseV2.Document": { "type": "object", "properties": { "failedDocument": { "description": "Failed delivery documents", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryStatusResponseV2.FailedDocument" } }, "deliveredDocument": { "description": "Delivered documents", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryStatusResponseV2.DeliveredDocument" } }, "delivered": { "allOf": [ { "$ref": "#/components/schemas/DeliveryStatusResponseV2.DeliveredRecipientStatistic" }, { "description": "Statistics of delivered documents" } ] }, "pendingDocuments": { "format": "int32", "description": "Number of documents that are in process", "type": "integer" } } }, "DeliveryStatusResponseV2.FailedDetail": { "description": "Failed delivery information for a single document of recipient", "type": "object", "properties": { "deliveryChannel": { "allOf": [ { "$ref": "#/components/schemas/DeliveryChannelPreference" }, { "description": "Delivery channel" } ] }, "errorCode": { "description": "Error code", "type": "string" }, "errorMessage": { "description": "Error message", "type": "string" }, "senderUserId": { "description": "User id was defined by you for each recipient", "type": "string" } } }, "DeliveryStatusResponseV2.FailedDocument": { "description": "Documents that failed to be delivered", "type": "object", "properties": { "senderEndToEndId": { "description": "End to end id defined by you for each document. It helps you keep track the document", "type": "string" }, "documentTitle": { "description": "Document title", "type": "string" }, "status": { "allOf": [ { "$ref": "#/components/schemas/ExternalDocumentStatus" }, { "description": "Status of document: " } ] }, "errorCode": { "description": "Error code: ", "type": "string" }, "errorMessage": { "description": "Error message", "type": "string" }, "detail": { "description": "A list of recipients we could not deliver to", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryStatusResponseV2.FailedDetail" } } } }, "DerivedHashedCredentialType": { "enum": [ "birthDate" ], "type": "string" }, "DetailInfo": { "type": "object", "properties": { "documentMetadata": { "$ref": "#/components/schemas/DocumentMetadataWithoutRecipients" }, "matchedParticipantId": { "type": "string" }, "deliveryStatus": { "type": "string" }, "documentStatus": { "type": "string" }, "documentErrorCode": { "type": "string" }, "recipientStatus": { "type": "string" }, "recipientErrorCode": { "type": "string" }, "pricingList": { "type": "array", "items": { "$ref": "#/components/schemas/DetailPricing" } } } }, "DetailPricing": { "type": "object", "properties": { "productCode": { "type": "string" }, "productName": { "type": "string" }, "price": { "type": "number" } } }, "DigitalAdditionalInfo": { "description": "Group of the digital delivery information.", "type": "object", "properties": { "digitalDeliveryVariant": { "allOf": [ { "$ref": "#/components/schemas/DigitalDeliveryVariant" }, { "description": "Specifies the tier for the delivery via channel DIGITAL. This selection determines the availability of digital receipts, tracking capabilities, and recipient identification requirements. If digitalDeliveryVariant is omitted, the system defaults to 'STANDARD'.

STANDARD: Standard digital delivery with proof of dispatch. Includes a digital timestamp and signature upon acceptance by ePost. [ePost Standard]
NO_CONFIRMATION: Basic digital delivery. Provides a digital delivery without additional digital receipts or tracking features. [ePost Light]
TRACKED: Enhanced delivery with retrieval tracking. Includes all features of STANDARD, plus 'Retrieval' and 'Non-retrieval' receipts to track if and when the recipient opened the message. [ePost Plus]
REGISTERED: Full legal-grade digital registered mail. Includes all TRACKED features, as well as recipient acceptance/rejection tracking and mandatory Person Identification. Important note: 'minimumLevelOfTrust' must be set to GOLD for the recipient, as verification of the recipient as a person by an online identification process is prerequisite for ePost Registered. [ePost Registered]", "default": "STANDARD", "example": "STANDARD" } ] }, "letterAnswer": { "description": "Specifies an optional recipient response option for the delivery via channel DIGITAL. When set to a supported value, the recipient is offered a corresponding action on the delivered document in the digital letterbox. This field is only considered for the DIGITAL channel; it is ignored for all other channels. Supported values are provisioned per agreement with ePost. If omitted, empty, or set to an unrecognised value, no response option is offered and the delivery proceeds normally.", "type": "string" }, "iLetter": { "allOf": [ { "$ref": "#/components/schemas/ILetter" }, { "description": "iLetter reference parameters for the delivery via channel DIGITAL. Required when this file's mediaType is \"application/vnd.ch.klara.epost.v1+iletter\"; ignored on every other document (including when mediaType is omitted)." } ] }, "documentInfoByLanguage": { "description": "Optional localised overwrite of the top-level documentTitle and documentDescription, keyed by uppercase language code (DE, FR, IT, EN). A recipient whose letterbox language has an entry is shown that entry's title and description instead of the top-level values; a recipient whose language has no entry is shown the top-level documentTitle and documentDescription. Relevant only for the DIGITAL channel.", "type": "object", "properties": { "DE": { "$ref": "#/components/schemas/LocalizedDocumentInfo" }, "FR": { "$ref": "#/components/schemas/LocalizedDocumentInfo" }, "IT": { "$ref": "#/components/schemas/LocalizedDocumentInfo" }, "EN": { "$ref": "#/components/schemas/LocalizedDocumentInfo" } }, "example": { "DE": { "title": "Ihr Schadenfall", "description": "Ihre Unterlagen zum Schadenfall" }, "FR": { "title": "Votre sinistre", "description": "Vos documents concernant le sinistre" }, "IT": { "title": "Il suo sinistro", "description": "I suoi documenti relativi al sinistro" }, "EN": { "title": "Your claim", "description": "Your claim documents" } } } } }, "DigitalDeliveryVariant": { "enum": [ "STANDARD", "NO_CONFIRMATION", "TRACKED", "REGISTERED" ], "type": "string" }, "Directory": { "description": "The metadata of the directory (folder).", "type": "object", "properties": { "directoryId": { "description": "Id of the directory. Empty for branded directory.", "type": "string", "readOnly": true, "example": "6406a0a6f000d7555cfffb92" }, "directoryName": { "description": "Name of the directory", "type": "string", "example": "Working" }, "numberOfDocuments": { "format": "int32", "description": "Number of documents in the directory", "type": "integer", "example": 10 }, "parentDirectoryIds": { "description": "The parent folder's IDs of the folder. Empty if the folder is in the root storage.", "type": "array", "items": { "type": "string" }, "example": [ "63f5e84ac1e69b3f45d54097", "63f5e9f4c1e69b3f45d555da" ] }, "hasSubDirectories": { "description": "Flag indicating whether the folder has subdirectories.", "type": "boolean", "example": true } } }, "DocumentHandling": { "type": "object", "properties": { "allowPrint": { "description": "Whether participants may print the document from the signing room. Defaults to false.", "default": "false", "type": "boolean", "example": false }, "allowSave": { "description": "Whether participants may download / save the document from the signing room. Defaults to false.", "default": "false", "type": "boolean", "example": false } } }, "DocumentInfo": { "type": "object", "properties": { "fileName": { "description": "Original file name of the uploaded document.", "type": "string", "example": "rental-contract.pdf" }, "contentType": { "description": "MIME type of the document.", "type": "string", "example": "application/pdf" }, "sizeBytes": { "format": "int64", "description": "Size of the document in bytes.", "type": "integer", "example": 154382 }, "currentVersion": { "format": "int32", "description": "Current document version. Increments with each collected signature.", "type": "integer", "example": 2 } } }, "DocumentMetadataV2": { "description": "Metadata of one file.", "required": [ "fileName", "deliveryChannelPreferences", "recipients" ], "type": "object", "properties": { "allCredentialShouldMatch": { "description": "Decides if this document should be delivered to ONLY the recipients that have their credentials all matched or not.
If not specified, then default value of TRUE is used.
This flag is only considered for the DIGITAL delivery in ePost.", "type": "boolean" }, "fileName": { "description": "Name of document file.", "type": "string" }, "mediaType": { "description": "Indicate the specific media type of the document. For sending a standard classic letter like a PDF leave this field empty.
Acceptable values:
\"application/vnd.ch.klara.epost.v1+simple_short_message\" for simple short message. To send simple short message, leave the document type empty.
\"application/vnd.ch.klara.epost.v1+incamail\" Please use SecureSend instead of IncaMail.
\"application/vnd.ch.klara.epost.v1+securesend\" for SecureSend.
\"application/vnd.ch.klara.epost.v1+iletter\" for iLetter. An iLetter document carries no binary file; provide the reference in digitalAdditionalInfo.iLetter instead.
null for Physical delivery.", "type": "string", "example": "application/vnd.ch.klara.epost.v1+iletter" }, "deliveryChannelPreferences": { "description": "This value defines your preference & priority among delivery channels. It defines that your letter/message/document should be delivered via which one of the available channels. You can input more than one delivery channel.

\nThe order of delivery channels defines the priority of each channel. Meaning, at first we try to deliver via the first mentioned delivery channel, if it's unsuccessful, we would try via the second channel mentioned, and so on.

\nIf delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.

\nDIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
\nPHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
\nSMS delivering the \"simple short message\" as a SMS to the recipient's mobile phone. (only for simple short message media type)
\nEBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
\nEMAIL delivering it to the recipient who using email
\nAUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryChannelPreference" }, "writeOnly": true }, "senderName": { "description": "This value will be shown to the recipient as the delivery sender name.", "type": "string", "example": "Canton Bern", "writeOnly": true }, "senderEndToEndId": { "description": "This id provided by the sender. It helps the sender to reference the document during the whole process.", "type": "string", "writeOnly": true }, "senderCaseId": { "description": "This id provided by the sender. If multiple Documents are related to one case (e.g. insurance) it helps the receiver to group received documents", "type": "string", "writeOnly": true }, "documentReferenceDate": { "format": "date", "description": "This date is relevant for a document from a business point of view, it differs from the date at which the document is entered in the \"KLARA Documents\" system.\nFor eBill, The business case date can not be more than 90 days in the past and it can not be in the future.", "type": "string", "example": "1990-01-02", "writeOnly": true }, "documentTitle": { "description": "This title will be shown to the recipient of the delivery on the application.", "type": "string", "example": "nameOfTheFile" }, "documentDescription": { "description": "A short description of the document shown to the recipient as a preview text.", "type": "string", "example": "Your health check invitation with questionnaire." }, "documentTypes": { "description": "This is the types of the document. In order to send a simple short message, leave this field empty.
Accepted values: message, invoice, contract, hr.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" }, "writeOnly": true }, "recipients": { "description": "Recipients's informations include hashed and unhashed datas for identity matching process.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "allRecipientsRequired": { "description": "True if all recipients are required to be valid in case Digital channel otherwise not send to anyone and mark as failed.
If this flag true we just consider Digital delivery channel.", "type": "boolean" }, "displayDeliveredDocument": { "description": "When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle", "type": "boolean" }, "documentMessage": { "description": "The message content of the simple short message", "type": "string", "example": "Dear Peter \n Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one" }, "ebillAdditionalInfo": { "$ref": "#/components/schemas/EbillAdditionalInfo" }, "emailAdditionalInfo": { "$ref": "#/components/schemas/EmailAdditionalInfo" }, "digitalAdditionalInfo": { "$ref": "#/components/schemas/DigitalAdditionalInfo" }, "forcedOnboarding": { "allOf": [ { "$ref": "#/components/schemas/forcedOnboarding" }, { "description": "This object is optional. Defines whether all recipients of this document should be forced to register to ePost in order to receive this document. If the recipient is already registered to ePost, the normal delivery flow applies. If the recipient is not yet registered to ePost, we will send him an email asking him to register to ePost in order to receive the document. The document is stored for up to 60 days and will be delivered to the recipient as soon as he registers to ePost. After 60 days the delivery will expire.
Reminder emails are sent to the recipient after 2, 25, 40 and 55 days.
Forced onboarding is only available for the delivery channel DIGITAL. Additionally the unhashed credential EMAIL is required for forced onboarding (onboarding request email will be sent to this email address) and the minimum level of trust must be BRONZE. (It is only supported in the async deliveries API.)" } ] }, "physicalAdditionalInfo": { "$ref": "#/components/schemas/PhysicalAdditionalInfo" } } }, "DocumentMetadataV2ForPreviewService": { "description": "Document metadata for preview pricing service .", "required": [ "fileName", "deliveryChannelPreferences", "recipients" ], "type": "object", "properties": { "allCredentialShouldMatch": { "description": "Decides if this document should be delivered to ONLY the recipients that have their credentials all matched or not.
If not specified, then default value of TRUE is used.
This flag is only considered for the DIGITAL delivery in ePost.", "type": "boolean" }, "fileName": { "description": "Name of document file.", "type": "string" }, "mediaType": { "description": "Indicate the specific media type of the document. For sending a standard classic letter like a PDF leave this field empty.
Acceptable values:
\"application/vnd.ch.klara.epost.v1+simple_short_message\" for simple short message. To send simple short message, leave the document type empty.
\"application/vnd.ch.klara.epost.v1+incamail\" Please use SecureSend instead of IncaMail.
\"application/vnd.ch.klara.epost.v1+securesend\" for SecureSend.
\"application/vnd.ch.klara.epost.v1+iletter\" for iLetter. An iLetter document carries no binary file; provide the reference in digitalAdditionalInfo.iLetter instead.
null for Physical delivery.", "type": "string", "example": "application/vnd.ch.klara.epost.v1+iletter" }, "deliveryChannelPreferences": { "description": "This value defines your preference & priority among delivery channels. It defines that your letter/message/document should be delivered via which one of the available channels. You can input more than one delivery channel.

\nThe order of delivery channels defines the priority of each channel. Meaning, at first we try to deliver via the first mentioned delivery channel, if it's unsuccessful, we would try via the second channel mentioned, and so on.

\nIf delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.

\nDIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
\nPHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
\nSMS delivering the \"simple short message\" as a SMS to the recipient's mobile phone. (only for simple short message media type)
\nEBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
\nEMAIL delivering it to the recipient who using email
\nAUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryChannelPreference" }, "writeOnly": true }, "senderName": { "description": "This value will be shown to the recipient as the delivery sender name.", "type": "string", "example": "Canton Bern", "writeOnly": true }, "senderEndToEndId": { "description": "This id provided by the sender. It helps the sender to reference the document during the whole process.", "type": "string", "writeOnly": true }, "senderCaseId": { "description": "This id provided by the sender. If multiple Documents are related to one case (e.g. insurance) it helps the receiver to group received documents", "type": "string", "writeOnly": true }, "documentReferenceDate": { "format": "date", "description": "This date is relevant for a document from a business point of view, it differs from the date at which the document is entered in the \"KLARA Documents\" system.\nFor eBill, The business case date can not be more than 90 days in the past and it can not be in the future.", "type": "string", "example": "1990-01-02", "writeOnly": true }, "documentTitle": { "description": "This title will be shown to the recipient of the delivery on the application.", "type": "string", "example": "nameOfTheFile" }, "documentDescription": { "description": "A short description of the document shown to the recipient as a preview text.", "type": "string", "example": "Your health check invitation with questionnaire." }, "documentTypes": { "description": "This is the types of the document. In order to send a simple short message, leave this field empty.
Accepted values: message, invoice, contract, hr.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" }, "writeOnly": true }, "recipients": { "description": "Recipients's informations include hashed and unhashed datas for identity matching process.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "allRecipientsRequired": { "description": "True if all recipients are required to be valid in case Digital channel otherwise not send to anyone and mark as failed.
If this flag true we just consider Digital delivery channel.", "type": "boolean" }, "displayDeliveredDocument": { "description": "When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle", "type": "boolean" }, "documentMessage": { "description": "The message content of the simple short message", "type": "string", "example": "Dear Peter \n Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one" }, "ebillAdditionalInfo": { "$ref": "#/components/schemas/EbillAdditionalInfo" }, "emailAdditionalInfo": { "$ref": "#/components/schemas/EmailAdditionalInfo" }, "digitalAdditionalInfo": { "$ref": "#/components/schemas/DigitalAdditionalInfo" }, "physicalAdditionalInfo": { "allOf": [ { "$ref": "#/components/schemas/PhysicalAdditionalInfoForPreviewService" }, { "description": "Additional information for PHYSICAL channel, use default values if it is not provided." } ] }, "forcedOnboarding": { "allOf": [ { "$ref": "#/components/schemas/forcedOnboarding" }, { "description": "For the preview: If no match for channel DIGITAL was found for the provided credentials, the preview result will still include channel DIGITAL in case a valid forcedOnboarding object as well as a valid recipient email address was provided in the metadata (as creating a forced onboarding delivery for the DIGITAL channel is possible in this case). In this case the participantId will be null in the preview result, as in the forced onboarding case the participant does not exist in ePost, yet.
This object is optional. Defines whether all recipients of this document should be forced to register to ePost in order to receive this document. If the recipient is already registered to ePost, the normal delivery flow applies. If the recipient is not yet registered to ePost, we will send him an email asking him to register to ePost in order to receive the document. The document is stored for up to 60 days and will be delivered to the recipient as soon as he registers to ePost. After 60 days the delivery will expire.
Reminder emails are sent to the recipient after 2, 25, 40 and 55 days.
Forced onboarding is only available for the delivery channel DIGITAL. Additionally the unhashed credential EMAIL is required for forced onboarding (onboarding request email will be sent to this email address) and the minimum level of trust must be BRONZE. (It is only supported in the async deliveries API.)" } ] } } }, "DocumentMetadataWithoutRecipients": { "type": "object", "properties": { "allCredentialShouldMatch": { "type": "boolean" }, "fileName": { "type": "string" }, "mediaType": { "type": "string" }, "senderName": { "type": "string" }, "senderEndToEndId": { "type": "string" }, "senderCaseId": { "type": "string" }, "documentReferenceDate": { "format": "date", "type": "string" }, "documentTitle": { "type": "string" }, "documentTypes": { "type": "array", "items": { "type": "string" } }, "allRecipientsRequired": { "type": "boolean" }, "origin": { "type": "string" }, "documentMessage": { "type": "string" }, "ebillAdditionalInfo": { "$ref": "#/components/schemas/EbillAdditionalInfo" }, "emailAdditionalInfo": { "$ref": "#/components/schemas/EmailAdditionalInfo" }, "physicalAdditionalInfo": { "$ref": "#/components/schemas/PhysicalAdditionalInfo1" }, "digitalAdditionalInfo": { "$ref": "#/components/schemas/DigitalAdditionalInfo" } } }, "DocumentType": { "enum": [ "message", "invoice", "contract", "hr" ], "type": "string" }, "EbillAdditionalInfo": { "description": "Group of the eBill delivery information.", "type": "object", "properties": { "dueDate": { "format": "date", "description": "Due date of business case", "type": "string", "example": "2022-12-22", "writeOnly": true }, "paymentAmount": { "description": "Amount to be paid for the invoice document", "type": "number", "example": 20, "writeOnly": true }, "qrReference": { "description": "Reference number in the invoice document, this field is referring to the QR Reference, as the biller should have provided a QR-IBAN.", "type": "string", "example": "RF012345QF67T8910UI123", "writeOnly": true } } }, "EffectiveILetterParameter": { "description": "One iLetter parameter key-value pair as it was actually used for a recipient.", "type": "object", "properties": { "key": { "description": "The parameter key.", "type": "string", "example": "claimId" }, "value": { "description": "The value used for this key for this recipient.", "type": "string", "example": "CLM-2026-0042" } } }, "EffectiveILetterPlaceholder": { "description": "One iLetter placeholder key-value pair as it was supplied for a recipient.", "type": "object", "properties": { "key": { "description": "The placeholder key.", "type": "string", "example": "claimNumber" }, "value": { "description": "The value supplied for this placeholder for this recipient.", "type": "string", "example": "CLM-2026-000471" } } }, "EmailAdditionalInfo": { "description": "Group of the email delivery information.", "type": "object", "properties": { "emailText": { "description": "Content of the email.", "type": "string", "example": "Hello world.", "writeOnly": true }, "emailHtml": { "description": "Content of the email in html format.", "type": "string", "example": "

Hallo world


", "writeOnly": true }, "emailSubject": { "description": "Subject of the email.", "type": "string", "example": "your invoice from KLARA", "writeOnly": true }, "sender": { "allOf": [ { "$ref": "#/components/schemas/AdditionalEmailInfo" }, { "description": "The sender's email info (only used for sending in EMAIL channel)", "writeOnly": true } ] }, "replyTo": { "description": "Reply to the given emails.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalEmailInfo" }, "writeOnly": true }, "cc": { "description": "Sending email as cc list.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalEmailInfo" }, "writeOnly": true }, "bcc": { "description": "Sending email as bcc list.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalEmailInfo" }, "writeOnly": true }, "inlineImages": { "description": "Inline images of the email", "type": "array", "items": { "$ref": "#/components/schemas/EmailInlineImage" } } } }, "EmailInlineImage": { "description": "Inline image for attach into email.", "required": [ "filename", "base64" ], "type": "object", "properties": { "filename": { "description": "filename of the inline image", "pattern": "\\S", "type": "string", "example": "picture1.png", "nullable": false }, "base64": { "description": "file content of the inline image as base64.", "pattern": "\\S", "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAXCAYAAAD+4+QTAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQ", "nullable": false } } }, "EnvelopeSize": { "enum": [ "C4", "C5", "BOX", "AUTO" ], "type": "string" }, "ErrorMessage": { "type": "object", "properties": { "uuid": { "type": "string" }, "createdTime": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": "string", "deprecated": true } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "description": "Summary of the error response", "type": "string" }, "error_description": { "description": "Description of the error response", "type": "string" } } }, "ExternalDocumentStatus": { "description": "Status of document: ", "enum": [ "FAILED", "DELIVERED_WITH_ERROR", "NOT_MATCH_ALL_RECIPIENTS" ], "type": "string" }, "HashedPrimaryCredentialType": { "enum": [ "email", "postaladdress", "mobilenumber" ], "type": "string" }, "ILetter": { "description": "iLetter reference parameters supplied per file under digitalAdditionalInfo when the file is an iLetter document. Set mediaType to \"application/vnd.ch.klara.epost.v1+iletter\" and provide templateId to send an interactive iLetter created from that Template; such a document carries no file binary. On a document with any other mediaType this object has no effect: no iLetter is created or touched and the delivery is neither rejected nor altered.", "required": [ "templateId" ], "type": "object", "properties": { "templateId": { "description": "Id of the iLetter Template used to create the iLetter to send. Required for every iLetter document sent through this API. Applies only to iLetter documents; ignored on other document types.", "maxLength": 128, "type": "string" }, "batchId": { "description": "Optional iLetter batch id. Deliveries with the same batchId share one iLetter record: sending the same batchId again appends the new recipients to the existing iLetter instead of creating a new one. If omitted, this delivery always creates its own new iLetter, and a resend of a failed delivery updates that same iLetter rather than creating a second one.", "maxLength": 128, "type": "string" }, "confidentialResponses": { "description": "Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.", "type": "boolean" }, "responseDeadline": { "description": "Date and time by which recipients are asked to answer, as an ISO-8601 instant with UTC offset, for example 2026-10-31T21:59:59Z. Passed on exactly as supplied. Absent means no deadline.", "type": "string" }, "parameters": { "description": "Default values for this document's iLetter URL parameters, appended to the letter's data-source calls; one entry per key, at most 20 entries. A recipient may override individual keys under recipients[].iLetter.parameters; per key the recipient's value applies when supplied, otherwise this document-level value. A recipient left without a value for a required key fails with ILETTER_PARAMETER_REQUIRED_VALUE_MISSING naming the key; a key the Template does not declare fails with ILETTER_PARAMETER_KEY_UNKNOWN.", "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/ILetterParameter" } }, "placeholders": { "description": "Values for the letter's text placeholders, substituted into the letter text; one entry per key, applied to every recipient of this document. A recipient may override individual keys under recipients[].iLetter.placeholders; per key the recipient's value applies when supplied, otherwise this value. At most 100 entries per level, values of at most 2000 characters; a document over these limits is rejected with ILETTER_PLACEHOLDER_LIMIT_EXCEEDED. A value for a key the letter does not define is ignored. Unlike a missing URL parameter, a recipient left without a value for a required placeholder does not reject the request: that recipient ends in a failed status with ILETTER_PLACEHOLDER_REQUIRED_VALUE_MISSING naming the key, and the other recipients are delivered.", "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/ILetterPlaceholder" } } } }, "ILetterParameter": { "description": "One key-value pair supplied for an iLetter's REST data source parameters.", "required": [ "key" ], "type": "object", "properties": { "key": { "description": "Must match a SENDER_PARAMETER key declared on the iLetter's data sources. At most 64 characters; starts with a letter or underscore, followed by letters, digits, underscores or hyphens.", "maxLength": 64, "pattern": "\\S", "type": "string", "nullable": false }, "value": { "description": "The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.", "maxLength": 128, "type": "string" } } }, "ILetterPlaceholder": { "description": "One value for a text placeholder defined on the iLetter.", "required": [ "key" ], "type": "object", "properties": { "key": { "description": "Key of a placeholder defined on the letter. At most 64 characters; starts with a letter or underscore, followed by letters, digits, underscores or hyphens. A key the letter does not define is ignored.", "maxLength": 64, "pattern": "\\S", "type": "string", "nullable": false }, "value": { "description": "Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.", "maxLength": 2000, "type": "string" } } }, "IdentityMatchingRecipient": { "description": "Recipient's info include hashed and unhashed data for identity matching process.", "type": "object", "properties": { "senderUserId": { "description": "This id is for the sender to recognize the recipient.", "type": "string" }, "hashedPrimaryCredential": { "allOf": [ { "$ref": "#/components/schemas/HashedPrimaryCredentialType" }, { "description": "Type of the primary credential which is hashed.", "example": "email" } ] }, "hashedPrimaryValue": { "description": "Value of the primary credential.", "type": "string", "example": "adu7adsfnn3489asdfn334jk" }, "derivedHashedCredentials": { "description": "These are credentials that are hashed but aren't \"Primary Credentials\". There could be more than one credential.", "type": "array", "items": { "$ref": "#/components/schemas/DerivedHashedCredentialType" } }, "derivedHashedValue": { "description": "This hash value is derived from the other value \"hashedPrimaryValue\".", "type": "string", "example": "adu7adsfnn3489asdfn334jk" }, "unhashedCredentials": { "allOf": [ { "$ref": "#/components/schemas/UnhashedCredential" }, { "description": "Unhashed credential for identity matching process." } ] }, "iLetter": { "allOf": [ { "$ref": "#/components/schemas/ILetter" }, { "description": "Only parameters and placeholders are considered here: each overrides, per key, the document-level digitalAdditionalInfo.iLetter value of the same name for this one recipient." } ] }, "allCredentialShouldMatch": { "description": "Decides if the recipient should be strictly processed with all credentials matched or not.
If not specified, then default value of TRUE will be used.", "type": "boolean" } } }, "Letter": { "description": "Metadata of the letter", "type": "object", "properties": { "id": { "description": "Id of the letter.", "type": "string", "readOnly": true, "example": "1" }, "letterTitle": { "description": "This is the letter title.", "type": "string", "example": "eVoting questionnaire" }, "fileName": { "description": "This is the name of the reference file of the letter.", "type": "string", "example": "invoice.pdf" }, "senderParticipantId": { "description": "The participant id of the sender.", "type": "string", "example": "b0f742a3-0a54-401d-bf41-38a3a9628953" }, "senderUserId": { "description": "The sender user id of the letter.", "type": "string", "example": "84332810" }, "senderCaseId": { "description": "The sender case id of the letter.", "type": "string", "example": "8wq2d8ca" }, "senderEndToEndId": { "description": "The sender end to end id of the letter.", "type": "string", "example": "4ffdec250928157ec24ef24716468b0f25f074e6" }, "documentTypes": { "description": "Types of the letter's document.", "type": "array", "items": { "type": "string" }, "example": [ "contract", "invoice" ] }, "letterContentReference": { "description": "This is the reference link that user can use to get to content of the letter.", "type": "string", "example": "https://api.klara.ch/epost/v2/letters/1/content" }, "letterType": { "allOf": [ { "$ref": "#/components/schemas/LetterType" }, { "description": "The letter type.", "example": "CLASSIC_LETTER" } ] }, "receivedDateTime": { "description": "The date and time (yyyy-MM-dd'T'HH:mm:ssZ) that the letter was received.", "type": "string", "example": "2021-09-29T04:21:10.163Z" }, "documentMessage": { "description": "The message content of the simple short message", "type": "string", "example": "Dear Peter \n Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one" }, "description": { "description": "Free-text description shown alongside the letter in eArchive. Sourced from the description supplied at upload time.", "type": "string", "example": "Monthly invoice file" }, "readStatus": { "allOf": [ { "$ref": "#/components/schemas/LetterReadStatus" }, { "description": "The read status of the document.", "example": "READ" } ] }, "remainingDayToDelete": { "format": "int64", "description": "The remaining days before permanently delete", "type": "integer", "example": 30 }, "registeredStatus": { "description": "The current registration status", "type": "string", "example": "PENDING | ACCEPTED | LEGALLY_ACCEPTED" }, "eLetterRegistered": { "description": "Letter is registered or not", "type": "boolean", "example": "true/false" } } }, "LetterFolder": { "enum": [ "INBOX_FOLDER", "SENT_FOLDER" ], "type": "string" }, "LetterReadStatus": { "enum": [ "READ", "UNREAD" ], "type": "string" }, "LetterReadStatusFilterParam": { "enum": [ "READ", "UNREAD", "ALL" ], "type": "string" }, "LetterReadUnreadResult": { "type": "object", "properties": { "letter_id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" } } }, "LetterType": { "enum": [ "CLASSIC_LETTER", "SMART_LETTER", "SMART_LETTER_ANSWER", "SIMPLE_SHORT_MESSAGE", "INCAMAIL", "SECURESEND" ], "type": "string" }, "LevelOfTrust": { "enum": [ "BRONZE", "SILVER", "GOLD" ], "type": "string" }, "Link": { "description": "Link metadata", "type": "object", "properties": { "href": { "type": "string" } } }, "LocalizedDocumentInfo": { "type": "object", "properties": { "title": { "description": "Title shown to a recipient whose letterbox language matches this entry's key.", "type": "string", "example": "Ihr Schadenfall" }, "description": { "description": "Description shown to a recipient whose letterbox language matches this entry's key.", "type": "string" } } }, "MatchedRecipient": { "type": "object", "properties": { "participantId": { "description": "This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.", "type": "string" }, "senderUserId": { "description": "This id is for the sender to recognize the recipient.", "type": "string" }, "levelOfTrust": { "allOf": [ { "$ref": "#/components/schemas/LevelOfTrust" }, { "description": "The Levels of Trust (LoT) define how strong a user is verified in the KLARA ecosystem. Three possible level of trust: BRONZE, SILVER, GOLD." } ] }, "notMatchCredentials": { "description": "The list credentials not matched.", "type": "array", "items": { "type": "string" }, "example": "[EMAIl, MOBILE_NUMBER]" }, "errorMessage": { "description": "The error message of matching services (if any)", "type": "string" }, "communityId": { "description": "The recipient's community ID (Matrix ID) for individual tenants active in the ePost community. Omitted when the recipient is not an individual or has no community account.", "type": "string" } } }, "MatchingLookup": { "description": "The response of the matching look up response.", "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/MatchingLookupRecipient" } }, "_links": { "$ref": "#/components/schemas/MatchingLookupLink" } } }, "MatchingLookupLink": { "description": "The link use for matching look up.", "type": "object", "properties": { "self": { "$ref": "#/components/schemas/Link" }, "next": { "$ref": "#/components/schemas/Link" } } }, "MatchingLookupRecipient": { "description": "The recipient data for the matching lookup response.", "type": "object", "properties": { "hashedPrimaryValue": { "type": "string" }, "levelOfTrust": { "type": "string" } } }, "MatchingResponse": { "type": "object", "properties": { "matchedRecipients": { "description": "This list contain the recipient info which matched with given information.", "type": "array", "items": { "$ref": "#/components/schemas/MatchedRecipient" } }, "nonMatchedRecipients": { "description": "This list contain the non-matched recipient with the error message corresponding.", "type": "array", "items": { "$ref": "#/components/schemas/MatchedRecipient" } } } }, "MatchingRunProcessResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/MatchingRunStatus" }, "matchingResult": { "$ref": "#/components/schemas/MatchingResponse" } } }, "MatchingRunResultLocation": { "type": "object", "properties": { "matchingRunResultLocation": { "description": "Contains the URL location to get the matching run result", "type": "string" } } }, "MatchingRunStatus": { "enum": [ "PROCESSING", "FINISHED" ], "type": "string" }, "Onboarding": { "description": "This model to hold data for onboarding steps", "type": "object", "properties": { "pinBrandedFolder": { "type": "boolean" }, "addingCredential": { "allOf": [ { "$ref": "#/components/schemas/QrCodeCredentialData" }, { "description": "Credentials to be add to user account, who scan the qr code." } ] } } }, "OneApiPreviewRequest": { "description": "A list of binary file and document metadata.", "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/BinaryFileV2" } }, "largeFile": { "allOf": [ { "$ref": "#/components/schemas/BinaryFileV2" }, { "description": "Only usable for specially activated senders!
\nOnly DIGITAL channel is supported.
\nDelivery (binary + metadata) size limit: 1GB" } ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/BaseDeliveryMetadataV2" }, { "description": "metadata" } ] } } }, "ParticipantStatus": { "type": "object", "properties": { "internalTrackingId": { "format": "uuid", "description": "Process-local participant id. Stable, also while the participant is unresolved. Use this to address the participant on PATCH.", "type": "string", "example": "b4a9b3f1-c8d0-4e2a-b5f6-b7c8d9e0a1b2" }, "participantId": { "description": "Internal ePost id of the resolved tenant. null while the participant cannot be resolved (e.g. forced onboarding pending, address-only credential).", "type": "string", "example": "c60d31fa-f335-4957-872a-90b035632081", "nullable": true }, "name": { "description": "Name as used within the signing process / signature itself. null while unresolved. Per CISO, no additional profile data from ePost is exposed here.", "type": "string", "example": "Anna Muster", "nullable": true }, "roles": { "description": "Role(s) held by this participant within the process.", "type": "array", "items": { "enum": [ "ADMIN", "SIGNER", "RECEIVER" ], "type": "string" }, "example": [ "SIGNER", "RECEIVER" ] }, "status": { "description": "Current signing status of this participant.", "enum": [ "PENDING", "FORCED_ONBOARDING", "SIGNED", "REJECTED", "EXPIRED", "REMOVED", "NOT_REQUIRED", "FULFILLED_BY_OTHER" ], "type": "object", "example": "PENDING" }, "deliveryStatus": { "description": "Delivery progress of the initial document to this participant, independent of the signing status above.", "enum": [ "PENDING", "DELIVERED", "ONBOARDING_SENT", "NOT_DELIVERED", "FAILED" ], "type": "object", "example": "DELIVERED", "nullable": true }, "recipientDeliveryStatus": { "description": "Delivery progress of the final signed document to this participant once the process completes, independent of deliveryStatus above (which only covers the initial document).", "enum": [ "PENDING", "DELIVERED", "ONBOARDING_SENT", "SUBMITTER_FALLBACK", "SKIPPED_NO_RECIPIENT", "FAILED" ], "type": "object", "example": "DELIVERED", "nullable": true }, "hashedPrimaryValue": { "description": "Correlates the returned participant with the hash the caller submitted.", "type": "string", "example": "5f4dcc3b5aa765d61d8327deb882cf99", "nullable": true }, "signedByUserEmail": { "description": "Email of the ePost account in whose name the signature was made (account owner). null before signing.", "type": "string", "example": "anna.muster@example.ch", "nullable": true }, "effectiveSignerUserEmail": { "description": "Email of the user who actually signed (e.g. a shared-account user). null before signing.", "type": "string", "example": "delegate@example.ch", "nullable": true }, "sequenceIndex": { "format": "int32", "description": "1-based order (SEQUENTIAL mode). null in PARALLEL mode.", "type": "integer", "example": 1, "nullable": true }, "rejectedReason": { "description": "Reason provided when the participant refused to sign. null otherwise.", "type": "string", "example": "Wrong recipient", "nullable": true }, "signedAt": { "format": "date-time", "description": "Timestamp at which the participant signed (ISO 8601). null before signing.", "type": "string", "example": "2026-09-01T14:22:07Z", "nullable": true }, "occupied": { "description": "Whether the signing room is currently held (locked) by this participant.", "type": "boolean", "example": false } } }, "ParticipantUpdate": { "type": "object", "properties": { "roles": { "description": "New role set. Must be non-empty when supplied. The process must retain at least one ADMIN and at least one SIGNER; removing the last ADMIN results in HTTP 409.", "type": "array", "items": { "enum": [ "ADMIN", "SIGNER", "RECEIVER" ], "type": "string" }, "example": [ "SIGNER", "RECEIVER" ] }, "hashedPrimaryCredential": { "description": "Which credential is hashed as the primary key (e.g. email, mobileNumber). Omit to keep the current value.", "type": "string", "example": "email" }, "hashedPrimaryValue": { "description": "Hash of the primary credential value. Omit to keep the current value.", "type": "string", "example": "5f4dcc3b5aa765d61d8327deb882cf99" }, "derivedHashedCredentials": { "description": "Names of the additional credentials mixed into the derived hash. Omit to keep the current value.", "type": "array", "items": { "type": "string" }, "example": [ "birthDate" ] }, "derivedHashedValue": { "description": "Hash of the derived credential combination. Omit to keep the current value.", "type": "string", "example": "b4a9b3f1c8d0e2a5f6b7c8d9e0a1b2c3" }, "unhashedCredentials": { "description": "Full participant credentials — submission only. Never returned by GET endpoints. Omit to keep the current value.", "type": "object", "properties": { "universalName": { "description": "If you are not sure whether the recipient is a company or a person, then this field can be used to put the name of the recipient", "type": "string", "example": "KLARA Business AG / Peter Muster" }, "firstName": { "description": "First name of a recipient.", "type": "string", "example": "Peter" }, "lastName": { "description": "Last name of a recipient.", "type": "string", "example": "Muster" }, "companyName": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company name here.", "type": "string", "example": "KLARA" }, "companyUid": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company UID here.
In case you are inputting the company UID for delivery via eBill channel to a company recipient, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "CHE-123.456.789" }, "street": { "description": "Street name in the address of a recipient.
As an option, street name and street number can be added here together in this field. In that case, leave the \"streetNumber\" field empty.", "type": "string", "example": "Bahnhofstrasse 10a" }, "streetNumber": { "description": "Street number in the address of a recipient.", "type": "string", "example": "20" }, "zipCode": { "description": "Zip code in the address of a recipient.", "type": "string", "example": "3000" }, "city": { "description": "City in the address of a recipient.", "type": "string", "example": "Bern" }, "email": { "description": "Email of a recipient.
In case you are inputting the email of the recipient for delivery via eBill channel, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "peter.muster@gmail.com" }, "mobileNumber": { "description": "Mobile number of the recipient.
Must be a valid international phone number: Beginning with a '+' sign followed by a 1-3 digit country code and the domestic phone number.", "type": "string", "example": " +41909112233" }, "birthDate": { "format": "date", "description": "Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)", "type": "string", "example": "1990-01-02" }, "participantId": { "description": "This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.", "type": "string" }, "clientLegacyId": { "description": "This id is optional and is used to support legacy systems.", "type": "string" }, "minimumLevelOfTrust": { "allOf": [ { "$ref": "#/components/schemas/LevelOfTrust" }, { "description": "The Levels of Trust (LoT) define how strong a user is verified in the KLARA ecosystem. Three possible level of trust: BRONZE, SILVER, GOLD." } ] }, "socialSecurityNumber": { "description": "Social security number of a recipient and must be unique.", "type": "string", "example": "756.1234.5678.97" }, "taxId": { "description": "Tax ID of a recipient and must be unique.", "type": "string", "example": "263125" }, "postOfficeBoxNumber": { "description": "Post office box number", "type": "string", "example": "12" }, "postOfficeBoxZip": { "description": "Post office box zipcode", "type": "string", "example": "1212" }, "postOfficeBoxTownName": { "description": "Post office box town name", "type": "string", "example": "Vervey 1" }, "unstructuredAddressLine01": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Peter Muster" }, "unstructuredAddressLine02": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Bahnhofsstr 20" }, "unstructuredAddressLine03": { "description": "If your unstructured address has more than 3 lines, input all the remaining in this line. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "8004 Zurich Switzerland" }, "billRecipientId": { "description": "Bill recipient Id from eBill. Using in eBill channel only.
In order to deliver via eBill channel, you can input this credential. If you input more than 1 credential for eBill, delivery can happen only if all of these credentials are found in the recipient of eBill by SIX.", "type": "string", "example": "41010560425610173" } } }, "allCredentialShouldMatch": { "description": "If true, every supplied credential MUST match to resolve the participant. Omit to keep the current value.", "type": "boolean", "example": false }, "sequenceIndex": { "format": "int32", "description": "1-based order of this participant when the process runs in SEQUENTIAL mode. Ignored in PARALLEL mode. Omit to keep the current value.", "minimum": 1, "type": "integer", "example": 1 }, "signatureFields": { "description": "Signature field positions for this participant. When supplied, replaces the current fields as a whole; empty list = SwissSign default placement. Omit to keep the current value.", "type": "array", "items": { "$ref": "#/components/schemas/SignatureField" } }, "status": { "description": "Only REMOVED is accepted — removes the participant from the process. Any other value results in HTTP 400. Only reachable while the participant is PENDING or FORCED_ONBOARDING.", "enum": [ "PENDING", "FORCED_ONBOARDING", "SIGNED", "REJECTED", "EXPIRED", "REMOVED", "NOT_REQUIRED", "FULFILLED_BY_OTHER" ], "type": "object", "example": "REMOVED" } } }, "PhysicalAdditionalInfo": { "description": "Group of the physical delivery information.", "type": "object", "properties": { "duplex": { "description": "If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.", "default": "false", "type": "boolean", "example": false }, "shippingCountry": { "description": "The country which the sender customer can send letters to
All acceptable country codes for shipping country.", "default": "CH", "type": "string", "example": "CH" }, "envelopeSize": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeSize" }, { "description": "Size of the envelope (values: C4, C5, BOX, AUTO)", "default": "AUTO", "example": "C5" } ] }, "postage": { "allOf": [ { "$ref": "#/components/schemas/Postage" }, { "description": "Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)", "default": "A_POST", "example": "A_POST" } ] }, "qrInvoicePageNumber": { "format": "int32", "description": "The qr Invoice page number", "default": "0", "type": "integer", "example": 0 }, "windowLocation": { "allOf": [ { "$ref": "#/components/schemas/WindowLocation" }, { "description": "The position of the letter(values: LEFT, RIGHT)", "default": "LEFT", "example": "LEFT" } ] }, "coverPrinterLogoId": { "description": "Optional field. This field is used to print your logo on the envelope by our printer partner. If you wish to do so, please contact the KLARA administrator.", "default": "", "type": "string", "example": "BKW.tif" }, "attachment": { "description": "Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.", "default": "", "type": "string", "example": "myAttachment01.pdf" }, "senderAddress": { "allOf": [ { "$ref": "#/components/schemas/SenderAddress" }, { "description": "Address to be printed on the letter as sender address. Optional (if no sender address is provided, the company address of the sender tenant will be printed on the letter as sender address)." } ] } } }, "PhysicalAdditionalInfo1": { "type": "object", "properties": { "postage": { "$ref": "#/components/schemas/Postage" }, "envelopeSize": { "$ref": "#/components/schemas/EnvelopeSize" }, "duplex": { "type": "boolean" }, "windowLocation": { "$ref": "#/components/schemas/WindowLocation" }, "qrInvoicePageNumber": { "format": "int32", "type": "integer" }, "shippingCountry": { "type": "string" } } }, "PhysicalAdditionalInfoForPreviewService": { "description": "Additional info support for preview pricing service.", "type": "object", "properties": { "duplex": { "description": "If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.", "default": "false", "type": "boolean", "example": false }, "shippingCountry": { "description": "The country which the sender customer can send letters to
All acceptable country codes for shipping country.", "default": "CH", "type": "string", "example": "CH" }, "envelopeSize": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeSize" }, { "description": "Size of the envelope (values: C4, C5, BOX, AUTO)", "default": "AUTO", "example": "C5" } ] }, "postage": { "allOf": [ { "$ref": "#/components/schemas/Postage" }, { "description": "Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)", "default": "A_POST", "example": "A_POST" } ] }, "qrInvoicePageNumber": { "format": "int32", "description": "The qr Invoice page number", "default": "0", "type": "integer", "example": 0 }, "windowLocation": { "allOf": [ { "$ref": "#/components/schemas/WindowLocation" }, { "description": "The position of the letter(values: LEFT, RIGHT)", "default": "LEFT", "example": "LEFT" } ] }, "coverPrinterLogoId": { "description": "Optional field. This field is used to print your logo on the envelope by our printer partner. If you wish to do so, please contact the KLARA administrator.", "default": "", "type": "string", "example": "BKW.tif" }, "attachment": { "description": "Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.", "default": "", "type": "string", "example": "myAttachment01.pdf" }, "senderAddress": { "allOf": [ { "$ref": "#/components/schemas/SenderAddress" }, { "description": "Address to be printed on the letter as sender address. Optional (if no sender address is provided, the company address of the sender tenant will be printed on the letter as sender address)." } ] }, "numberOfPage": { "format": "int32", "description": "Number of document page should be provided if no file uploaded", "type": "integer" } } }, "Postage": { "enum": [ "A_POST", "B_POST", "B_POST_LARGEVOLUME", "A_PLUS", "REGISTERED" ], "type": "string" }, "PotentialPriceItem": { "description": "Preview total potential price for specific delivery channel", "type": "object", "properties": { "channel": { "allOf": [ { "$ref": "#/components/schemas/DeliveryChannelPreview" }, { "description": "Potential delivery channel" } ] }, "price": { "description": "Total potential price for specific channel", "type": "number" }, "errorCode": { "description": "Error code", "type": "string" }, "errorMessage": { "description": "Reason can not preview price", "type": "string" } } }, "PreviewDeliveryChannel": { "description": "List of delivery-channel preview item.", "type": "object", "properties": { "participantId": { "description": "The participant id of the user that was delivered. Available for DIGITAL channel only.", "type": "string" }, "billRecipientId": { "description": "The bill recipient id of the user that was delivered. Available for EBILL channel only.", "type": "string" }, "senderUserId": { "description": "User id was defined by sender for each recipient", "type": "string" }, "senderEndToEndId": { "description": "End to end id defined by sender for each document", "type": "string" }, "fileName": { "description": "Name of document file uploaded", "type": "string" }, "documentTitle": { "description": "Document title", "type": "string" }, "availableChannels": { "description": "List of available channels that can be delivered for this recipient", "type": "array", "items": { "$ref": "#/components/schemas/DeliveryChannelPreview" } }, "errorCode": { "description": "Error code of preview delivery channel", "type": "string" }, "errorMessage": { "description": "Error message of preview delivery channel", "type": "string" } } }, "PreviewDeliveryChannelResponse": { "description": "Response of delivery-channel preview with status.", "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/DeliveryPreviewStatus" }, { "description": "The status of preview delivery-channel." } ] }, "previewChannels": { "description": "List response of delivery-channel preview.", "type": "array", "items": { "$ref": "#/components/schemas/PreviewDeliveryChannel" } } } }, "PreviewDeliveryMetadataV2": { "description": "Metadata of one delivery v2 contain list metadata of files for preview service.", "type": "object", "properties": { "costCenter": { "description": "In each delivery, you can input the specific department name sending the delivery. In order to see the cost generated by each business unit/department in the invoice. This is an optional field and maximum of 1 value per each delivery is accepted.", "type": "string" }, "fileMetadata": { "description": "List of file's metadata", "type": "array", "items": { "$ref": "#/components/schemas/DocumentMetadataV2ForPreviewService" } } } }, "PreviewDeliveryPricingResponse": { "description": "Response of delivery pricing preview with status.", "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/DeliveryPreviewStatus" }, { "description": "The status of preview delivery pricing." } ] }, "pricePreview": { "description": "List price preview of single delivery.", "type": "array", "items": { "$ref": "#/components/schemas/PreviewPotentialPrice" } } } }, "PreviewDeliveryRequestV2": { "description": "A list of binary file and document metadata for preview service.", "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/BinaryFileV2" } }, "largeFile": { "allOf": [ { "$ref": "#/components/schemas/BinaryFileV2" }, { "description": "Only usable for specially activated senders!
\nOnly DIGITAL channel is supported.
\nDelivery (binary + metadata) size limit: 1GB" } ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/PreviewDeliveryMetadataV2" }, { "description": "metadata" } ] } } }, "PreviewOption": { "enum": [ "FIRST_AVAILABLE_CHANNEL", "ALL_AVAILABLE_CHANNELS" ], "type": "string" }, "PreviewPotentialPrice": { "description": "List of delivery pricing preview item.", "type": "object", "properties": { "participantId": { "description": "The participant id of the user that was delivered. Available for DIGITAL channel only.", "type": "string" }, "billRecipientId": { "description": "The bill recipient id of the user that was delivered. Available for EBILL channel only.", "type": "string" }, "senderUserId": { "description": "User id was defined by sender for each recipient", "type": "string" }, "senderEndToEndId": { "description": "End to end id defined by sender for each document", "type": "string" }, "fileName": { "description": "Name of document file uploaded", "type": "string" }, "documentTitle": { "description": "Document title", "type": "string" }, "potentialPrices": { "description": "List of potential price for each single delivery", "type": "array", "items": { "$ref": "#/components/schemas/PotentialPriceItem" } }, "errorCode": { "description": "Error code of preview pricing service", "type": "string" }, "errorMessage": { "description": "Error message of preview pricing service", "type": "string" } } }, "PublicAPIToken": { "description": "A public api token object. This object holds info of tokens that can be used to access KLARA Public API", "type": "object", "properties": { "access_token": { "description": "Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant", "type": "string" }, "expires_in": { "format": "int64", "description": "Amount of time in seconds left that the access token is valid for", "type": "integer" }, "refresh_expires_in": { "format": "int64", "description": "Amount of time in seconds left that the refresh token is valid for", "type": "integer" }, "refreshToken": { "description": "Token used to renew the access token", "type": "string" }, "token_type": { "description": "Type of access token that should be included in the Authorziation header of each request", "type": "string" } } }, "QrCodeAddress": { "description": "After user scan the qr code, this address data will be added to user account in mobile app.", "required": [ "type", "firstName", "lastName" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/QrCodeAddressType" }, { "description": "Type of an qr code address. Valid values: PO_BOX, POSTAL", "example": "POSTAL", "nullable": false } ] }, "firstName": { "description": "First name of an address.", "type": "string", "example": "Peter" }, "lastName": { "description": "Last name of an address.", "type": "string", "example": "Muster" }, "street": { "description": "Street name of an address.", "type": "string", "example": "Bahnhofstrasse" }, "streetNumber": { "description": "Street number of an address.", "type": "string", "example": "20" }, "zipCode": { "description": "Zip code of an address.", "type": "string", "example": "3000" }, "city": { "description": "City code of an address.", "type": "string", "example": "Bern" }, "additionalAddressLine": { "description": "Additional to an address.", "type": "string", "example": "additional address info" }, "postOfficeBoxNumber": { "description": "Post office box number", "type": "string", "example": "12" }, "postOfficeBoxZip": { "description": "Post office box zipcode", "type": "string", "example": "1212" }, "postOfficeBoxTownName": { "description": "Post office box town name", "type": "string", "example": "Vervey 1" }, "verificationScore": { "format": "int32", "description": "Verification score", "type": "integer", "example": 50 }, "gender": { "description": "Gender of address's owner. Allow values: \"male\", \"female\"", "type": "string", "example": "male" } } }, "QrCodeAddressType": { "enum": [ "PO_BOX", "POSTAL" ], "type": "string" }, "QrCodeCredential": { "description": "After user scan the qr code, this credential data will be added to user account in mobile app.", "required": [ "name", "value" ], "type": "object", "properties": { "name": { "allOf": [ { "$ref": "#/components/schemas/QrCodeCredentialName" }, { "description": "Name of an qr code credential. Valid values: MOBILE, TAX_ID, EMAIL", "example": "EMAIL", "nullable": false } ] }, "value": { "description": "Value of an qr code credential.", "type": "string", "example": "peter.muster@gmail.com", "nullable": false }, "verificationScore": { "format": "int32", "description": "Verification score", "type": "integer", "example": 0 } } }, "QrCodeCredentialData": { "description": "After user scan the qr code, these address and credentials data will be added to user account in mobile app.", "type": "object", "properties": { "othercredentials": { "description": "List of credentials to be add to user account, who scan the qr code.", "type": "array", "items": { "$ref": "#/components/schemas/QrCodeCredential" } }, "address": { "allOf": [ { "$ref": "#/components/schemas/QrCodeAddress" }, { "description": "Address to be add to user account, who scan the qr code." } ] } } }, "QrCodeCredentialName": { "enum": [ "MOBILE", "TAX_ID", "EMAIL" ], "type": "string" }, "ReadLetters": { "description": "Letters with read status", "required": [ "readStatus", "letterIds" ], "type": "object", "properties": { "readStatus": { "allOf": [ { "$ref": "#/components/schemas/LetterReadStatus" }, { "description": "Marked the given letters as READ/UNREAD status. Default is READ", "example": "READ" } ] }, "letterIds": { "description": "Letter ids", "type": "array", "items": { "type": "string" }, "example": [ "65e7e536aae6544ca8dce48f", "65e7e4d2aae6544ca8dce485" ] } } }, "Recipient": { "description": "Recipient's info include hashed and unhashed data.", "type": "object", "properties": { "senderUserId": { "description": "This id is for the sender to recognize the recipient.", "type": "string" }, "hashedPrimaryCredential": { "allOf": [ { "$ref": "#/components/schemas/HashedPrimaryCredentialType" }, { "description": "Type of the primary credential which is hashed.", "example": "email" } ] }, "hashedPrimaryValue": { "description": "Value of the primary credential.", "type": "string", "example": "adu7adsfnn3489asdfn334jk" }, "derivedHashedCredentials": { "description": "These are credentials that are hashed but aren't \"Primary Credentials\". There could be more than one credential.", "type": "array", "items": { "$ref": "#/components/schemas/DerivedHashedCredentialType" } }, "derivedHashedValue": { "description": "This hash value is derived from the other value \"hashedPrimaryValue\".", "type": "string", "example": "adu7adsfnn3489asdfn334jk" }, "unhashedCredentials": { "allOf": [ { "$ref": "#/components/schemas/UnhashedCredential" }, { "description": "Unhashed credential for identity matching process." } ] }, "iLetter": { "allOf": [ { "$ref": "#/components/schemas/ILetter" }, { "description": "Only parameters and placeholders are considered here: each overrides, per key, the document-level digitalAdditionalInfo.iLetter value of the same name for this one recipient." } ] } } }, "RecipientInfo": { "required": [ "recipients" ], "type": "object", "properties": { "recipients": { "maxItems": 50000, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/IdentityMatchingRecipient" } } } }, "RecipientTrackingDataResponse": { "type": "object", "properties": { "id": { "format": "int64", "type": "integer" }, "deliveryId": { "format": "int64", "type": "integer" }, "deliveredTime": { "format": "date-time", "type": "string" }, "createdTime": { "format": "date-time", "type": "string" }, "costCenter": { "type": "string" }, "documentTitle": { "type": "string" }, "documentTypes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" } }, "unhashedCredentials": { "$ref": "#/components/schemas/UnhashedCredential" }, "senderUserId": { "type": "string" }, "cost": { "type": "number" }, "channel": { "type": "string" }, "status": { "type": "string" }, "thirdPartyStatus": { "type": "string" }, "thirdPartyErrorMessage": { "type": "string" }, "errorCode": { "type": "string" }, "deliveryChannelPreferences": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryChannelPreference" } }, "detail": { "$ref": "#/components/schemas/DetailInfo" }, "pricePlan": { "type": "string" }, "businessStatusHistory": { "description": "The history of business status changes for this delivery, ordered from the oldest to the most recent status change.", "type": "array", "items": { "$ref": "#/components/schemas/BusinessStatusHistory" } }, "effectiveILetterParameters": { "description": "The iLetter parameter key-value pairs actually used for this recipient: the recipient's own override where the sender supplied one, the document's value otherwise. Absent when the delivery carried no iLetter parameters.", "type": "array", "items": { "$ref": "#/components/schemas/EffectiveILetterParameter" } }, "effectiveILetterPlaceholders": { "description": "The iLetter placeholder key-value pairs supplied for this recipient: the recipient's own value where the sender supplied one, the document's value otherwise. Absent when the delivery carried no iLetter placeholders.", "type": "array", "items": { "$ref": "#/components/schemas/EffectiveILetterPlaceholder" } } } }, "ResponseFileGoneResponse": { "description": "Metadata of a Response File whose content is no longer available", "type": "object", "properties": { "fileName": { "description": "Original file name", "type": "string", "example": "id-card.pdf" }, "mimeType": { "description": "MIME type of the file", "type": "string", "example": "application/pdf" }, "size": { "format": "int64", "description": "Size of the file in bytes", "type": "integer", "example": 2048 }, "removedAt": { "description": "When the content was removed (ISO 8601 UTC). Before the daily clean-up has run, this is the expiry time.", "type": "string", "example": "2026-12-12T08:00:00Z" } } }, "SenderAddress": { "description": "Address to be printed on the letter as sender address. Optional (if no sender address is provided, the company address of the sender tenant will be printed on the letter as sender address).", "type": "object", "properties": { "name": { "description": "Sender name to be printed on the letter as part of the sender address.", "type": "string", "example": "ePost Service AG" }, "street": { "description": "Sender street to be printed on the letter as part of the sender address.", "type": "string", "example": "Bahnhofstrasse" }, "streetNumber": { "description": "Sender street number to be printed on the letter as part of the sender address.", "type": "string", "example": "20" }, "zipCode": { "description": "Sender zip code to be printed on the letter as part of the sender address.", "type": "string", "example": "3000" }, "city": { "description": "Sender city to be printed on the letter as part of the sender address.", "type": "string", "example": "Bern" } } }, "SignatureField": { "type": "object", "properties": { "fieldName": { "description": "Logical name of the signature field on the PDF form (matches the AcroForm field name when present).", "type": "string", "example": "SignatureField_1" }, "pageIndex": { "format": "int32", "description": "Zero-based index of the PDF page the field is placed on.", "minimum": 0, "type": "integer", "example": 0 }, "x": { "format": "double", "description": "X coordinate of the field's lower-left corner (PDF points).", "type": "number", "example": 72 }, "y": { "format": "double", "description": "Y coordinate of the field's lower-left corner (PDF points).", "type": "number", "example": 144 }, "width": { "format": "double", "description": "Width of the field (PDF points).", "type": "number", "example": 180 }, "height": { "format": "double", "description": "Height of the field (PDF points).", "type": "number", "example": 48 } } }, "SigningProcess": { "type": "object", "properties": { "processId": { "format": "uuid", "description": "Unique identifier of the signing process.", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" }, "title": { "description": "Title of the signing request.", "type": "string", "example": "Rental contract Bahnhofstrasse 12" }, "description": { "description": "Optional description.", "type": "string", "example": "Please sign by the end of the month.", "nullable": true }, "submittedBy": { "allOf": [ { "$ref": "#/components/schemas/ActorRef" }, { "description": "Who the signing request came from." } ] }, "signatureType": { "description": "Chosen signature type. Locked at creation.", "enum": [ "SES", "AES", "QES" ], "type": "object", "example": "SES" }, "mode": { "description": "Signing order strategy. Locked at creation.", "enum": [ "PARALLEL", "SEQUENTIAL" ], "type": "object", "example": "PARALLEL" }, "deadline": { "format": "date", "description": "Signing deadline (ISO 8601).", "type": "string", "example": "2026-12-31" }, "documentHandling": { "allOf": [ { "$ref": "#/components/schemas/DocumentHandling" }, { "description": "Restrictions applied to the document during the process." } ] }, "forceOnboarding": { "description": "Whether forced onboarding was requested for unresolved email participants.", "type": "boolean", "example": true }, "status": { "description": "Current lifecycle status.", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "EXPIRED", "CANCELLED" ], "type": "object", "example": "IN_PROGRESS" }, "deliveryState": { "description": "Delivery/orchestration state of the process side effects (independent of status).", "enum": [ "PENDING", "IN_PROGRESS", "PARTIAL", "COMPLETE", "FAILED" ], "type": "object", "example": "PARTIAL" }, "signedCount": { "format": "int32", "description": "Number of participants that have already signed.", "type": "integer", "example": 1 }, "pendingCount": { "format": "int32", "description": "Number of participants still outstanding (PENDING / FORCED_ONBOARDING).", "type": "integer", "example": 2 }, "participants": { "description": "Participants with their current signing status.", "type": "array", "items": { "type": "object", "properties": { "internalTrackingId": { "format": "uuid", "description": "Process-local participant id. Stable, also while the participant is unresolved. Use this to address the participant on PATCH.", "type": "string", "example": "b4a9b3f1-c8d0-4e2a-b5f6-b7c8d9e0a1b2" }, "participantId": { "description": "Internal ePost id of the resolved tenant. null while the participant cannot be resolved (e.g. forced onboarding pending, address-only credential).", "type": "string", "example": "c60d31fa-f335-4957-872a-90b035632081", "nullable": true }, "name": { "description": "Name as used within the signing process / signature itself. null while unresolved. Per CISO, no additional profile data from ePost is exposed here.", "type": "string", "example": "Anna Muster", "nullable": true }, "roles": { "description": "Role(s) held by this participant within the process.", "type": "array", "items": { "enum": [ "ADMIN", "SIGNER", "RECEIVER" ], "type": "string" }, "example": [ "SIGNER", "RECEIVER" ] }, "status": { "description": "Current signing status of this participant.", "enum": [ "PENDING", "FORCED_ONBOARDING", "SIGNED", "REJECTED", "EXPIRED", "REMOVED", "NOT_REQUIRED", "FULFILLED_BY_OTHER" ], "type": "object", "example": "PENDING" }, "deliveryStatus": { "description": "Delivery progress of the initial document to this participant, independent of the signing status above.", "enum": [ "PENDING", "DELIVERED", "ONBOARDING_SENT", "NOT_DELIVERED", "FAILED" ], "type": "object", "example": "DELIVERED", "nullable": true }, "recipientDeliveryStatus": { "description": "Delivery progress of the final signed document to this participant once the process completes, independent of deliveryStatus above (which only covers the initial document).", "enum": [ "PENDING", "DELIVERED", "ONBOARDING_SENT", "SUBMITTER_FALLBACK", "SKIPPED_NO_RECIPIENT", "FAILED" ], "type": "object", "example": "DELIVERED", "nullable": true }, "hashedPrimaryValue": { "description": "Correlates the returned participant with the hash the caller submitted.", "type": "string", "example": "5f4dcc3b5aa765d61d8327deb882cf99", "nullable": true }, "signedByUserEmail": { "description": "Email of the ePost account in whose name the signature was made (account owner). null before signing.", "type": "string", "example": "anna.muster@example.ch", "nullable": true }, "effectiveSignerUserEmail": { "description": "Email of the user who actually signed (e.g. a shared-account user). null before signing.", "type": "string", "example": "delegate@example.ch", "nullable": true }, "sequenceIndex": { "format": "int32", "description": "1-based order (SEQUENTIAL mode). null in PARALLEL mode.", "type": "integer", "example": 1, "nullable": true }, "rejectedReason": { "description": "Reason provided when the participant refused to sign. null otherwise.", "type": "string", "example": "Wrong recipient", "nullable": true }, "signedAt": { "format": "date-time", "description": "Timestamp at which the participant signed (ISO 8601). null before signing.", "type": "string", "example": "2026-09-01T14:22:07Z", "nullable": true }, "occupied": { "description": "Whether the signing room is currently held (locked) by this participant.", "type": "boolean", "example": false } } } }, "document": { "allOf": [ { "$ref": "#/components/schemas/DocumentInfo" }, { "description": "Metadata of the submitted document (never the payload)." } ] }, "createdAt": { "format": "date-time", "description": "Creation timestamp (ISO 8601).", "type": "string", "example": "2026-08-13T09:15:30Z" }, "completedAt": { "format": "date-time", "description": "Timestamp at which every required signature was collected. null while incomplete.", "type": "string", "example": "2026-09-05T11:03:19Z", "nullable": true }, "deleteAt": { "format": "date-time", "description": "When the process/document will be finally deleted. Retention per CISO: open + signed documents 90 days; cancelled/deactivated processes 30 days; audit/process metadata 12 months.", "type": "string", "example": "2026-12-04T09:15:30Z", "nullable": true } } }, "SigningProcessCreated": { "type": "object", "properties": { "processId": { "format": "uuid", "description": "Server-assigned unique identifier of the signing process.", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" }, "status": { "description": "Initial lifecycle status of the process.", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "EXPIRED", "CANCELLED" ], "type": "object", "example": "CREATED" } } }, "SigningProcessListResponse": { "type": "object", "properties": { "items": { "description": "Page of signing processes belonging to the calling tenant.", "type": "array", "items": { "type": "object", "properties": { "processId": { "format": "uuid", "description": "Unique identifier of the signing process.", "type": "string", "example": "6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51" }, "submittedBy": { "allOf": [ { "$ref": "#/components/schemas/ActorRef" }, { "description": "Who the signing request came from (creator)." } ] }, "title": { "description": "Title of the signing request.", "type": "string", "example": "Rental contract Bahnhofstrasse 12" }, "description": { "description": "Optional description.", "type": "string", "example": "Please sign by the end of the month.", "nullable": true }, "status": { "description": "Current lifecycle status.", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "EXPIRED", "CANCELLED" ], "type": "object", "example": "IN_PROGRESS" }, "deadline": { "format": "date", "description": "Signing deadline (ISO 8601).", "type": "string", "example": "2026-12-31" }, "createdAt": { "format": "date-time", "description": "Creation timestamp (ISO 8601).", "type": "string", "example": "2026-08-13T09:15:30Z" } } } }, "total": { "format": "int64", "description": "Total number of signing processes matching the filter, across all pages.", "type": "integer", "example": 137 } } }, "SigningProcessMultipartForm": { "description": "Multipart body for POST /signing/processes: exactly one PDF plus a SigningProcessCreateRequest metadata JSON.", "type": "object", "properties": { "file": { "allOf": [ { "$ref": "#/components/schemas/BinaryFileV2" }, { "description": "The single PDF to be signed. Provided as a multipart binary part named file." } ] }, "metadata": { "description": "The SigningProcessCreateRequest metadata JSON — see the field-by-field guide in the operation description.", "required": [ "title", "signatureType", "participants", "deadline", "forceOnboarding" ], "type": "object", "properties": { "title": { "description": "Title of the signing request. Shown to participants in the signing room and in the process list.", "maxLength": 255, "pattern": "\\S", "type": "string", "example": "Rental contract Bahnhofstrasse 12", "nullable": false }, "description": { "description": "Optional free-form description shown next to the title.", "maxLength": 2000, "type": "string", "example": "Please sign by the end of the month." }, "signatureType": { "description": "SwissSign signature type. Locked once the process is created.", "enum": [ "SES", "AES", "QES" ], "type": "object", "example": "SES", "nullable": false }, "participants": { "description": "Participants of the process. Must contain at least one ADMIN (the creator) and at least one SIGNER.", "minItems": 1, "type": "array", "items": { "required": [ "roles" ], "type": "object", "properties": { "roles": { "description": "One or more roles the participant holds in this process. Must contain at least one role. Every process must contain at least one ADMIN and at least one SIGNER.", "minItems": 1, "type": "array", "items": { "enum": [ "ADMIN", "SIGNER", "RECEIVER" ], "type": "string" }, "example": [ "ADMIN", "SIGNER" ] }, "senderUserId": { "description": "Optional sender-user reference forwarded to the signing room and to the audit log.", "type": "string", "example": "user-42" }, "hashedPrimaryCredential": { "description": "Which credential is hashed as the primary key (e.g. email, mobileNumber).", "type": "string", "example": "email" }, "hashedPrimaryValue": { "description": "Hash of the primary credential value. Used for privacy-preserving matching.", "type": "string", "example": "5f4dcc3b5aa765d61d8327deb882cf99" }, "derivedHashedCredentials": { "description": "Names of the additional credentials mixed into the derived hash (e.g. [\"birthDate\"]).", "type": "array", "items": { "type": "string" }, "example": [ "birthDate" ] }, "derivedHashedValue": { "description": "Hash of the derived credential combination.", "type": "string", "example": "b4a9b3f1c8d0e2a5f6b7c8d9e0a1b2c3" }, "unhashedCredentials": { "description": "Full participant credentials — submission only. Never returned by GET endpoints. Reuses the shared UnhashedCredential DTO used elsewhere in the public API (e.g. ePost deliveries).", "type": "object", "properties": { "universalName": { "description": "If you are not sure whether the recipient is a company or a person, then this field can be used to put the name of the recipient", "type": "string", "example": "KLARA Business AG / Peter Muster" }, "firstName": { "description": "First name of a recipient.", "type": "string", "example": "Peter" }, "lastName": { "description": "Last name of a recipient.", "type": "string", "example": "Muster" }, "companyName": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company name here.", "type": "string", "example": "KLARA" }, "companyUid": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company UID here.
In case you are inputting the company UID for delivery via eBill channel to a company recipient, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "CHE-123.456.789" }, "street": { "description": "Street name in the address of a recipient.
As an option, street name and street number can be added here together in this field. In that case, leave the \"streetNumber\" field empty.", "type": "string", "example": "Bahnhofstrasse 10a" }, "streetNumber": { "description": "Street number in the address of a recipient.", "type": "string", "example": "20" }, "zipCode": { "description": "Zip code in the address of a recipient.", "type": "string", "example": "3000" }, "city": { "description": "City in the address of a recipient.", "type": "string", "example": "Bern" }, "email": { "description": "Email of a recipient.
In case you are inputting the email of the recipient for delivery via eBill channel, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "peter.muster@gmail.com" }, "mobileNumber": { "description": "Mobile number of the recipient.
Must be a valid international phone number: Beginning with a '+' sign followed by a 1-3 digit country code and the domestic phone number.", "type": "string", "example": " +41909112233" }, "birthDate": { "format": "date", "description": "Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)", "type": "string", "example": "1990-01-02" }, "participantId": { "description": "This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.", "type": "string" }, "clientLegacyId": { "description": "This id is optional and is used to support legacy systems.", "type": "string" }, "minimumLevelOfTrust": { "allOf": [ { "$ref": "#/components/schemas/LevelOfTrust" }, { "description": "The Levels of Trust (LoT) define how strong a user is verified in the KLARA ecosystem. Three possible level of trust: BRONZE, SILVER, GOLD." } ] }, "socialSecurityNumber": { "description": "Social security number of a recipient and must be unique.", "type": "string", "example": "756.1234.5678.97" }, "taxId": { "description": "Tax ID of a recipient and must be unique.", "type": "string", "example": "263125" }, "postOfficeBoxNumber": { "description": "Post office box number", "type": "string", "example": "12" }, "postOfficeBoxZip": { "description": "Post office box zipcode", "type": "string", "example": "1212" }, "postOfficeBoxTownName": { "description": "Post office box town name", "type": "string", "example": "Vervey 1" }, "unstructuredAddressLine01": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Peter Muster" }, "unstructuredAddressLine02": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Bahnhofsstr 20" }, "unstructuredAddressLine03": { "description": "If your unstructured address has more than 3 lines, input all the remaining in this line. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "8004 Zurich Switzerland" }, "billRecipientId": { "description": "Bill recipient Id from eBill. Using in eBill channel only.
In order to deliver via eBill channel, you can input this credential. If you input more than 1 credential for eBill, delivery can happen only if all of these credentials are found in the recipient of eBill by SIX.", "type": "string", "example": "41010560425610173" } } }, "allCredentialShouldMatch": { "description": "If true, every supplied credential MUST match to resolve the participant. If false, any one matching credential is sufficient. Defaults to false.", "default": "false", "type": "boolean", "example": false }, "sequenceIndex": { "format": "int32", "description": "1-based order of this participant when the process runs in SEQUENTIAL mode. Ignored in PARALLEL mode.", "minimum": 1, "type": "integer", "example": 1 }, "signatureFields": { "description": "Optional signature field positions for this participant. Empty = SwissSign default placement.", "type": "array", "items": { "$ref": "#/components/schemas/SignatureField" } } } } }, "mode": { "description": "Signing order strategy. Defaults to PARALLEL. Locked once the process is created.", "default": "PARALLEL", "enum": [ "PARALLEL", "SEQUENTIAL" ], "type": "object", "example": "PARALLEL" }, "deadline": { "format": "date", "description": "Absolute date by which every required signature must have been collected (ISO 8601).", "pattern": "\\S", "type": "string", "example": "2026-12-31", "nullable": false }, "documentHandling": { "allOf": [ { "$ref": "#/components/schemas/DocumentHandling" }, { "description": "Restrictions applied to the document while the process is running." } ] }, "forceOnboarding": { "description": "Whether to trigger a forced-onboarding email for participants that do not yet exist on ePost. Required. Only effective when the participant credential is an email address; ignored otherwise. Onboarded users can complete only SES.", "type": "boolean", "example": true, "nullable": false }, "billToCompanyTenantId": { "description": "Optional company tenant id to bill this signing to (\"send for a company\"). The acting user must hold the DOCUMENT_SIGN_BILLING company role in the KLARA web client role system on the referenced company; otherwise the request is rejected with 403. Retrieve eligible companies via GET /signing/billing-companies. The acting user/tenant remains the sender; the company only takes over billing.", "type": "string", "example": "c60d31fa-f335-4957-872a-90b035632081" } } } } }, "SigningProcessUpdate": { "type": "object", "properties": { "title": { "description": "New title shown to participants in the signing room and in the process list. Omit to keep the current title.", "maxLength": 255, "type": "string", "example": "Rental contract Bahnhofstrasse 12 (v2)" }, "description": { "description": "New free-form description. Omit to keep the current description; send an empty string to clear it.", "maxLength": 2000, "type": "string", "example": "Please sign by the end of next week." }, "deadline": { "format": "date", "description": "New absolute deadline (ISO 8601). Must be strictly in the future. Omit to keep the current deadline.", "type": "string", "example": "2027-01-31" }, "documentHandling": { "allOf": [ { "$ref": "#/components/schemas/DocumentHandling" }, { "description": "New document-handling restrictions. Omit to keep the current values; when supplied, replaces the current values as a whole." } ] }, "status": { "description": "Only CANCELLED is accepted — deactivates the process (SwissSign signaturesCancelProcessing). Any other value results in HTTP 400.", "enum": [ "CREATED", "IN_PROGRESS", "COMPLETED", "EXPIRED", "CANCELLED" ], "type": "object", "example": "CANCELLED" } } }, "SortStrategy": { "enum": [ "DESCENDING", "ASCENDING" ], "type": "string" }, "StandardMatchingResponse": { "type": "object", "properties": { "matchedRecipients": { "description": "This list contain the recipient basic info which matched with given information.", "type": "array", "items": { "$ref": "#/components/schemas/StandardRecipientResponse" } }, "nonMatchedSenderUserIds": { "description": "This list contain the non-matched recipient.", "type": "array", "items": { "type": "string" } } } }, "StandardMatchingRunProcessResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/MatchingRunStatus" }, "matchingResult": { "$ref": "#/components/schemas/StandardMatchingResponse" } } }, "StandardRecipientResponse": { "type": "object", "properties": { "senderUserId": { "description": "This id is for the sender to recognize the recipient.", "type": "string" }, "participantId": { "description": "This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.", "type": "string" }, "communityId": { "description": "The recipient's community ID (Matrix ID) for individual tenants active in the ePost community. Omitted when the recipient is not an individual or has no community account.", "type": "string" } } }, "Tenant": { "description": "A Company Tenant.", "type": "object", "properties": { "tenant_id": { "type": "string", "example": "aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "company_id": { "format": "int64", "type": "integer", "example": 1 }, "company_name": { "type": "string", "example": "ABC Company" } } }, "UnhashedCredential": { "description": "Full participant credentials — submission only. Never returned by GET endpoints. Reuses the shared UnhashedCredential DTO used elsewhere in the public API (e.g. ePost deliveries).", "type": "object", "properties": { "universalName": { "description": "If you are not sure whether the recipient is a company or a person, then this field can be used to put the name of the recipient", "type": "string", "example": "KLARA Business AG / Peter Muster" }, "firstName": { "description": "First name of a recipient.", "type": "string", "example": "Peter" }, "lastName": { "description": "Last name of a recipient.", "type": "string", "example": "Muster" }, "companyName": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company name here.", "type": "string", "example": "KLARA" }, "companyUid": { "description": "If the tenant entry is a business customer, i.e a Company, enter the company UID here.
In case you are inputting the company UID for delivery via eBill channel to a company recipient, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "CHE-123.456.789" }, "street": { "description": "Street name in the address of a recipient.
As an option, street name and street number can be added here together in this field. In that case, leave the \"streetNumber\" field empty.", "type": "string", "example": "Bahnhofstrasse 10a" }, "streetNumber": { "description": "Street number in the address of a recipient.", "type": "string", "example": "20" }, "zipCode": { "description": "Zip code in the address of a recipient.", "type": "string", "example": "3000" }, "city": { "description": "City in the address of a recipient.", "type": "string", "example": "Bern" }, "email": { "description": "Email of a recipient.
In case you are inputting the email of the recipient for delivery via eBill channel, pay attention to not input any value for the billRecipientId. Otherwise, delivery is only possible if both values are correct for the recipient of eBill.", "type": "string", "example": "peter.muster@gmail.com" }, "mobileNumber": { "description": "Mobile number of the recipient.
Must be a valid international phone number: Beginning with a '+' sign followed by a 1-3 digit country code and the domestic phone number.", "type": "string", "example": " +41909112233" }, "birthDate": { "format": "date", "description": "Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)", "type": "string", "example": "1990-01-02" }, "participantId": { "description": "This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.", "type": "string" }, "clientLegacyId": { "description": "This id is optional and is used to support legacy systems.", "type": "string" }, "minimumLevelOfTrust": { "allOf": [ { "$ref": "#/components/schemas/LevelOfTrust" }, { "description": "The Levels of Trust (LoT) define how strong a user is verified in the KLARA ecosystem. Three possible level of trust: BRONZE, SILVER, GOLD." } ] }, "socialSecurityNumber": { "description": "Social security number of a recipient and must be unique.", "type": "string", "example": "756.1234.5678.97" }, "taxId": { "description": "Tax ID of a recipient and must be unique.", "type": "string", "example": "263125" }, "postOfficeBoxNumber": { "description": "Post office box number", "type": "string", "example": "12" }, "postOfficeBoxZip": { "description": "Post office box zipcode", "type": "string", "example": "1212" }, "postOfficeBoxTownName": { "description": "Post office box town name", "type": "string", "example": "Vervey 1" }, "unstructuredAddressLine01": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Peter Muster" }, "unstructuredAddressLine02": { "description": "If you are not sure which part of the address is name, street, house number, city or postcode, then you can input your address in the unstructured line 1 to 3. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "Bahnhofsstr 20" }, "unstructuredAddressLine03": { "description": "If your unstructured address has more than 3 lines, input all the remaining in this line. Keep in mind that sending unstructured addresses will result to a lower matching rate", "type": "string", "example": "8004 Zurich Switzerland" }, "billRecipientId": { "description": "Bill recipient Id from eBill. Using in eBill channel only.
In order to deliver via eBill channel, you can input this credential. If you input more than 1 credential for eBill, delivery can happen only if all of these credentials are found in the recipient of eBill by SIX.", "type": "string", "example": "41010560425610173" } } }, "WindowLocation": { "enum": [ "LEFT", "RIGHT" ], "type": "string" }, "channel": { "description": "The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.", "enum": [ "EMAIL" ], "type": "string" }, "forcedOnboarding": { "description": "This object is optional. Defines whether all recipients of this document should be forced to register to ePost in order to receive this document. If the recipient is already registered to ePost, the normal delivery flow applies. If the recipient is not yet registered to ePost, we will send him an email asking him to register to ePost in order to receive the document. The document is stored for up to 60 days and will be delivered to the recipient as soon as he registers to ePost. After 60 days the delivery will expire.\nReminder emails are sent to the recipient after 2, 25, 40 and 55 days.\nForced onboarding is only available for the delivery channel DIGITAL. Additionally the unhashed credential EMAIL is required for forced onboarding (onboarding request email will be sent to this email address) and the minimum level of trust must be BRONZE.", "type": "object", "properties": { "channel": { "allOf": [ { "$ref": "#/components/schemas/channel" }, { "description": "The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.", "example": "EMAIL", "writeOnly": true } ] }, "language": { "allOf": [ { "$ref": "#/components/schemas/language" }, { "description": "Language of the recipient. Defines the language we will use in the email we send to the recipient with the request to onboard to ePost.", "example": "EN", "writeOnly": true } ] }, "emailToBeInformedWhenExpired": { "description": "This email address is used to inform the sender, in case the forced onboarding eLetter expires after 60 days (recipient didn't register) or should an error occur in the delivery of the forced onboarding eLetter.", "type": "string", "example": "peter.muster@gmail.com" } } }, "language": { "description": "Language of the recipient. Defines the language we will use in the email we send to the recipient with the request to onboard to ePost.", "enum": [ "EN", "DE", "FR", "IT" ], "type": "string" } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "name": "X-API-KEY", "in": "header" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }