ePost API documentation

operationId

createDelivery — the method name a generated client uses.

Request body

multipart/form-data DeliveryRequestV2

• files array of string (binary)
• largeFile object format: binary
  A binary file, users can push the binary via API document for testing.
  PDF binaries have to be delivered in the format PDF/A.
• metadata object
  Metadata of one delivery v2 contain list metadata of files.
  show fields

  • costCenter string
    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.
  • fileMetadata array of DocumentMetadataV2
    List of file's metadata
    show fields

    Array of DocumentMetadataV2.

    • allCredentialShouldMatch boolean
      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.
    • fileName string required
      Name of document file.
    • mediaType string example: application/vnd.ch.klara.epost.v1+iletter
      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.
    • deliveryChannelPreferences array of string required write-only
      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.
      
      
      The 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.
      
      
      If delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.
      
      
      DIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
      
      PHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
      
      SMS delivering the "simple short message" as a SMS to the recipient's mobile phone. (only for simple short message media type)
      
      EBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
      
      EMAIL delivering it to the recipient who using email
      
      AUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering
      Allowed values: DIGITAL, PHYSICAL, SMS, AUTO, EBILL, EMAIL
    • senderName string write-only example: Canton Bern
      This value will be shown to the recipient as the delivery sender name.
    • senderEndToEndId string write-only
      This id provided by the sender. It helps the sender to reference the document during the whole process.
    • senderCaseId string write-only
      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
    • documentReferenceDate string (date) format: date write-only example: 1990-01-02
      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.
      For eBill, The business case date can not be more than 90 days in the past and it can not be in the future.
    • documentTitle string example: nameOfTheFile
      This title will be shown to the recipient of the delivery on the application.
    • documentDescription string example: Your health check invitation with questionnaire.
      A short description of the document shown to the recipient as a preview text.
    • documentTypes array of string write-only
      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.
      Allowed values: message, invoice, contract, hr
    • recipients array of Recipient required minItems: 1
      Recipients's informations include hashed and unhashed datas for identity matching process.
      show fields

      Array of Recipient.

      • senderUserId string
        This id is for the sender to recognize the recipient.
      • hashedPrimaryCredential object example: email
        Type of the primary credential which is hashed.
      • hashedPrimaryValue string example: adu7adsfnn3489asdfn334jk
        Value of the primary credential.
      • derivedHashedCredentials array of string
        These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
        Allowed values: birthDate
      • derivedHashedValue string example: adu7adsfnn3489asdfn334jk
        This hash value is derived from the other value "hashedPrimaryValue".
      • unhashedCredentials object
        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).
        show fields

        • universalName string example: KLARA Business AG / Peter Muster
          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
        • firstName string example: Peter
          First name of a recipient.
        • lastName string example: Muster
          Last name of a recipient.
        • companyName string example: KLARA
          If the tenant entry is a business customer, i.e a Company, enter the company name here.
        • companyUid string example: CHE-123.456.789
          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.
        • street string example: Bahnhofstrasse 10a
          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.
        • streetNumber string example: 20
          Street number in the address of a recipient.
        • zipCode string example: 3000
          Zip code in the address of a recipient.
        • city string example: Bern
          City in the address of a recipient.
        • email string example: peter.muster@gmail.com
          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.
        • mobileNumber string example: +41909112233
          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.
        • birthDate string (date) format: date example: 1990-01-02
          Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)
        • participantId string
          This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.
        • clientLegacyId string
          This id is optional and is used to support legacy systems.
        • minimumLevelOfTrust object
          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 string example: 756.1234.5678.97
          Social security number of a recipient and must be unique.
        • taxId string example: 263125
          Tax ID of a recipient and must be unique.
        • postOfficeBoxNumber string example: 12
          Post office box number
        • postOfficeBoxZip string example: 1212
          Post office box zipcode
        • postOfficeBoxTownName string example: Vervey 1
          Post office box town name
        • unstructuredAddressLine01 string example: Peter Muster
          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
        • unstructuredAddressLine02 string example: Bahnhofsstr 20
          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
        • unstructuredAddressLine03 string example: 8004 Zurich Switzerland
          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
        • billRecipientId string example: 41010560425610173
          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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
    • allRecipientsRequired boolean
      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.
    • displayDeliveredDocument boolean
      When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle
    • documentMessage string example: Dear Peter Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one
      The message content of the simple short message
    • ebillAdditionalInfo EbillAdditionalInfo
      Group of the eBill delivery information.
      show fields

      • dueDate string (date) format: date write-only example: 2022-12-22
        Due date of business case
      • paymentAmount number write-only example: 20
        Amount to be paid for the invoice document
      • qrReference string write-only example: RF012345QF67T8910UI123
        Reference number in the invoice document, this field is referring to the QR Reference, as the biller should have provided a QR-IBAN.
    • emailAdditionalInfo EmailAdditionalInfo
      Group of the email delivery information.
      show fields

      • emailText string write-only example: Hello world.
        Content of the email.
      • emailHtml string write-only example: <html><h1>Hallo world</h1><br><img src="cid:picture1.png"/></html>
        Content of the email in html format.
      • emailSubject string write-only example: your invoice from KLARA
        Subject of the email.
      • sender object
        Contain email and its name
        show fields

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • replyTo array of AdditionalEmailInfo write-only
        Reply to the given emails.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • cc array of AdditionalEmailInfo write-only
        Sending email as cc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • bcc array of AdditionalEmailInfo write-only
        Sending email as bcc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • inlineImages array of EmailInlineImage
        Inline images of the email
        show fields

        Array of EmailInlineImage.

        • filename string required pattern: \S example: picture1.png
          filename of the inline image
        • base64 string required pattern: \S example: iVBORw0KGgoAAAANSUhEUgAAABkAAAAXCAYAAAD+4+QTAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQ
          file content of the inline image as base64.
    • digitalAdditionalInfo DigitalAdditionalInfo
      Group of the digital delivery information.
      show fields

      • digitalDeliveryVariant object example: STANDARD
        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]
      • letterAnswer string
        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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
      • documentInfoByLanguage object
        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.
        show fields

        • DE LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • FR LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • IT LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • EN LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
    • forcedOnboarding object
      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.
      show fields

      • channel object example: EMAIL
        The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.
      • language object example: EN
        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.
      • emailToBeInformedWhenExpired string example: peter.muster@gmail.com
        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.
    • physicalAdditionalInfo PhysicalAdditionalInfo
      Group of the physical delivery information.
      show fields

      • duplex boolean default: false example: False
        If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.
      • shippingCountry string default: CH example: CH
        The country which the sender customer can send letters to
        All acceptable country codes for shipping country.
      • envelopeSize object example: C5
        Size of the envelope (values: C4, C5, BOX, AUTO)
      • postage object example: A_POST
        Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)
      • qrInvoicePageNumber integer (int32) format: int32 default: 0 example: 0
        The qr Invoice page number
      • windowLocation object example: LEFT
        The position of the letter(values: LEFT, RIGHT)
      • coverPrinterLogoId string default: example: BKW.tif
        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.
      • attachment string default: example: myAttachment01.pdf
        Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.
      • senderAddress object
        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).
        show fields

        • name string example: ePost Service AG
          Sender name to be printed on the letter as part of the sender address.
        • street string example: Bahnhofstrasse
          Sender street to be printed on the letter as part of the sender address.
        • streetNumber string example: 20
          Sender street number to be printed on the letter as part of the sender address.
        • zipCode string example: 3000
          Sender zip code to be printed on the letter as part of the sender address.
        • city string example: Bern
          Sender city to be printed on the letter as part of the sender address.
  • featurePricePlan string
    This value is optional and is used for special pricing agreement between KLARA and the sender customer. For more information, please contact KLARA admin.
    
    If you don't have a value given by KLARA admin team, you can set it to null which will result in standard pricing.

