---
title: "Identity matching process. Standard version just return the user's basic information."
method: POST
path: "/epost/v2/standard-matchings"
tags: ["Standard ePost Digital Letterbox Identity Matching"]
---

# Identity matching process. Standard version just return the user's basic information.

`POST /epost/v2/standard-matchings`

## Request

- Base URL: `https://api.klara.ch`
- URL: `https://api.klara.ch/epost/v2/standard-matchings`
- Auth: one of:
  - API key in header `X-API-KEY`
  - HTTP bearer

Send metadata of your customers for matching them with ePost users. The limit size of the metadata is 5 There is the possibility to hash the metadata before sending it. It isn't mandatory to send all data for identity matching, but the sent data has to be unique in it's combination.

## Request body

- RecipientInfo
  - `recipients` IdentityMatchingRecipient[], required
    - `senderUserId` string: This id is for the sender to recognize the recipient.
    - `hashedPrimaryCredential` 'email' | 'postaladdress' | 'mobilenumber': Type of the primary credential which is hashed.
    - `hashedPrimaryValue` string: Value of the primary credential.
    - `derivedHashedCredentials` DerivedHashedCredentialType[]: These are credentials that are hashed but aren't "Primary Credentials". There could be more than one credential.
    - `derivedHashedValue` string: This hash value is derived from the other value "hashedPrimaryValue".
    - `unhashedCredentials` object: Unhashed credential for identity matching process.
      - `universalName` string: 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: First name of a recipient.
      - `lastName` string: Last name of a recipient.
      - `companyName` string: If the tenant entry is a business customer, i.e a Company, enter the company name here.
      - `companyUid` string: If the tenant entry is a business customer, i.e a Company, enter the company UID here.<br/>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: Street name in the address of a recipient.<br/>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: Street number in the address of a recipient.
      - `zipCode` string: Zip code in the address of a recipient.
      - `city` string: City in the address of a recipient.
      - `email` string: Email of a recipient.<br/>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: Mobile number of the recipient.<br/>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: 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` 'BRONZE' | 'SILVER' | 'GOLD': 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: Social security number of a recipient and must be unique.
      - `taxId` string: Tax ID of a recipient and must be unique.
      - `postOfficeBoxNumber` string: Post office box number
      - `postOfficeBoxZip` string: Post office box zipcode
      - `postOfficeBoxTownName` string: Post office box town name
      - `unstructuredAddressLine01` string: 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: 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: 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: Bill recipient Id from eBill. Using in eBill channel only.<br/>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: Only parameters and placeholders are considered here: each overrides, per key, the document-level digitalAdditionalInfo.iLetter value of the same name for this one recipient.
      - `templateId` string, required: 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: Optional correlation key grouping several deliveries onto 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` ILetterParameter[]: 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.
        - `key` string, required: 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: The value substituted for this key when the recipient's iLetter resolves the data source. At most 128 characters.
      - `placeholders` ILetterPlaceholder[]: 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.
        - `key` string, required: 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: 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.<br />If not specified, then default value of TRUE will be used.

## Response `200`

Get matched users

- StandardMatchingResponse[]
  - `matchedRecipients` StandardRecipientResponse[]: This list contain the recipient basic info which matched with given information.
    - `senderUserId` string: This id is for the sender to recognize the recipient.
    - `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.
    - `communityId` string: The recipient's community ID (Matrix ID) for individual tenants active in the ePost community. Omitted when the recipient is not an individual or has no community account.
  - `nonMatchedSenderUserIds` string[]: This list contain the non-matched recipient.

## Other responses

- `400`: Data invalid<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</code> field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.
- `401`: No Authorization header found or invalid token<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</code> field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.
- `429`: API rate limit exceeded<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</code> field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list.

---

[API](https://skmtc.dev/klara/apis/klara-public-api.md) · [All operations](https://skmtc.dev/klara/apis/klara-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/klara/apis/klara-public-api/revisions/490b1a879fc2?raw)