ePost Sign

Update a participant of a running signing process (ADMIN-only).

ADMIN-only update of a single participant. Callable by the process creator or by <strong>any active participant that holds the <code>ADMIN</code> role</strong> (LUZ-158618). Only reachable while the participant is <code>PENDING</code> or <code>FORCED_ONBOARDING</code> — once the participant has <code>SIGNED</code>, <code>REJECTED</code>, <code>EXPIRED</code> or has already been <code>REMOVED</code>, the request is rejected with HTTP 409. All fields on the body are optional; field-level diffing is applied and an audit trail entry (<code>PARTICIPANT_UPDATED</code>) is written only when at least one value actually changed.<br/><br/><strong>Removal</strong>: send <code>status = REMOVED</code> to remove the participant from the process. Records a <code>PARTICIPANT_REMOVED</code> audit trail entry. Any other status value is rejected with HTTP 400.<br/><br/><strong>Credential-change re-matching (LUZ-158618)</strong>: changing any credential field — <code>hashedPrimaryCredential</code>, <code>hashedPrimaryValue</code>, <code>derivedHashedCredentials</code>, <code>derivedHashedValue</code>, <code>unhashedCredentials</code>, or <code>allCredentialShouldMatch</code> — re-runs tenant-directory matching for this participant slot. If the resolved recipient changes, the previously-resolved tenant is remembered (so their subsequent sign attempts are rejected with <code>REMOVED_BY_SENDER</code>) and the initial signing notification is re-delivered to the newly resolved recipient. The previous recipient's letterbox entry is intentionally <strong>NOT</strong> withdrawn. If the new credential matches multiple accounts the request is rejected with HTTP 422.<br/><br/><strong>Last-ADMIN protection</strong>: removing the last <code>ADMIN</code> — or stripping the <code>ADMIN</code> role from the last <code>ADMIN</code> by supplying a <code>roles</code> list that does not contain <code>ADMIN</code> — is rejected with HTTP 409; the participant is left unchanged. Callers that are not an <code>ADMIN</code> participant of this process receive HTTP 404 (the existence of the process is not disclosed). Access requires the ePost Sign widget subscription.

patch/epost/signing/processes/{processId}/participants/{participantId}

Request

  • Base URL: https://api.klara.ch
  • URL: https://api.klara.ch/epost/signing/processes/{processId}/participants/{participantId}
  • Auth: one of:
    • API key in header X-API-KEY
    • HTTP bearer

Path parameters

participantIdstring uuid required
Example:b4a9b3f1-c8d0-4e2a-b5f6-b7c8d9e0a1b2

Process-local participant id (stable, also while the participant is unresolved). Matches <code>ParticipantStatus.internalTrackingId</code> from the <code>GET</code> view.

processIdstring uuid required
Example:6c2df3c0-5b1a-4c92-9c46-3b8a9e0e2d51

Server-assigned unique identifier of the signing process.

Request body

rolesstring[]

New role set. Must be non-empty when supplied. The process must retain at least one <code>ADMIN</code> and at least one <code>SIGNER</code>; removing the last <code>ADMIN</code> results in HTTP 409.

hashedPrimaryCredentialstring

Which credential is hashed as the primary key (e.g. <code>email</code>, <code>mobileNumber</code>). Omit to keep the current value.

hashedPrimaryValuestring

Hash of the primary credential value. Omit to keep the current value.

derivedHashedCredentialsstring[]

Names of the additional credentials mixed into the derived hash. Omit to keep the current value.

derivedHashedValuestring

Hash of the derived credential combination. Omit to keep the current value.

allCredentialShouldMatchboolean

If <code>true</code>, every supplied credential MUST match to resolve the participant. Omit to keep the current value.

sequenceIndexinteger

1-based order of this participant when the process runs in <code>SEQUENTIAL</code> mode. Ignored in <code>PARALLEL</code> mode. Omit to keep the current value.

statusobject