Responses 6

operationId

getDeliveryStatus — the method name a generated client uses.

Parameters 1

Responses 5

operationId

getILetterResponseFileContent — the method name a generated client uses.

Parameters 2

Responses 7

operationId

createSynchronousDelivery — the method name a generated client uses.

Request body

multipart/form-data DeliveryRequestV21

• files array of string (binary)
• metadata object
  Metadata of one delivery v2 contain list metadata of files.
  show fields

  • costCenter string
    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.
  • fileMetadata array of DocumentMetadataV2
    List of file's metadata
    show fields

    Array of DocumentMetadataV2.

    • allCredentialShouldMatch boolean
      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.
    • fileName string required
      Name of document file.
    • mediaType string example: application/vnd.ch.klara.epost.v1+iletter
      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.
    • deliveryChannelPreferences array of string required write-only
      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.
      
      
      The 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.
      
      
      If delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.
      
      
      DIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
      
      PHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
      
      SMS delivering the "simple short message" as a SMS to the recipient's mobile phone. (only for simple short message media type)
      
      EBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
      
      EMAIL delivering it to the recipient who using email
      
      AUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering
      Allowed values: DIGITAL, PHYSICAL, SMS, AUTO, EBILL, EMAIL
    • senderName string write-only example: Canton Bern
      This value will be shown to the recipient as the delivery sender name.
    • senderEndToEndId string write-only
      This id provided by the sender. It helps the sender to reference the document during the whole process.
    • senderCaseId string write-only
      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
    • documentReferenceDate string (date) format: date write-only example: 1990-01-02
      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.
      For eBill, The business case date can not be more than 90 days in the past and it can not be in the future.
    • documentTitle string example: nameOfTheFile
      This title will be shown to the recipient of the delivery on the application.
    • documentDescription string example: Your health check invitation with questionnaire.
      A short description of the document shown to the recipient as a preview text.
    • documentTypes array of string write-only
      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.
      Allowed values: message, invoice, contract, hr
    • recipients array of Recipient required minItems: 1
      Recipients's informations include hashed and unhashed datas for identity matching process.
      show fields

      Array of Recipient.

      • senderUserId string
        This id is for the sender to recognize the recipient.
      • hashedPrimaryCredential object example: email
        Type of the primary credential which is hashed.
      • hashedPrimaryValue string example: adu7adsfnn3489asdfn334jk
        Value of the primary credential.
      • derivedHashedCredentials array of string
        These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
        Allowed values: birthDate
      • derivedHashedValue string example: adu7adsfnn3489asdfn334jk
        This hash value is derived from the other value "hashedPrimaryValue".
      • unhashedCredentials object
        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).
        show fields

        • universalName string example: KLARA Business AG / Peter Muster
          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
        • firstName string example: Peter
          First name of a recipient.
        • lastName string example: Muster
          Last name of a recipient.
        • companyName string example: KLARA
          If the tenant entry is a business customer, i.e a Company, enter the company name here.
        • companyUid string example: CHE-123.456.789
          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.
        • street string example: Bahnhofstrasse 10a
          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.
        • streetNumber string example: 20
          Street number in the address of a recipient.
        • zipCode string example: 3000
          Zip code in the address of a recipient.
        • city string example: Bern
          City in the address of a recipient.
        • email string example: peter.muster@gmail.com
          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.
        • mobileNumber string example: +41909112233
          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.
        • birthDate string (date) format: date example: 1990-01-02
          Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)
        • participantId string
          This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.
        • clientLegacyId string
          This id is optional and is used to support legacy systems.
        • minimumLevelOfTrust object
          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 string example: 756.1234.5678.97
          Social security number of a recipient and must be unique.
        • taxId string example: 263125
          Tax ID of a recipient and must be unique.
        • postOfficeBoxNumber string example: 12
          Post office box number
        • postOfficeBoxZip string example: 1212
          Post office box zipcode
        • postOfficeBoxTownName string example: Vervey 1
          Post office box town name
        • unstructuredAddressLine01 string example: Peter Muster
          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
        • unstructuredAddressLine02 string example: Bahnhofsstr 20
          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
        • unstructuredAddressLine03 string example: 8004 Zurich Switzerland
          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
        • billRecipientId string example: 41010560425610173
          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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
    • allRecipientsRequired boolean
      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.
    • displayDeliveredDocument boolean
      When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle
    • documentMessage string example: Dear Peter Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one
      The message content of the simple short message
    • ebillAdditionalInfo EbillAdditionalInfo
      Group of the eBill delivery information.
      show fields

      • dueDate string (date) format: date write-only example: 2022-12-22
        Due date of business case
      • paymentAmount number write-only example: 20
        Amount to be paid for the invoice document
      • qrReference string write-only example: RF012345QF67T8910UI123
        Reference number in the invoice document, this field is referring to the QR Reference, as the biller should have provided a QR-IBAN.
    • emailAdditionalInfo EmailAdditionalInfo
      Group of the email delivery information.
      show fields

      • emailText string write-only example: Hello world.
        Content of the email.
      • emailHtml string write-only example: <html><h1>Hallo world</h1><br><img src="cid:picture1.png"/></html>
        Content of the email in html format.
      • emailSubject string write-only example: your invoice from KLARA
        Subject of the email.
      • sender object
        Contain email and its name
        show fields

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • replyTo array of AdditionalEmailInfo write-only
        Reply to the given emails.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • cc array of AdditionalEmailInfo write-only
        Sending email as cc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • bcc array of AdditionalEmailInfo write-only
        Sending email as bcc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • inlineImages array of EmailInlineImage
        Inline images of the email
        show fields

        Array of EmailInlineImage.

        • filename string required pattern: \S example: picture1.png
          filename of the inline image
        • base64 string required pattern: \S example: iVBORw0KGgoAAAANSUhEUgAAABkAAAAXCAYAAAD+4+QTAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQ
          file content of the inline image as base64.
    • digitalAdditionalInfo DigitalAdditionalInfo
      Group of the digital delivery information.
      show fields

      • digitalDeliveryVariant object example: STANDARD
        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]
      • letterAnswer string
        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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
      • documentInfoByLanguage object
        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.
        show fields

        • DE LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • FR LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • IT LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • EN LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
    • forcedOnboarding object
      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.
      show fields

      • channel object example: EMAIL
        The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.
      • language object example: EN
        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.
      • emailToBeInformedWhenExpired string example: peter.muster@gmail.com
        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.
    • physicalAdditionalInfo PhysicalAdditionalInfo
      Group of the physical delivery information.
      show fields

      • duplex boolean default: false example: False
        If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.
      • shippingCountry string default: CH example: CH
        The country which the sender customer can send letters to
        All acceptable country codes for shipping country.
      • envelopeSize object example: C5
        Size of the envelope (values: C4, C5, BOX, AUTO)
      • postage object example: A_POST
        Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)
      • qrInvoicePageNumber integer (int32) format: int32 default: 0 example: 0
        The qr Invoice page number
      • windowLocation object example: LEFT
        The position of the letter(values: LEFT, RIGHT)
      • coverPrinterLogoId string default: example: BKW.tif
        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.
      • attachment string default: example: myAttachment01.pdf
        Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.
      • senderAddress object
        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).
        show fields

        • name string example: ePost Service AG
          Sender name to be printed on the letter as part of the sender address.
        • street string example: Bahnhofstrasse
          Sender street to be printed on the letter as part of the sender address.
        • streetNumber string example: 20
          Sender street number to be printed on the letter as part of the sender address.
        • zipCode string example: 3000
          Sender zip code to be printed on the letter as part of the sender address.
        • city string example: Bern
          Sender city to be printed on the letter as part of the sender address.
  • featurePricePlan string
    This value is optional and is used for special pricing agreement between KLARA and the sender customer. For more information, please contact KLARA admin.
    
    If you don't have a value given by KLARA admin team, you can set it to null which will result in standard pricing.

