---
title: "Update a participant of a running signing process (ADMIN-only)."
method: PATCH
path: "/epost/signing/processes/{processId}/participants/{participantId}"
tags: ["ePost Sign"]
---

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

`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

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> &mdash; 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 &mdash; <code>hashedPrimaryCredential</code>, <code>hashedPrimaryValue</code>, <code>derivedHashedCredentials</code>, <code>derivedHashedValue</code>, <code>unhashedCredentials</code>, or <code>allCredentialShouldMatch</code> &mdash; 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> &mdash; 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> &mdash; 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.

## Path parameters

- `participantId` string, uuid, required
- `processId` string, uuid, required

## Request body

- ParticipantUpdate
  - `roles` string[]: 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.
  - `hashedPrimaryCredential` string: Which credential is hashed as the primary key (e.g. <code>email</code>, <code>mobileNumber</code>). Omit to keep the current value.
  - `hashedPrimaryValue` string: Hash of the primary credential value. Omit to keep the current value.
  - `derivedHashedCredentials` string[]: Names of the additional credentials mixed into the derived hash. Omit to keep the current value.
  - `derivedHashedValue` string: Hash of the derived credential combination. Omit to keep the current value.
  - `unhashedCredentials` object: Full participant credentials &mdash; submission only. Never returned by <code>GET</code> endpoints. Omit to keep the current value.
    - `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.
  - `allCredentialShouldMatch` boolean: If <code>true</code>, every supplied credential MUST match to resolve the participant. Omit to keep the current value.
  - `sequenceIndex` integer: 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.
  - `signatureFields` SignatureField[]: Signature field positions for this participant. When supplied, replaces the current fields as a whole; empty list = SwissSign default placement. Omit to keep the current value.
    - `fieldName` string: Logical name of the signature field on the PDF form (matches the AcroForm field name when present).
    - `pageIndex` integer: Zero-based index of the PDF page the field is placed on.
    - `x` number, double: X coordinate of the field's lower-left corner (PDF points).
    - `y` number, double: Y coordinate of the field's lower-left corner (PDF points).
    - `width` number, double: Width of the field (PDF points).
    - `height` number, double: Height of the field (PDF points).
  - `status` object: Only <code>REMOVED</code> is accepted &mdash; 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>.

## Response `200`

Updated participant.

- ParticipantStatus
  - `internalTrackingId` string, uuid: Process-local participant id. Stable, also while the participant is unresolved. Use this to address the participant on <code>PATCH</code>.
  - `participantId` string, 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).
  - `name` string, 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.
  - `roles` string[]: Role(s) held by this participant within the process.
  - `status` object: Current signing status of this participant.
  - `deliveryStatus` object, nullable: Delivery progress of the initial document to this participant, independent of the signing <code>status</code> above.
  - `hashedPrimaryValue` string, nullable: Correlates the returned participant with the hash the caller submitted.
  - `signedByUserEmail` string, nullable: Email of the ePost account in whose name the signature was made (account owner). <code>null</code> before signing.
  - `effectiveSignerUserEmail` string, nullable: Email of the user who actually signed (e.g. a shared-account user). <code>null</code> before signing.
  - `sequenceIndex` integer, nullable: 1-based order (<code>SEQUENTIAL</code> mode). <code>null</code> in <code>PARALLEL</code> mode.
  - `rejectedReason` string, nullable: Reason provided when the participant refused to sign. <code>null</code> otherwise.
  - `signedAt` string, date-time, nullable: Timestamp at which the participant signed (ISO 8601). <code>null</code> before signing.
  - `occupied` boolean: Whether the signing room is currently held (locked) by this participant.

## Other responses

- `400`: Body invalid, or <code>status</code> supplied but not equal to <code>REMOVED</code>.<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.
- `403`: ePost Sign widget not subscribed, or caller is not an <code>ADMIN</code> of this process.<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.
- `404`: Resource not found<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.
- `409`: Participant is no longer in an editable state (not <code>PENDING</code> / <code>FORCED_ONBOARDING</code>), or the change would leave the process without any <code>ADMIN</code>.<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.
- `422`: Validation failed on the request body, or a credential change re-matches to multiple accounts.<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.
- `500`: Something went wrong on our side while processing the request. Please kindly contact our support.<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)