Only <code>REMOVED</code> is accepted — removes the participant from the process. Any other value results in HTTP 400. Only reachable while the participant is <code>PENDING</code> or <code>FORCED_ONBOARDING</code>.

Example request

{
  "roles": [
    "SIGNER",
    "RECEIVER"
  ],
  "hashedPrimaryCredential": "email",
  "hashedPrimaryValue": "5f4dcc3b5aa765d61d8327deb882cf99",
  "derivedHashedCredentials": [
    "birthDate"
  ],
  "derivedHashedValue": "b4a9b3f1c8d0e2a5f6b7c8d9e0a1b2c3",
  "unhashedCredentials": {
    "universalName": "KLARA Business AG / Peter Muster",
    "firstName": "Peter",
    "lastName": "Muster",
    "companyName": "KLARA",
    "companyUid": "CHE-123.456.789",
    "street": "Bahnhofstrasse 10a",
    "streetNumber": "20",
    "zipCode": "3000",
    "city": "Bern",
    "email": "peter.muster@gmail.com",
    "mobileNumber": " +41909112233",
    "birthDate": "1990-01-02",
    "socialSecurityNumber": "756.1234.5678.97",
    "taxId": "263125",
    "postOfficeBoxNumber": "12",
    "postOfficeBoxZip": "1212",
    "postOfficeBoxTownName": "Vervey 1",
    "unstructuredAddressLine01": "Peter Muster",
    "unstructuredAddressLine02": "Bahnhofsstr 20",
    "unstructuredAddressLine03": "8004 Zurich Switzerland",
    "billRecipientId": "41010560425610173"
  },
  "sequenceIndex": 1,
  "signatureFields": [
    {
      "fieldName": "SignatureField_1",
      "x": 72,
      "y": 144,
      "width": 180,
      "height": 48
    }
  ]
}

Response

Updated participant.

internalTrackingIdstring uuid

Process-local participant id. Stable, also while the participant is unresolved. Use this to address the participant on <code>PATCH</code>.

participantIdstring nullable

Internal ePost id of the resolved tenant. <code>null</code> while the participant cannot be resolved (e.g. forced onboarding pending, address-only credential).

namestring nullable

Name as used within the signing process / signature itself. <code>null</code> while unresolved. Per CISO, no additional profile data from ePost is exposed here.

rolesstring[]

Role(s) held by this participant within the process.

statusobject

Current signing status of this participant.

deliveryStatusobject nullable

Delivery progress of the initial document to this participant, independent of the signing <code>status</code> above.

hashedPrimaryValuestring nullable

Correlates the returned participant with the hash the caller submitted.

signedByUserEmailstring nullable

Email of the ePost account in whose name the signature was made (account owner). <code>null</code> before signing.

effectiveSignerUserEmailstring nullable

Email of the user who actually signed (e.g. a shared-account user). <code>null</code> before signing.

sequenceIndexinteger nullable

1-based order (<code>SEQUENTIAL</code> mode). <code>null</code> in <code>PARALLEL</code> mode.

rejectedReasonstring nullable

Reason provided when the participant refused to sign. <code>null</code> otherwise.

signedAtstring date-time nullable

Timestamp at which the participant signed (ISO 8601). <code>null</code> before signing.

occupiedboolean

Whether the signing room is currently held (locked) by this participant.

Example response

{
  "internalTrackingId": "b4a9b3f1-c8d0-4e2a-b5f6-b7c8d9e0a1b2",
  "participantId": "c60d31fa-f335-4957-872a-90b035632081",
  "name": "Anna Muster",
  "roles": [
    "SIGNER",
    "RECEIVER"
  ],
  "hashedPrimaryValue": "5f4dcc3b5aa765d61d8327deb882cf99",
  "signedByUserEmail": "anna.muster@example.ch",
  "effectiveSignerUserEmail": "delegate@example.ch",
  "sequenceIndex": 1,
  "rejectedReason": "Wrong recipient",
  "signedAt": "2026-09-01T14:22:07Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.