Responses 6

operationId

createDeliveryChannelPreview — the method name a generated client uses.

Parameters 1

Request body required

multipart/form-data OneApiPreviewRequest

• files array of string (binary)
• largeFile object format: binary
  A binary file, users can push the binary via API document for testing.
  PDF binaries have to be delivered in the format PDF/A.
• metadata object
  Metadata of one delivery v2 contain list metadata of files.
  show fields

  • costCenter string
    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.
  • fileMetadata array of DocumentMetadataV2
    List of file's metadata
    show fields

    Array of DocumentMetadataV2.

    • allCredentialShouldMatch boolean
      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.
    • fileName string required
      Name of document file.
    • mediaType string example: application/vnd.ch.klara.epost.v1+iletter
      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.
    • deliveryChannelPreferences array of string required write-only
      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.
      
      
      The 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.
      
      
      If delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.
      
      
      DIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
      
      PHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
      
      SMS delivering the "simple short message" as a SMS to the recipient's mobile phone. (only for simple short message media type)
      
      EBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
      
      EMAIL delivering it to the recipient who using email
      
      AUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering
      Allowed values: DIGITAL, PHYSICAL, SMS, AUTO, EBILL, EMAIL
    • senderName string write-only example: Canton Bern
      This value will be shown to the recipient as the delivery sender name.
    • senderEndToEndId string write-only
      This id provided by the sender. It helps the sender to reference the document during the whole process.
    • senderCaseId string write-only
      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
    • documentReferenceDate string (date) format: date write-only example: 1990-01-02
      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.
      For eBill, The business case date can not be more than 90 days in the past and it can not be in the future.
    • documentTitle string example: nameOfTheFile
      This title will be shown to the recipient of the delivery on the application.
    • documentDescription string example: Your health check invitation with questionnaire.
      A short description of the document shown to the recipient as a preview text.
    • documentTypes array of string write-only
      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.
      Allowed values: message, invoice, contract, hr
    • recipients array of Recipient required minItems: 1
      Recipients's informations include hashed and unhashed datas for identity matching process.
      show fields

      Array of Recipient.

      • senderUserId string
        This id is for the sender to recognize the recipient.
      • hashedPrimaryCredential object example: email
        Type of the primary credential which is hashed.
      • hashedPrimaryValue string example: adu7adsfnn3489asdfn334jk
        Value of the primary credential.
      • derivedHashedCredentials array of string
        These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
        Allowed values: birthDate
      • derivedHashedValue string example: adu7adsfnn3489asdfn334jk
        This hash value is derived from the other value "hashedPrimaryValue".
      • unhashedCredentials object
        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).
        show fields

        • universalName string example: KLARA Business AG / Peter Muster
          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
        • firstName string example: Peter
          First name of a recipient.
        • lastName string example: Muster
          Last name of a recipient.
        • companyName string example: KLARA
          If the tenant entry is a business customer, i.e a Company, enter the company name here.
        • companyUid string example: CHE-123.456.789
          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.
        • street string example: Bahnhofstrasse 10a
          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.
        • streetNumber string example: 20
          Street number in the address of a recipient.
        • zipCode string example: 3000
          Zip code in the address of a recipient.
        • city string example: Bern
          City in the address of a recipient.
        • email string example: peter.muster@gmail.com
          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.
        • mobileNumber string example: +41909112233
          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.
        • birthDate string (date) format: date example: 1990-01-02
          Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)
        • participantId string
          This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.
        • clientLegacyId string
          This id is optional and is used to support legacy systems.
        • minimumLevelOfTrust object
          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 string example: 756.1234.5678.97
          Social security number of a recipient and must be unique.
        • taxId string example: 263125
          Tax ID of a recipient and must be unique.
        • postOfficeBoxNumber string example: 12
          Post office box number
        • postOfficeBoxZip string example: 1212
          Post office box zipcode
        • postOfficeBoxTownName string example: Vervey 1
          Post office box town name
        • unstructuredAddressLine01 string example: Peter Muster
          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
        • unstructuredAddressLine02 string example: Bahnhofsstr 20
          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
        • unstructuredAddressLine03 string example: 8004 Zurich Switzerland
          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
        • billRecipientId string example: 41010560425610173
          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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
    • allRecipientsRequired boolean
      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.
    • displayDeliveredDocument boolean
      When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle
    • documentMessage string example: Dear Peter Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one
      The message content of the simple short message
    • ebillAdditionalInfo EbillAdditionalInfo
      Group of the eBill delivery information.
      show fields

      • dueDate string (date) format: date write-only example: 2022-12-22
        Due date of business case
      • paymentAmount number write-only example: 20
        Amount to be paid for the invoice document
      • qrReference string write-only example: RF012345QF67T8910UI123
        Reference number in the invoice document, this field is referring to the QR Reference, as the biller should have provided a QR-IBAN.
    • emailAdditionalInfo EmailAdditionalInfo
      Group of the email delivery information.
      show fields

      • emailText string write-only example: Hello world.
        Content of the email.
      • emailHtml string write-only example: <html><h1>Hallo world</h1><br><img src="cid:picture1.png"/></html>
        Content of the email in html format.
      • emailSubject string write-only example: your invoice from KLARA
        Subject of the email.
      • sender object
        Contain email and its name
        show fields

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • replyTo array of AdditionalEmailInfo write-only
        Reply to the given emails.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • cc array of AdditionalEmailInfo write-only
        Sending email as cc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • bcc array of AdditionalEmailInfo write-only
        Sending email as bcc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • inlineImages array of EmailInlineImage
        Inline images of the email
        show fields

        Array of EmailInlineImage.

        • filename string required pattern: \S example: picture1.png
          filename of the inline image
        • base64 string required pattern: \S example: iVBORw0KGgoAAAANSUhEUgAAABkAAAAXCAYAAAD+4+QTAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQ
          file content of the inline image as base64.
    • digitalAdditionalInfo DigitalAdditionalInfo
      Group of the digital delivery information.
      show fields

      • digitalDeliveryVariant object example: STANDARD
        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]
      • letterAnswer string
        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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
      • documentInfoByLanguage object
        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.
        show fields

        • DE LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • FR LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • IT LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • EN LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
    • forcedOnboarding object
      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.
      show fields

      • channel object example: EMAIL
        The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.
      • language object example: EN
        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.
      • emailToBeInformedWhenExpired string example: peter.muster@gmail.com
        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.
    • physicalAdditionalInfo PhysicalAdditionalInfo
      Group of the physical delivery information.
      show fields

      • duplex boolean default: false example: False
        If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.
      • shippingCountry string default: CH example: CH
        The country which the sender customer can send letters to
        All acceptable country codes for shipping country.
      • envelopeSize object example: C5
        Size of the envelope (values: C4, C5, BOX, AUTO)
      • postage object example: A_POST
        Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)
      • qrInvoicePageNumber integer (int32) format: int32 default: 0 example: 0
        The qr Invoice page number
      • windowLocation object example: LEFT
        The position of the letter(values: LEFT, RIGHT)
      • coverPrinterLogoId string default: example: BKW.tif
        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.
      • attachment string default: example: myAttachment01.pdf
        Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.
      • senderAddress object
        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).
        show fields

        • name string example: ePost Service AG
          Sender name to be printed on the letter as part of the sender address.
        • street string example: Bahnhofstrasse
          Sender street to be printed on the letter as part of the sender address.
        • streetNumber string example: 20
          Sender street number to be printed on the letter as part of the sender address.
        • zipCode string example: 3000
          Sender zip code to be printed on the letter as part of the sender address.
        • city string example: Bern
          Sender city to be printed on the letter as part of the sender address.

Responses 6

operationId

getDeliveryChannelPreviewStatus — the method name a generated client uses.

Parameters 1

Responses 5

operationId

createDeliveryPricePreview — the method name a generated client uses.

Parameters 1

Request body

multipart/form-data PreviewDeliveryRequestV2

• files array of string (binary)
• largeFile object format: binary
  A binary file, users can push the binary via API document for testing.
  PDF binaries have to be delivered in the format PDF/A.
• metadata object
  Metadata of one delivery v2 contain list metadata of files for preview service.
  show fields

  • costCenter string
    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.
  • fileMetadata array of DocumentMetadataV2ForPreviewService
    List of file's metadata
    show fields

    Array of DocumentMetadataV2ForPreviewService.

    • allCredentialShouldMatch boolean
      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.
    • fileName string required
      Name of document file.
    • mediaType string example: application/vnd.ch.klara.epost.v1+iletter
      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.
    • deliveryChannelPreferences array of string required write-only
      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.
      
      
      The 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.
      
      
      If delivery is not successful via any of the delivery methods, then an error response will be returned to the sender.
      
      
      DIGITAL delivering it to the recipient's ePost letterbox (available for all types of documents/letters/messages)
      
      PHYSICAL printing and sending the letter physically (only specific pdf formats are accepted)
      
      SMS delivering the "simple short message" as a SMS to the recipient's mobile phone. (only for simple short message media type)
      
      EBILL delivering it to the recipient's eBill (available for invoice document type with pdf format)
      
      EMAIL delivering it to the recipient who using email
      
      AUTO will try to find most suitable one from all available channel in order like this (DIGITAL, SMS, EBILL, PHYSICAL, EMAIL) then do the delivering
      Allowed values: DIGITAL, PHYSICAL, SMS, AUTO, EBILL, EMAIL
    • senderName string write-only example: Canton Bern
      This value will be shown to the recipient as the delivery sender name.
    • senderEndToEndId string write-only
      This id provided by the sender. It helps the sender to reference the document during the whole process.
    • senderCaseId string write-only
      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
    • documentReferenceDate string (date) format: date write-only example: 1990-01-02
      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.
      For eBill, The business case date can not be more than 90 days in the past and it can not be in the future.
    • documentTitle string example: nameOfTheFile
      This title will be shown to the recipient of the delivery on the application.
    • documentDescription string example: Your health check invitation with questionnaire.
      A short description of the document shown to the recipient as a preview text.
    • documentTypes array of string write-only
      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.
      Allowed values: message, invoice, contract, hr
    • recipients array of Recipient required minItems: 1
      Recipients's informations include hashed and unhashed datas for identity matching process.
      show fields

      Array of Recipient.

      • senderUserId string
        This id is for the sender to recognize the recipient.
      • hashedPrimaryCredential object example: email
        Type of the primary credential which is hashed.
      • hashedPrimaryValue string example: adu7adsfnn3489asdfn334jk
        Value of the primary credential.
      • derivedHashedCredentials array of string
        These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
        Allowed values: birthDate
      • derivedHashedValue string example: adu7adsfnn3489asdfn334jk
        This hash value is derived from the other value "hashedPrimaryValue".
      • unhashedCredentials object
        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).
        show fields

        • universalName string example: KLARA Business AG / Peter Muster
          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
        • firstName string example: Peter
          First name of a recipient.
        • lastName string example: Muster
          Last name of a recipient.
        • companyName string example: KLARA
          If the tenant entry is a business customer, i.e a Company, enter the company name here.
        • companyUid string example: CHE-123.456.789
          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.
        • street string example: Bahnhofstrasse 10a
          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.
        • streetNumber string example: 20
          Street number in the address of a recipient.
        • zipCode string example: 3000
          Zip code in the address of a recipient.
        • city string example: Bern
          City in the address of a recipient.
        • email string example: peter.muster@gmail.com
          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.
        • mobileNumber string example: +41909112233
          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.
        • birthDate string (date) format: date example: 1990-01-02
          Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)
        • participantId string
          This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.
        • clientLegacyId string
          This id is optional and is used to support legacy systems.
        • minimumLevelOfTrust object
          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 string example: 756.1234.5678.97
          Social security number of a recipient and must be unique.
        • taxId string example: 263125
          Tax ID of a recipient and must be unique.
        • postOfficeBoxNumber string example: 12
          Post office box number
        • postOfficeBoxZip string example: 1212
          Post office box zipcode
        • postOfficeBoxTownName string example: Vervey 1
          Post office box town name
        • unstructuredAddressLine01 string example: Peter Muster
          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
        • unstructuredAddressLine02 string example: Bahnhofsstr 20
          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
        • unstructuredAddressLine03 string example: 8004 Zurich Switzerland
          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
        • billRecipientId string example: 41010560425610173
          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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
    • allRecipientsRequired boolean
      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.
    • displayDeliveredDocument boolean
      When this flag true, the delivered document with show more information like senderEndToEndId, senderUserId and documentTitle
    • documentMessage string example: Dear Peter Your appointment on 28.05.2022 has been cancelled. Please contact us to arrange a new one
      The message content of the simple short message
    • ebillAdditionalInfo EbillAdditionalInfo
      Group of the eBill delivery information.
      show fields

      • dueDate string (date) format: date write-only example: 2022-12-22
        Due date of business case
      • paymentAmount number write-only example: 20
        Amount to be paid for the invoice document
      • qrReference string write-only example: RF012345QF67T8910UI123
        Reference number in the invoice document, this field is referring to the QR Reference, as the biller should have provided a QR-IBAN.
    • emailAdditionalInfo EmailAdditionalInfo
      Group of the email delivery information.
      show fields

      • emailText string write-only example: Hello world.
        Content of the email.
      • emailHtml string write-only example: <html><h1>Hallo world</h1><br><img src="cid:picture1.png"/></html>
        Content of the email in html format.
      • emailSubject string write-only example: your invoice from KLARA
        Subject of the email.
      • sender object
        Contain email and its name
        show fields

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • replyTo array of AdditionalEmailInfo write-only
        Reply to the given emails.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • cc array of AdditionalEmailInfo write-only
        Sending email as cc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • bcc array of AdditionalEmailInfo write-only
        Sending email as bcc list.
        show fields

        Array of AdditionalEmailInfo.

        • email string write-only example: abc@klara.ch
          Email address
        • name string write-only example: ABC
          Name of email
      • inlineImages array of EmailInlineImage
        Inline images of the email
        show fields

        Array of EmailInlineImage.

        • filename string required pattern: \S example: picture1.png
          filename of the inline image
        • base64 string required pattern: \S example: iVBORw0KGgoAAAANSUhEUgAAABkAAAAXCAYAAAD+4+QTAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQ
          file content of the inline image as base64.
    • digitalAdditionalInfo DigitalAdditionalInfo
      Group of the digital delivery information.
      show fields

      • digitalDeliveryVariant object example: STANDARD
        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]
      • letterAnswer string
        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.
      • iLetter object
        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.
        show fields

        • templateId string required maxLength: 128
          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.
        • batchId string maxLength: 128
          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.
        • confidentialResponses boolean
          Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
        • responseDeadline string
          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.
        • parameters array of ILetterParameter maxItems: 20
          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.
          show fields

          Array of ILetterParameter.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 128
            The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
        • placeholders array of ILetterPlaceholder maxItems: 100
          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.
          show fields

          Array of ILetterPlaceholder.

          • key string required maxLength: 64 pattern: \S
            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.
          • value string maxLength: 2000
            Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
      • documentInfoByLanguage object
        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.
        show fields

        • DE LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • FR LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • IT LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
        • EN LocalizedDocumentInfo
          show fields

          • title string example: Ihr Schadenfall
            Title shown to a recipient whose letterbox language matches this entry's key.
          • description string
            Description shown to a recipient whose letterbox language matches this entry's key.
    • physicalAdditionalInfo object
      Additional info support for preview pricing service.
      show fields

      • duplex boolean default: false example: False
        If this flag is true, the Printer will print the document as both sides, otherwise just 1 side.
      • shippingCountry string default: CH example: CH
        The country which the sender customer can send letters to
        All acceptable country codes for shipping country.
      • envelopeSize object example: C5
        Size of the envelope (values: C4, C5, BOX, AUTO)
      • postage object example: A_POST
        Type of physical delivery (values: A_POST, A_PLUS, B_POST, B_POST_LARGEVOLUME, REGISTERED)
      • qrInvoicePageNumber integer (int32) format: int32 default: 0 example: 0
        The qr Invoice page number
      • windowLocation object example: LEFT
        The position of the letter(values: LEFT, RIGHT)
      • coverPrinterLogoId string default: example: BKW.tif
        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.
      • attachment string default: example: myAttachment01.pdf
        Optional field. This field is used to inform the print partner to add the attachment to the letter coming from oneAPI.
      • senderAddress object
        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).
        show fields

        • name string example: ePost Service AG
          Sender name to be printed on the letter as part of the sender address.
        • street string example: Bahnhofstrasse
          Sender street to be printed on the letter as part of the sender address.
        • streetNumber string example: 20
          Sender street number to be printed on the letter as part of the sender address.
        • zipCode string example: 3000
          Sender zip code to be printed on the letter as part of the sender address.
        • city string example: Bern
          Sender city to be printed on the letter as part of the sender address.
      • numberOfPage integer (int32) format: int32
        Number of document page should be provided if no file uploaded
    • forcedOnboarding object
      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.
      show fields

      • channel object example: EMAIL
        The channel we will use to contact the recipient with the request to onboard to ePost. Currently, only EMAIL is supported.
      • language object example: EN
        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.
      • emailToBeInformedWhenExpired string example: peter.muster@gmail.com
        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.

Responses 6

operationId

getDeliveryPricePreviewStatus — the method name a generated client uses.

Parameters 1

Responses 6

operationId

listDeliveryMonitoringData — the method name a generated client uses.

Parameters 4

Responses 5

operationId

createStandardMatchingRun — the method name a generated client uses.

Request body required

application/json RecipientInfo

• recipients array of IdentityMatchingRecipient required minItems: 1 maxItems: 50000
  show fields

  Array of IdentityMatchingRecipient.

  • senderUserId string
    This id is for the sender to recognize the recipient.
  • hashedPrimaryCredential object example: email
    Type of the primary credential which is hashed.
  • hashedPrimaryValue string example: adu7adsfnn3489asdfn334jk
    Value of the primary credential.
  • derivedHashedCredentials array of string
    These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
    Allowed values: birthDate
  • derivedHashedValue string example: adu7adsfnn3489asdfn334jk
    This hash value is derived from the other value "hashedPrimaryValue".
  • unhashedCredentials object
    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).
    show fields

    • universalName string example: KLARA Business AG / Peter Muster
      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
    • firstName string example: Peter
      First name of a recipient.
    • lastName string example: Muster
      Last name of a recipient.
    • companyName string example: KLARA
      If the tenant entry is a business customer, i.e a Company, enter the company name here.
    • companyUid string example: CHE-123.456.789
      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.
    • street string example: Bahnhofstrasse 10a
      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.
    • streetNumber string example: 20
      Street number in the address of a recipient.
    • zipCode string example: 3000
      Zip code in the address of a recipient.
    • city string example: Bern
      City in the address of a recipient.
    • email string example: peter.muster@gmail.com
      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.
    • mobileNumber string example: +41909112233
      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.
    • birthDate string (date) format: date example: 1990-01-02
      Birth date of a recipient in ISO 8601 format (yyyy-mm-dd)
    • participantId string
      This field is result of identity matching process, if value is entered in request then it will have highest priority for matching search process.
    • clientLegacyId string
      This id is optional and is used to support legacy systems.
    • minimumLevelOfTrust object
      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 string example: 756.1234.5678.97
      Social security number of a recipient and must be unique.
    • taxId string example: 263125
      Tax ID of a recipient and must be unique.
    • postOfficeBoxNumber string example: 12
      Post office box number
    • postOfficeBoxZip string example: 1212
      Post office box zipcode
    • postOfficeBoxTownName string example: Vervey 1
      Post office box town name
    • unstructuredAddressLine01 string example: Peter Muster
      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
    • unstructuredAddressLine02 string example: Bahnhofsstr 20
      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
    • unstructuredAddressLine03 string example: 8004 Zurich Switzerland
      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
    • billRecipientId string example: 41010560425610173
      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.
  • iLetter object
    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.
    show fields

    • templateId string required maxLength: 128
      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.
    • batchId string maxLength: 128
      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.
    • confidentialResponses boolean
      Whether the iLetter collects confidential responses: answers are not shown to the sender together with who gave them. Defaults to not confidential when absent.
    • responseDeadline string
      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.
    • parameters array of ILetterParameter maxItems: 20
      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.
      show fields

      Array of ILetterParameter.

      • key string required maxLength: 64 pattern: \S
        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.
      • value string maxLength: 128
        The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
    • placeholders array of ILetterPlaceholder maxItems: 100
      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.
      show fields

      Array of ILetterPlaceholder.

      • key string required maxLength: 64 pattern: \S
        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.
      • value string maxLength: 2000
        Text shown to the recipient in place of the placeholder. Any characters, including line breaks; at most 2000 characters.
  • allCredentialShouldMatch boolean
    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.